Skip to content

AGENTS.md

Latest commit

 

History

History
126 lines (95 loc) · 6.53 KB

AGENTS.md

File metadata and controls

126 lines (95 loc) · 6.53 KB
Raw

Overview

This is the Coinbase Design System (CDS) - a cross-platform component library. Primary language: TypeScript Package manager: yarn Task runner & monorepo tooling: Nx Runtime: NodeJS (see .nvmrc for version)

CDS ships on four product platforms across three toolchains:

Product platform Implementation Toolchain
Web React Node
Mobile React Native Node
Native Android Kotlin/Jetpack Compose Gradle
Native iOS Swift/SwiftUI Xcode

This root file contains repository-wide guidance. A package-level AGENTS.md is authoritative for work in that package and may add stricter local rules. In particular, read packages/cds-android/AGENTS.md before Kotlin work and packages/cds-ios/AGENTS.md before Swift work.

Agent Guidelines

  • NEVER make commits without being instructed to do so directly
  • Never commit secrets or credentials, log restricted PII, or remove or weaken security controls
  • Ask focused clarifying questions when ambiguity would materially change the implementation
  • ALWAYS look for relevant skills and rules you can apply before beginning your work

Core Commands

  • yarn install - Install dependencies
  • yarn nx release plan - Writes an nx release version plan describing your change
  • yarn release - Applies pending version plans, writing new versions and CHANGELOG entries. Wraps nx release --skip-publish; publishing is CI's job. See docs/release.md
  • yarn clean - Removes all build artifacts, deletes .nx folder and resets the Nx daemon
  • yarn nx reset - Reset Nx daemon cache

Verification

After writing code, validate the smallest relevant scope:

  • Node: run tests for the modified files, typecheck and lint the modified projects, then run yarn nx format:write
  • Gradle: run the changed project's test and build targets; Prettier does not format Kotlin
  • Xcode: run cds-ios:test and the changed project's build target; Prettier does not format Swift
  • Documentation only: run yarn nx format:write and verify changed commands and links

See docs/testing.md for exact commands.

Nx and toolchains

ALWAYS run Nx commands using the formats demonstrated by the commands below.

  • yarn nx show projects - Show all projects in the workspace (project names differ from package names)
  • yarn nx affected --target=test - Run tests only for affected projects
  • yarn nx run <project>:build - Build any project through its assigned toolchain
  • yarn nx run <project>:test - Run tests for a specific project
  • yarn nx run <project>:test --testNamePattern=<pattern> - Run tests matching pattern
  • yarn nx format:write - Formats all files in the workspace with Prettier
  • yarn nx run <project>:lint - Lint a specific project
  • yarn nx run <project>:typecheck - Check for type errors in a specific project
  • yarn nx run-many --target=<target1>,<target2> - Run targets for all projects
  • yarn nx run-many --target=<target1>,<target2> --projects=<project1>,<project2> - Run targets for specific projects

Every project has exactly one of toolchain:node, toolchain:gradle, or toolchain:xcode. Common targets use build and, where supported, test. Specialized targets such as launch and xcframework remain project-specific. See docs/nx.md for why the root target defaults remain Node-oriented, and docs/ for setup and CI architecture.

Architecture

  • Platform implementations live in packages/web, packages/mobile, packages/cds-android, and packages/cds-ios.
  • Shared Node functionality lives in packages/common; Kotlin and Swift cannot import TypeScript packages.
  • Development apps are apps/storybook, apps/expo-app, apps/android-app, and apps/ios-gallery.
  • android/ is the Gradle root. ios/ is the Xcode workspace umbrella.
  • Components generally colocate implementation, tests, stories, and Figma bindings where the toolchain supports them.

Native package guidance

  • For Kotlin/Compose implementation rules, API boundaries, token details, and releases, follow packages/cds-android/AGENTS.md.
  • For Swift/SwiftUI implementation rules, API boundaries, token details, and releases, follow packages/cds-ios/AGENTS.md.
  • Load the jetpack-best-practices skill when writing Compose.
  • Load the swiftui-best-practices skill when writing SwiftUI or migrating a RN component to packages/cds-ios.
  • Load the cds-rn-to-compose skill when porting mobile components to packages/cds-android or auditing Android/mobile parity.
  • Do not copy package-local consumer or release rules into this root file.

Skills

Repository-specific skills live in skills/ and .claude/skills/. Load the relevant skill before working in its domain. Skills under skills/ use a README.md and may include an evals/ directory with benchmark test cases.

After running skill evals

If a skill has evals and you run them, update the skill's README.md with a ## Performance section containing the latest benchmark results:

  • Overall summary table: pass rate, avg time, avg tokens — with/without skill and the delta
  • Per-eval breakdown table showing each task name and pass rates for each configuration
  • A callout of the biggest gains (where the skill adds the most value)
  • The iteration number and date for traceability

See skills/cds-code/README.md for a reference example.

Standards & Best Practices

General

  • We prefer quality over quantity for unit tests: focus on high-quality tests that provide outsized value before writing exhaustive test cases for coverage.
  • Prefer constants over magic numbers: replace hard-coded values with descriptively named constants in camelCase
  • Use meaningful names: variables and functions should reveal their purpose
  • Code is self-documenting: code shouldn't need comments unless it is unusually complex in which case add brief comments where appropriate
  • NEVER use exports marked as deprecated in the codebase when writing code or a plan.

React

  • Always memoize CDS components with memo HOC
  • Use useMemo for expensive computations or for computed/conditional styles
  • Use useCallback for event handlers passed as props to other components
  • Use useEffect only for side effects (e.g API calls, subscriptions, browser API calls, etc.)
  • Consult React's docs if you feel you need a useEffect for something else (https://react.dev/learn/you-might-not-need-an-effect)