Documenting Commands & Workflows in CLAUDE.md

Of everything that goes in CLAUDE.md, precisely-documented commands have the fastest, most measurable payoff: the difference between an agent that runs the exact right test command on the first try and one that spends several turns discovering it by trial and error.

Be Exact, Not Approximate

<!-- Vague — forces the agent to guess or explore -->
## Commands
Run tests to verify changes.

<!-- Exact — no guessing required -->
## Commands
- Run all tests: `npm test`
- Run a single test file: `npm test -- src/utils/parser.test.ts`
- Run tests matching a name pattern: `npm test -- -t "parses dates"`
- Watch mode during development: `npm test -- --watch`

The vague version forces the agent to either explore package.json scripts itself (costing time and turns) or guess at conventional command names that may not match this project’s actual setup. The exact version eliminates that entirely.

Cover the Full Development Loop

A genuinely useful commands section covers everything a contributor would need on their first day, not just the most obvious one or two:

## Commands

### Setup
- Install dependencies: `npm install`
- Set up local database: `npm run db:setup`
- Seed test data: `npm run db:seed`

### Development
- Start dev server: `npm run dev`
- Start with debug logging: `DEBUG=app:* npm run dev`

### Testing
- Full suite: `npm test`
- Single file: `npm test -- path/to/file.test.ts`
- With coverage: `npm test -- --coverage`

### Quality
- Lint: `npm run lint`
- Lint with autofix: `npm run lint -- --fix`
- Type-check: `npm run typecheck`
- Format: `npm run format`

### Build & Deploy
- Production build: `npm run build`
- Preview production build locally: `npm run preview`

This structure — grouped by phase of the development loop — makes it easy for both humans and the agent to find the right command quickly, and easy to keep updated as commands change (you know exactly which section a new command belongs in).

Document Non-Obvious Sequencing

Some workflows have ordering requirements that aren’t obvious from the individual commands alone:

## Database Migrations

1. Write the migration: `npm run migrate:create -- add_users_email_index`
2. Review the generated file in `migrations/` before running it
3. Apply locally: `npm run migrate:up`
4. Never edit a migration file after it has been merged to main — write a new
   migration to correct it instead

Step 4 here is exactly the kind of gotcha that a bare command list wouldn’t communicate — the sequence and constraints matter as much as the individual commands.

Environment-Specific Variants

Where commands genuinely differ by environment or context, say so explicitly rather than leaving it implicit:

## Testing

- Unit tests (fast, run constantly): `npm run test:unit`
- Integration tests (require Docker, slower): `npm run test:integration`
- E2E tests (require a running server, run in CI only — do not run locally
  unless explicitly asked): `npm run test:e2e`

That last line — telling the agent when not to run something — is as valuable as telling it when to.

Common Mistakes

Documenting only the “npm test” happy path and omitting how to run a single file or a subset — this is precisely the case where an agent iterating on one specific failing test benefits most, and precisely the case a vague command list fails to serve.

Letting the commands section drift out of sync with package.json. A stale command that no longer exists (renamed, removed) sends the agent down a dead end — commands should be updated in the same PR that changes the underlying script.

Omitting setup/first-run commands because “everyone on the team already has it set up” — an agent starting fresh in a new environment (a CI runner, a fresh container) benefits from the same first-run instructions a new human contributor would need.

Frequently Asked Questions

Should I document every single npm script, even obscure ones? Prioritize the ones actually used day-to-day — a comprehensive package.json scripts dump duplicates information already available in that file; CLAUDE.md’s commands section should curate the commands worth knowing without exploring, not exhaustively catalog every script.

What about commands that require secrets or credentials to run? State that requirement explicitly (“requires AWS_PROFILE to be set — see .env.example”) rather than letting the agent discover the failure and have to diagnose it from an opaque error.

Should deployment commands be included, given the risk of an agent accidentally running them? Document them for reference, but pair genuinely risky commands (production deploys, database migrations against prod) with an explicit note that they require human confirmation before running — the documentation itself doesn’t grant permission to execute freely.

Summary

Precise, complete command documentation is the fastest win in any CLAUDE.md — exact invocations (including single-file/single-test variants), grouped by development phase, with non-obvious sequencing and environment-specific caveats called out explicitly. It’s also the easiest category to keep accurate, since it maps directly onto files (package.json, CI config) that already exist and change under version control alongside it.