CLAUDE.md: Persistent Project Memory
What belongs in project memory (commands, gotchas, style rules), what doesn't, and keeping it true as an operating manual.
What CLAUDE.md is
CLAUDE.md is a markdown file that Claude Code reads automatically at the start of every conversation in your project. It's persistent memory: everything a fresh session needs to know before touching your code, without you re-explaining it each time. Run /init and Claude generates a starter by scanning the repo — then your job is to prune it relentlessly.
Think of it as the onboarding doc you'd hand the brilliant new hire from the prompting module. Not the company handbook — the one-pager of things that would otherwise burn their first week.
What belongs, what doesn't
| Include | Exclude |
|---|---|
Bash commands Claude can't guess (npm run test:unit -- --watch=false) | Anything Claude can read from the code itself |
| Style rules that differ from language defaults | Standard conventions ("use meaningful variable names") |
| How to run tests, and which tests to run when | Long tutorials or API documentation |
| Repo etiquette: branch naming, commit format, PR rules | Aspirational process docs nobody follows |
| Environment quirks (Node version, env vars, flaky services) | Detailed domain knowledge used only sometimes |
| Gotchas that have actually caused mistakes | Praise, filler, restating the obvious |
The litmus test for every line: "Would removing this cause Claude to make a mistake?" If not, cut it. This isn't just tidiness — a bloated CLAUDE.md actively hurts. Every line competes for attention with your real instructions, and models start ignoring an overlong rule file precisely when you need it followed.
A concrete example of a line that earns its place:
# Workflow
- Typecheck after a series of edits: npm run typecheck
- Prefer running single tests, not the whole suite (full suite ~10 min)
That second line saved a real team from Claude running ten-minute full test runs after every small change. It passes the litmus test: removing it demonstrably causes wasted time.
Where memory files live
CLAUDE.md is not one file but a hierarchy, loaded in order:
~/.claude/CLAUDE.md— global: your personal preferences across all projects../CLAUDE.md— project root, checked into git: the team's shared memory../CLAUDE.local.md— gitignored: your personal notes for this project.- Parent directories — for monorepos: a root file covers all packages.
- Child directories — loaded on demand when Claude works with files there.
Two syntax features worth knowing. You can import other files with @path/to/file — useful for pointing at an existing doc instead of duplicating it. And you can tune adherence with emphasis: adding IMPORTANT or YOU MUST to a line measurably increases compliance — spend that currency sparingly, on the rules that matter most.
Treat it like code
The file compounds in value only if it stays true. Three habits:
Review it when things go wrong. Claude did something odd? First question: does CLAUDE.md say anything about this — or worse, say the wrong thing? A stale rule ("tests live in /spec" after they moved) is worse than no rule.
Test changes by observing behavior. After editing, watch whether Claude's behavior actually shifts. It's a prompt — and prompts are tested, not assumed.
Check it into git. The project file belongs in version control so the whole team contributes, gotchas accumulate, and fixes ship to everyone at once.
The escape valve: move sometimes-relevant knowledge to skills
The pressure that bloats CLAUDE.md is real: there is lots of context that's occasionally useful. The answer isn't a bigger file — it's skills, covered later in this module. CLAUDE.md is loaded always; a skill is loaded on demand when relevant. Domain knowledge needed for one workflow (release steps, a migration guide, PDF-form handling) goes in a skill, costing ~30-50 tokens of overhead until the moment it's needed.
The division of labor:
- CLAUDE.md: what every session needs — commands, rules, gotchas. Small and always-on.
- Skills: what some sessions need — workflows, domain expertise. Larger and on-demand.
Keep that split honest and both stay effective. A good CLAUDE.md reads like a well-maintained operating manual: short, current, and boring — every line there because its absence caused a real mistake once.