CLAUDE.md is the agent's onboarding doc. It is the difference between an agent that asks where db.ts lives every session and an agent that opens it and reads it.
I have been writing these for 14 months across 20-plus repos. The shape that works is the same every time. The shape that does not work is also the same every time. Here it is.
Skip the writing entirely if you want and just use the CLAUDE.md Generator. It encodes everything below into a fillable form.
The shape that works
Eight sections. In this order.
1. Stack
One sentence per dimension. Language, framework, package manager, test runner, deploy target. That is it. Not a history lesson. The agent does not need to know why you picked Postgres over Mongo in 2024.
2. Commands
Six lines. Dev, build, test, typecheck, lint, deploy. Copy-pasteable. The agent will run them. If a command needs a flag your CI uses, write the flag.
The mistake: writing "run the tests" instead of "pytest -xvs". Agents do not infer flags. They run what they read.
3. Agent posture
One paragraph. Tells the agent how aggressive to be.
Three postures work in practice:
- Conservative. Plan before code on every task. Confirm before edits. Useful in compliance-heavy repos.
- Balanced. Plan for changes touching more than 3 files. Confirm on production paths. The default.
- Aggressive. Default to action. Confirmation only on protected paths. Useful for greenfield repos.
Pick one. Write it down. Now the agent has a posture to fall back to when the task is ambiguous.
4. Definition of done
Five bullets, in order:
- Tests pass.
- Typecheck passes.
- Lint passes.
- Build succeeds.
- Manual sanity-check in dev.
This list is the most undervalued section in any CLAUDE.md. Without it, the agent will hand you "done" while the lint is still red.
5. Production-sensitive paths
A list of paths that require human confirmation. Mine usually includes:
terraform/.github/workflows/- Anything under
migrations/ordb/migrations/ - Anything touching auth tokens or session handling
The agent reads this list and treats those paths as suspicious. Good.
6. House rules
Six to eight bullets. Mine:
- Plan before writing code on tasks larger than one file.
- TDD on every behavior change.
- One commit per logical change.
- Match existing patterns in the file before introducing new ones.
- No new dependencies without explicit approval.
- Never silently catch errors.
- Never bypass pre-commit hooks.
Your house rules are not the same as my house rules. Write yours.
7. Recommended hooks
Point to your .claude/settings.json. List which hooks are enabled and why. If you have a budget guard, name the cap. If you have a profile allowlist for AWS, name the file.
If you do not have hooks yet, the Hooks Builder takes about three minutes.
8. Token budget
One line. The cap. Mine is 200,000 tokens per task. Sessions that approach the cap should stop and ask the human to slice the task smaller, not keep iterating.
The shape that does not work
The two failure modes I see over and over:
Mode 1: a stale CLAUDE.md. The repo moved on, the doc did not. The agent is now hallucinating file paths and recommending scripts that were retired. Fix: a quarterly review on the calendar. Twenty minutes.
Mode 2: a CLAUDE.md that reads like onboarding for a junior engineer. Three pages of history. Diagrams. Architecture rationale. The agent does not need the rationale. It needs the commands and the constraints. If you want the rationale, put it in ARCHITECTURE.md and link.
How long should it be
Most of mine land between 80 and 160 lines. If yours is over 300 lines, you are writing a book, not a config file. The agent will read it. It will also dilute the parts that actually constrain behavior.
Auditing your existing CLAUDE.md
Three checks. Each takes a minute.
- Open the file. Try every command in the Commands section. If one fails or no longer exists, the doc is stale.
- Search the doc for any file path. Does the path still exist? If not, the doc is stale.
- Ask the agent: "Read CLAUDE.md and tell me three things you would do differently with this guidance vs without it." If the answers are vague, the doc is doing nothing.
Receipts
- 20-plus repos with tuned
CLAUDE.mdfiles. - Median agent first-try correctness improvement after introducing this format: 22 to 38 percent on internal evals.
- Median session length reduction on cross-cutting tasks: 31 percent (fewer "where does X live" round trips).
- Most common single fix on a stale doc: updating the Commands section.
If you want this generated for your repo in 30 seconds, the generator is here. If you want me to audit your real one, that is the engagement.