Chapter 1 · Practice 2 of 4
Write only what the assistant cannot work out from the code
Why it matters
Claude Code's best practices give a clear test for every line: "Would removing this cause Claude to make mistakes?" If not, cut it.
| Include | Leave out |
|---|---|
| Build, test and lint commands it cannot guess | Anything it can learn by reading the code |
| Code style rules that differ from defaults | Standard language conventions |
| Testing instructions and the preferred runner | Detailed API docs (link instead) |
| Branch naming and PR conventions | Information that changes often |
| Architecture decisions specific to the project | Long tutorials |
| Environment quirks, such as required env vars | File-by-file descriptions of the codebase |
GitHub's guidance for repository instructions suggests similar content: what the repository does, step-by-step build and test commands with tool versions, known errors and workarounds, and key file locations.
Example
# AGENTS.md
## Commands
- Install: pnpm install
- Test one file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit (run before saying a task is done)
## Conventions
- Server code lives in src/server; never import it from src/components
- Money is stored in integer cents; never use floats for amounts
## Gotchas
- Tests need DATABASE_URL pointing at the local Docker database