Guide · Short, specific, true
CLAUDE.md best practices
What to put in CLAUDE.md so Claude Code gets your project right the first time, and what to leave out.
Last updated
CLAUDE.md is a Markdown file that Claude Code reads at the start of every session. It's the place for facts Claude can't easily work out from your code: which commands to run, how the parts fit together, and the traps. Because it's loaded every time, every line costs tokens in every session. Keep only lines that earn their place. Where it lives
| File | Use it for |
|---|---|
~/.claude/CLAUDE.md | Your personal rules for every project (how you like to work, tools you always use) |
CLAUDE.md in the project root | Project facts. Commit it so your team and every session share it. |
CLAUDE.md in a subfolder | Rules for one part of a big repo. Claude picks it up when it works in that folder. |
Run /memory in Claude Code to see which files are loaded and open one to edit.
1Start with /init
In your project, run:
/init
Claude scans the repo and writes a first CLAUDE.md. Treat it as a draft: read every line, delete what's obvious, and add what only you know.
2Put in what Claude can't guess
- Commands, especially the ones that differ from the default (a build script that does extra steps, how to run one test, a Node version to switch to first).
- The big picture: how the parts connect when it takes several files to see it.
- Traps: things that look fine but break, and why.
- Where to add things: "a new page also needs an entry in X and Y".
3Leave out what it can find
- File trees and lists of every component: Claude can list files itself, and the list goes stale.
- Generic advice like "write clean code" or "add tests": it changes nothing.
- Long docs. Link to them instead, or import them only where they're needed (see step 5).
- Secrets. The file is committed and sent with every request.
4Be specific, and say why
| Vague | Specific |
|---|---|
| Build the project properly. | Build with npm run build, not ng build: it also writes the CSP header. |
| Be careful with browser code. | Every page is prerendered, so window and localStorage only work inside afterNextRender. |
| Keep the sitemap updated. | New page? Add it to public/sitemap.xml too. |
The "why" matters: with a reason, Claude can handle the cases your rule didn't spell out.
5Import, don't paste
To pull another file into CLAUDE.md, write its path after an @:
See @README.md for the project overview. Release steps: @docs/releasing.md
Imported files are loaded too, so they cost the same as pasting them. Use imports to keep one source of truth, not to add more text.
6Keep it up to date
When Claude makes the same mistake twice, add one line that prevents it. When a line stops being true, delete it: a wrong instruction is worse than none. Review changes to CLAUDE.md like code changes.
A real example
This is the (shortened) CLAUDE.md for this website:
# CLAUDE.md AH Dev Studio: a small Angular 22 site, fully prerendered to static HTML and hosted on Cloudflare Pages. ## Commands Run `nvm use 22.22.3` first. - npm start: dev server at http://localhost:4200 - npm run build: ng build + scripts/csp.mjs. Always use this, not bare ng build, for a deployable build. - Single test: npx ng test --include src/app/app.spec.ts --watch=false ## Architecture - Every route is prerendered. Code touching window or localStorage must run browser-only (afterNextRender). - Adding a page: route in app.routes.ts, plus public/sitemap.xml (and public/rss.xml for guides). - scripts/csp.mjs hashes inline scripts after the build. New external origins must be added to its policy.
No file tree, no "write good code". Each line is something Claude would otherwise get wrong.
CLAUDE.md is getting long, Claude follows each rule less reliably, and it costs tokens in every session. More on that in how to save tokens in Claude Code.