Every Claude Code setup lives or dies by one file. Not the model, not the prompts you type at 2 AM - the CLAUDE.md sitting at the root of the repo. It is the first thing the agent reads and the only thing it reads every single time.
I have reviewed a lot of these files, and the bad ones fail in predictable ways. They are either novels nobody would read, wish lists with no enforcement, or walls of style rules the model ignores because nothing says what matters most. Here is the structure that actually works, section by section.
1. Identity and mission (2-3 sentences, no more)
Open with what the project is and what the agent's job is. Not marketing copy - operational context.
This is a B2B invoicing API in TypeScript (Fastify + Postgres). You are the
primary maintainer. Prioritize correctness of money math over speed. When in
doubt, ask before changing anything under /billing.
That last line does real work. It tells the agent where the blast radius is.
2. Commands that must work
The agent will run things. Tell it exactly which commands are the source of truth so it does not invent npm run test:quick and hallucinate success.
- Install: `pnpm install`
- Test: `pnpm test` (must pass before every commit)
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint --fix`
Agents are surprisingly obedient here. If you give them the exact command, they run the exact command. If you do not, they guess, and guesses fail silently.
3. Hard rules, stated as rules
This is where most files go soft. "Try to avoid committing to main" is a suggestion. Write rules like a linter would:
- NEVER commit directly to main. Always create a feature branch.
- NEVER use `git push --force` on shared branches.
- NEVER commit files matching .env* or containing API keys.
- ALWAYS run `pnpm test` before committing. No exceptions.
The ALL-CAPS markers are not for style. Models weight emphatic, absolute language more heavily, and these are the rules you most want to survive a long context window.
4. Architecture map (the 60-second version)
Agents waste enormous effort exploring. Give them the map:
/src/routes - HTTP handlers, thin by design
/src/domain - business logic, no I/O allowed here
/src/db - migrations and queries
/tests - mirrors /src structure
Five lines saves dozens of exploratory tool calls per session.
5. How to verify work
This is the section almost everyone skips, and it is the one that changes behavior the most. Define what "done" means:
A task is done when: tests pass, typecheck is clean, the commit message
follows conventional commits, and you have re-read your own diff for
obvious mistakes.
Without this, agents declare victory after the code compiles. With it, they self-review.
6. What the agent is NOT allowed to do
Boundaries prevent the most expensive mistakes:
Do not: modify CI configuration, change database migrations that have
already been applied, add dependencies without asking, or touch anything
under /infra.
What to leave out
Three things do not belong in CLAUDE.md: your entire style guide (link it), exhaustive API docs (the agent can read code), and anything you would not enforce in review (every unenforced rule teaches the model that rules are optional).
The test of a good one
Read your CLAUDE.md and ask: if a talented contractor read only this file, could they work in this repo without asking me a single question for the first hour? If not, that gap is exactly what your agent is silently guessing about.
If you want this structure without writing it from scratch, I packaged a production-tested version into the Agentic Coding Kit - a CLAUDE.md template with these six sections, plus the git hooks that enforce the hard rules even when the model forgets them, review subagents, and slash commands. But the anatomy above is the real takeaway: identity, commands, hard rules, map, definition of done, boundaries. Everything else is decoration.
Top comments (0)