04
CLAUDE.md per project
Every repo we touch ships with a CLAUDE.md at its root. It is the contract between the codebase and the agents that work on it — conventions, boundaries, what to never do.
Placeholder method entry. Rewrite the body before launch.
A CLAUDE.md is a contract. It tells the agent — and the next human reader — what this codebase considers legal, what it considers forbidden, and what shortcut it will refuse to allow. It is not documentation. It is policy.
We write CLAUDE.md before we write a single feature. If the project already has code, we write CLAUDE.md by reading the code and codifying what is already true. The act of writing it surfaces the conventions nobody had bothered to say out loud.
Why
Without a CLAUDE.md, the agent regenerates the codebase’s accidental conventions on every prompt. With one, the agent’s output converges on intent. The same applies to the new engineer onboarding next month.
How we do it
- CLAUDE.md lives at the repo root, not in
/docs. - Sections: critical rules, project structure, commands, conventions, what NOT to do.
- It is reviewed at the end of every cycle. If the agent broke a rule, the rule is missing or wrong.
- Subdirectories that need their own rules get their own nested CLAUDE.md.