How do I write a CLAUDE.md that actually makes Claude Code useful?
TL;DR
Write it for a smart contractor joining on day one: what not to touch, how decisions get made, what the architecture looks like, and where to find things.
CLAUDE.md is Claude Code's persistent memory. Every session starts by reading it. The goal is to eliminate the questions a good developer would ask in their first week.
What belongs in CLAUDE.md
1. Decision-making principles (most important)
The highest-value content is "never do X without asking me first" and "when you see Y, always do Z." These prevent the irreversible mistakes.
Example:
## URL/SEO Changes: NEVER Do Without Approval
- Never rename working URLs — even with 301s, you lose link equity
- Never delete pages with traffic — check analytics first2. Architecture map
Where is the thing? What pattern does it follow? What's the source of truth?
Example:
## Two-Repo Architecture
| Repo | Purpose |
|------|---------|
| FrankX | Private development |
| frankx.ai-vercel-website | Production — deploys to frankx.ai |3. Brand/voice rules
What the output should sound like. What phrases are banned. What the positioning is.
4. Environment and tooling
Where secrets live, how to run the dev server, what commands run what, what the deploy flow looks like.
What to leave out
- Step-by-step instructions for things Claude already knows (e.g., "to create a file, use the Write tool")
- Philosophy without action criteria (e.g., "we value quality" without specifying what that means operationally)
- Outdated information — a stale CLAUDE.md is worse than none because it actively misleads
Format guidance
- Use tables for mappings, matrices, comparisons
- Use code blocks for exact commands, exact phrases to avoid
- Keep sections short — Claude reads the whole file every session; density beats completeness
- Put the most critical rules (destructive operation gates, brand terms) near the top