Writing CLAUDE.md Files That Actually Work
CLAUDE.md is loaded at every session start — every byte costs tokens. This article covers the exact content that belongs in CLAUDE.md, what to leave out, effective structural patterns, and the token economics that should shape every decision you make about it.
Quick Reference
- →CLAUDE.md is auto-loaded at session start from ~/.claude/CLAUDE.md, ./CLAUDE.md, and subdirectory CLAUDE.md files
- →More specific CLAUDE.md files override more general ones — same CSS specificity model
- →/init generates a starter CLAUDE.md by analyzing your codebase
- →/memory (or the command 'open CLAUDE.md') lets you edit it from inside Claude Code
- →Every line in CLAUDE.md costs tokens on every session start — keep it lean
- →The 'new engineer test': include what a competent new hire would need that's not obvious from code
- →Outdated instructions are worse than missing ones — they actively mislead Claude
- →Under 500 lines is the sweet spot — split larger configs with @import and .claude/rules/
In this article
How CLAUDE.md Gets Loaded
Claude Code discovers CLAUDE.md files automatically at session start. It doesn't require you to point to them — it looks in a set of standard locations and loads everything it finds.
| Location | Scope | Committed to git? |
|---|---|---|
| ~/.claude/CLAUDE.md | Every project on your machine | No — personal preferences |
| ./CLAUDE.md (project root) | Everyone on this project | Yes — shared team knowledge |
| ./.claude/CLAUDE.md | Everyone on this project (alt location) | Yes |
| ./src/api/CLAUDE.md | Only when working in ./src/api/ subtree | Yes |
| CLAUDE.local.md (project root) | You only, this project | No — gitignored |
The load order goes from most general to most specific, with more specific files taking precedence on conflicts — exactly like CSS specificity. User-level applies everywhere; directory-level only applies when Claude is working in that directory subtree.
Run /init in your project root to generate a first draft from your codebase. Claude analyzes package.json, directory structure, config files, and produces a reasonable starting point. Then use /memory (or tell Claude 'open my CLAUDE.md') to edit it without leaving the session.
What to Put in CLAUDE.md
The question 'what goes in CLAUDE.md?' has a reliable answer: anything that a competent senior engineer joining the team today would need to know that is NOT obvious from reading the code or README. This is the 'new engineer test'.
| Include | Why |
|---|---|
| Tech stack and exact versions | Claude's training data has many versions — specificity matters |
| Naming conventions that differ from language defaults | Not obvious from one file |
| Architecture and directory structure | No one reads the whole repo on day one |
| Testing patterns and tools | Many frameworks have different conventions |
| Non-obvious project constraints | Claude can't infer business rules from code |
| Common pitfalls and gotchas | Mistakes Claude would otherwise make repeatedly |
| Dev workflow (how to run, test, build) | Required for verify phase to work |
What NOT to Put in CLAUDE.md
Every line in CLAUDE.md is re-loaded on every session start. Lines that don't add value are pure token waste. More dangerously, incorrect lines actively mislead Claude — a stale instruction is worse than no instruction.
| Exclude | Reason |
|---|---|
| Obvious language features ('TypeScript has interfaces') | Claude already knows this |
| Content that duplicates linter/formatter config | Claude reads those files directly |
| Long tutorials or how-tos | Use @import to reference them only when needed |
| Full API documentation | Use @import — don't always load docs you rarely need |
| Personal preferences | Those belong in ~/.claude/CLAUDE.md, not the shared file |
| Frequently changing information | It will go stale and mislead — use git log instead |
| Security secrets or API keys | Never put credentials in any committed file |
If CLAUDE.md says 'use Redux for state management' but you migrated to Zustand six months ago, Claude will follow the stale instruction. Delete or update CLAUDE.md entries whenever the corresponding convention changes — treat it like code.
Effective Structure Patterns
A well-structured CLAUDE.md is easy to scan, easy to maintain, and easy for Claude to use. Here are the patterns that work in practice:
Lead with tech stack
The most information-dense content goes first. Tech stack, versions, and key dependencies. Claude uses this to calibrate everything else it reads.
Follow with conventions
Naming conventions, export patterns, architectural rules. These are the things Claude would otherwise have to infer from reading many files — save it the trouble.
Include dev workflow
How to run, test, and build. Claude needs these to execute the verify phase correctly. Without them, it will try to guess (often incorrectly) or ask you every time.
End with gotchas
Non-obvious constraints, common mistakes, external system quirks. This is the highest-value section — it prevents errors Claude would otherwise make repeatedly.
Under 500 lines, CLAUDE.md loads cheaply and stays readable. Beyond that, split domain-specific rules into .claude/rules/ files with glob patterns so they only load when relevant. A 2,000-line CLAUDE.md that's always loaded is worse than a 200-line CLAUDE.md plus targeted rules files.
Token Economics: The Cost of Every Line
CLAUDE.md is loaded at the start of every session. On a team where every engineer runs multiple Claude Code sessions per day, the token cost of CLAUDE.md multiplies fast. This is not a reason to make CLAUDE.md sparse — the context it provides is worth the cost. But it is a reason to be precise.
| CLAUDE.md size | Approx tokens | % of 200K window |
|---|---|---|
| 100 lines (~3KB) | ~750 tokens | 0.4% |
| 300 lines (~9KB) | ~2,250 tokens | 1.1% |
| 500 lines (~15KB) | ~3,750 tokens | 1.9% |
| 1,000 lines (~30KB) | ~7,500 tokens | 3.75% |
| 2,000 lines (~60KB) | ~15,000 tokens | 7.5% |
A 500-line CLAUDE.md consuming 3,750 tokens is a very reasonable investment — that context shapes every interaction in the session. A 2,000-line CLAUDE.md with duplicate content, stale instructions, and verbose tutorials consuming 15,000 tokens is not. Precision matters more than comprehensiveness.
CLAUDE.md as a Team Artifact
Because CLAUDE.md is committed to the repository, it is a team artifact subject to the same process as code. This has powerful implications for how you maintain it.
- ▸CLAUDE.md changes should go through code review — a wrong instruction propagates errors across every AI-assisted change
- ▸When a convention changes, update CLAUDE.md in the same PR as the convention change
- ▸New team members should read CLAUDE.md as part of onboarding — it serves double duty
- ▸Use CLAUDE.md as the authoritative answer to 'how do we do X here?' — if Claude can answer it from CLAUDE.md, so can any engineer
Best Practices
Do
- ✓Generate with /init, then review and refine the output — don't ship the raw /init output
- ✓Apply the 'new engineer test' to every section — would a competent new hire need this?
- ✓Update CLAUDE.md in the same PR as any convention change to prevent stale instructions
- ✓Keep it under 500 lines — split larger configs with @import and .claude/rules/
- ✓Commit CLAUDE.md to git — it is shared team knowledge
Don’t
- ✗Don't put personal preferences in the project CLAUDE.md — use ~/.claude/CLAUDE.md
- ✗Don't let CLAUDE.md go stale — a wrong instruction is worse than no instruction
- ✗Don't duplicate content from your linter config, tsconfig, or other config files
- ✗Don't store secrets or credentials in any CLAUDE.md file
- ✗Don't skip the review step when generating with /init — always refine the draft
Key Takeaways
- ✓CLAUDE.md is loaded fresh on every session start — every line costs tokens every time
- ✓Use the 'new engineer test': include what a competent new hire needs that code can't convey
- ✓Stale instructions mislead Claude — update CLAUDE.md whenever a convention changes
- ✓Keep it under 500 lines; split domain-specific rules with @import and .claude/rules/
- ✓CLAUDE.md is a team artifact — commit it, review changes, maintain it like code
Video on this topic
Writing a CLAUDE.md That Actually Helps Claude Code
tiktok