The short answer
- What it is: a Markdown file Claude Code reads automatically and treats as standing instructions — project (repo root) or global (
~/.claude/CLAUDE.md). - What goes in: how to run & test, conventions Claude gets wrong, patterns to prefer or avoid, non-obvious architecture. Nothing the code already makes obvious.
- The golden rule: short, specific, imperative. A tight one-liner beats a paragraph every time.
- The real win: turn the corrections you keep repeating into written rules — most never get captured at all.
What CLAUDE.md is
CLAUDE.md is a plain Markdown file that Claude Code loads
at the start of a session and treats as instructions it should follow
without being reminded. There are two kinds:
| File | Location | Use it for |
|---|---|---|
| Project | Repo root — ./CLAUDE.md | Build/test commands, this codebase's conventions and architecture |
| Global | ~/.claude/CLAUDE.md | Your personal preferences across every project |
When they conflict, the project file wins — repo-specific rules override your global defaults, which is exactly what you want.
What to put in it
The test for every line is simple: would I otherwise have to say this out loud? If yes, it belongs. Good candidates:
- How to run and test. The exact commands —
pnpm test,cargo build, the lint step. This alone saves Claude from guessing wrong. - Conventions it keeps getting wrong. Naming, file layout, imports, formatting quirks your linter enforces.
- Prefer / avoid. "Use the existing
api.tsclient, not raw fetch." "No new dependencies without asking." - Non-obvious architecture. The one boundary or gotcha a newcomer always trips on.
What to leave out
Most weak CLAUDE.md files fail by including too much, not too little. Skip:
- Anything Claude can read from the code. It can see your file tree and dependencies — don't narrate them.
- Aspirational essays. A paragraph of philosophy gets skimmed; a one-line rule gets followed.
- Rules you don't actually enforce. Contradictions between the file and the codebase teach Claude to trust neither.
Write rules that get followed
Same content, very different hit rate depending on how you phrase it:
| Instead of | Write |
|---|---|
| "We generally try to keep components small where possible." | "Keep React components under 150 lines; split beyond that." |
| "Be mindful about adding dependencies." | "Don't add npm packages without asking first." |
| "Testing is important to us." | "Run pnpm test before saying a task is done." |
The pattern: imperative, specific, checkable. A rule Claude can verify it followed is a rule it follows.
The habit that matters most
Here's the thing almost everyone misses. The value of CLAUDE.md isn't the file you write once — it's the corrections you'd otherwise repeat forever. Every time you tell Claude "no, not like that" and it's the third time, that's a rule that should already be written down.
Most of those corrections never make it into the file. You fix it in the moment, the session ends, and next week you fix it again. The single highest-leverage CLAUDE.md habit is closing that loop: when you correct the same thing twice, write it down. Spotting the repeats usually means reviewing your Claude Code session history rather than trusting memory.
A minimal starter
You don't need much. A solid project CLAUDE.md can be this short:
## Commands- Test: pnpm test- Build: pnpm build## Conventions- Indent with tabs. - Use the existing api.ts client, not raw fetch.- No new dependencies without asking. - Run tests before calling a task done. |
Start there, then let it grow one captured correction at a time. A CLAUDE.md that reflects your real, repeated feedback beats any template you copy off the internet.
Frequently asked
What is a CLAUDE.md file?+
A plain Markdown file Claude Code reads automatically at the start of a session and treats as standing instructions. A project CLAUDE.md lives in the repo root; a global one at ~/.claude/CLAUDE.md applies everywhere. It records the conventions, commands and preferences you want followed without repeating them.
What should I put in a CLAUDE.md?+
The things you'd otherwise repeat: how to run and test, conventions Claude keeps getting wrong, patterns to prefer or avoid, and non-obvious architecture. Keep each rule short and specific, and leave out anything Claude can infer from the code itself.
Where does CLAUDE.md go — global or project?+
Use a project CLAUDE.md in the repo root for anything specific to that codebase, and the global ~/.claude/CLAUDE.md for personal preferences across all your work. Project rules override global ones when they conflict.
Why does Claude keep ignoring my CLAUDE.md?+
Usually it's too long, too vague, or contradictory. Short, imperative, specific rules are followed more reliably than paragraphs. Tighten the wording rather than adding more — and make sure the correction you keep making is actually written down, because most never make it into the file.
Stop repeating the same corrections.
Dinoradar's CLAUDE.md Coach finds the fixes you keep making and turns them into rules that stick. Free forever · Pro $29 once.