What Should Go in Your CLAUDE.md?
Only what Claude Code can't work out by reading your repo: the exact commands that prove work is done, places where the code misleads, decisions that never made it into the code, and anything you've corrected twice. Anthropic's docs say to target under 200 lines per file, and many repos need far fewer.
Audit my CLAUDE.md. For each line, ask two questions: could you find this by reading the code, and would you actually go and look? If both answers are yes, propose deleting the line. Then propose additions only for: - the exact commands to install, run one test file, typecheck and lint, checked against [package.json / Makefile / pyproject.toml] - patterns in the code that new code must not copy, such as [legacy folder] - decisions that aren't in the repo, such as [which error helper we use, how deploys work] - corrections I've had to make twice: [list them] Move anything that matters for only one folder into a .claude/rules/ file with a paths: filter. Keep the file under 200 lines. Show me the diff, and don't apply anything until I say so.
- 1Commands that prove the work is donetest, typecheck, lint
- 2Places where the code misleadsold patterns not to copy
- 3Decisions that aren't in the repodeploys, error helper
- 4Anything you've corrected twiceadd as it happens
Try it now
- 1In your project, run
/init. It generates a starting file, or suggests improvements if aCLAUDE.mdalready exists. - 2Delete every line that tours your folders or says something like "write clean code". Add the command that runs one test file.
- 3Run
/doctor prompt-audit(v2.1.283 or later). It flags instructions written for older models, references to files that no longer exist, and contradictions. Nothing changes until you ask Claude to apply the edits. - 4Run
/context alland look under Memory files. If your file is listed there, it loaded.
Use it when
Any repo you come back to. The memory docs name the moments to add a line: Claude makes the same mistake a second time, a code review catches something it should have known, you type a correction you also typed last session, or a new teammate would need the same context.
Skip it when
Skip it for a one-off session in a repo you won't return to, since the file only pays back across sessions. Don't use it for a rule with no exceptions: Never edit src/gen/ belongs in a hook or deny rule, because Anthropic says CLAUDE.md lines are followed nearly every time, not every time. Long procedures, such as a release runbook, belong in a skill at .claude/skills/<name>/SKILL.md, which loads its full text only when needed.
Why it works
Claude Code loads CLAUDE.md into every session, so each line takes a little attention on every task, relevant or not. The memory docs say longer files use more context and reduce adherence. The file is context, not enforced configuration, so the model still decides whether a line applies. Anthropic's test before you add anything has two questions: could Claude find this by reading the code, and would it actually go and look? If both answers are yes, leave it out. That's why its best-practices page now lists describing your architecture and file layout as advice you can drop.
Example
Anthropic's own sample is six rules under three headings: pnpm install, pnpm vitest run path/to/file.test.ts for one test file, pnpm tsc --noEmit for the typecheck, use the helpers in src/lib/errors.ts and never throw raw strings, don't copy patterns from src/legacy/, and integration tests need DATABASE_URL set. Notice what's missing: no folder tour and no general advice. The typecheck line is only the command, so Claude can check its own work. If you need a passing typecheck enforced, that's a job for a Stop hook.
Going further
Block-level HTML comments, such as <!-- maintainer note -->, are stripped before the content reaches Claude, so notes for humans cost no tokens. @path imports tidy a long file but don't cut its cost, because imported files load along with it, up to four hops deep. Path-scoped rules do cut it: a .claude/rules/api.md with paths: frontmatter loads only when Claude works on matching files. One trap: from v2.1.277, Claude Code reads your AGENTS.md when there's no CLAUDE.md, but adding a personal CLAUDE.local.md counts as having one and stops that by default.
Common mistakes
- Adding IMPORTANT or capital letters to a line Claude keeps missing. Anthropic's docs say that probably won't fix it: either the file is too long, or the line belongs in a hook.
- Writing rules nobody can check.
Test your changesgives Claude nothing to verify, whereRun npm test before committingdoes. - Putting personal preferences in the shared file. Those go in
CLAUDE.local.md, added to.gitignore. - Leaving instruction files in conflict. All discovered files are joined together rather than overriding each other, so when two lines contradict, the docs say Claude may pick one arbitrarily.
Sources
Checked 6 November 2026. Products change often, so confirm details with the vendor.