Keep a CLAUDE.md That Actually Changes the Output

A discipline for the CLAUDE.md file that Claude Code reads at the start of every task: keep it to rules that actually change behaviour — real commands, real conventions, real boundaries — and ruthlessly cut anything the model would do correctly anyway.

CLAUDE.md is standing context loaded on every run, so bloat has a permanent cost: it dilutes attention and buries the three rules that matter under twenty that don't. A tight file that says how to run the tests, which patterns this repo uses, and what never to touch changes the output on every task; a wall of generic 'write clean code' advice changes nothing and crowds out signal.

Any repo you use Claude Code in more than once — especially ones with non-obvious build steps, house conventions that differ from the language default, or dangerous areas (migrations, generated files, vendored code).

A one-off exploration you'll never return to. And don't paste your whole style guide in — link the specifics that Claude gets wrong, not the ones it already gets right.

Read the repo and draft a CLAUDE.md. Include only things that would change how you work here and that you couldn't infer correctly on your own:
- exact commands to build, test, lint, run;
- conventions this repo follows that differ from the language default;
- files/areas you must not edit without asking;
- non-obvious gotchas you'd otherwise trip on.
Cut anything generic. Keep it under a page.

A good CLAUDE.md says 'run pnpm test:unit, not npm test; API errors use the Result type in lib/result.ts, never thrown; never edit db/schema.generated.ts.' Every future task inherits that, so you stop re-explaining it in each prompt.

When you catch yourself correcting Claude Code the same way twice, add that correction to CLAUDE.md — the file becomes a record of your repo's real traps, tuned by the mistakes it actually makes rather than the ones you imagine it might.

• Filling it with generic advice ('write readable code') the model already follows.
• Letting it rot — a stale command in CLAUDE.md is worse than none, because it's confidently wrong.
• Documenting what the code already makes obvious instead of the non-obvious gotchas.