03 · Best practice
Make CLAUDE.md the single source of truth
Product, voice, architecture, and conventions live in one file Claude reads on every session.
CLAUDE.md is the file Claude Code reads on every session start. It's where your project's rules, voice, architecture decisions, and agent strategy live. If you find yourself re-explaining the same constraints in every chat, the constraints belong here.
Aakash Gupta's framing: "This is where you place rules, behaviours, architecture and agent strategy." Anthropic's official guidance is just as direct: it shares the context window with everything else, so be concise. Every token costs.
How to do it
Copy templates/CLAUDE.md from this repo into the root of your project.
Fill in: product, team, stack, voice, agents, and what Claude should never do.
Keep it under 500 lines. If a section grows past that, split it into a file in docs/ and reference it from CLAUDE.md.
Re-read it monthly. Cut what's stale.
What goes in it
- Product — what we sell, who buys, what we don't sell.
- Team — roles, who decides what; tag-mention conventions.
- Stack — what's installed, what's banned (e.g. "do not introduce a new state-management library").
- Voice — how we write (tone, banned words, sentence patterns).
- Agents and skills — pointers to the skills installed in
skills/. - Architecture decisions — short rationale for each big choice.
- What Claude should never do — destructive commands, schema changes, customer-facing copy without review.
What does not belong in it
Anything that changes weekly. Roadmap items, sprint goals, current OKRs — those go in docs/product.md. The CLAUDE.md file should be true in three months without edits.
Anti-patterns
- A
CLAUDE.mdover 1,000 lines. It's a system prompt budget, not a wiki. - Restating things Claude already knows ("React is a JavaScript library…"). Anthropic's docs are explicit about this.
- No "what not to do" section. You will regret this on day 14.
- Pasting a brain dump and never re-reading. Treat it like an onboarding doc.