Short answer: put in CLAUDE.md what Claude cannot work out by reading the code and needs on every task: how to build and test, the conventions that are not enforced by a tool, and the things it must never do. Leave out general advice, anything your linter already checks, and long instructions for one kind of task. Keep it short; mine is about forty lines.
Claude Code reads CLAUDE.md at the start of every session, before your first message. That makes it the most valuable space in your project, and the easiest to fill with things that do not help.
Where can CLAUDE.md live?
| File | Read for |
|---|---|
~/.claude/CLAUDE.md | You, in every project |
CLAUDE.md or .claude/CLAUDE.md at the project root | Everyone in the project (commit it) |
CLAUDE.md in a subfolder | Work in that folder, read when Claude goes there |
Run /init in a new project to have Claude draft one from the code, and /memory to open the files that are loaded. A line like @docs/testing.md imports another file, so a long section can live where it belongs.
What earns a line?
- Commands. How to install, build, run one test, run all tests, lint. The exact commands, not "use the usual tools".
- What the code does not tell you. "The
legacy/folder is frozen; never edit it." "Prices are integers in cents." "Staging and production share one database." - Conventions a tool does not enforce. Naming of branches, where new components go, how errors are reported.
- Hard limits. "Never run migrations against production." "Ask before adding a dependency."
- How you want to work. "Make a plan and wait for a yes before editing more than three files."
What does not?
- General advice. "Write clean, readable code" changes nothing.
- Rules your tools already check. If ESLint or Prettier enforces it, Claude will hear about it from them.
- Long how-tos for one task. Release steps, a migration checklist, how to write a new endpoint: move them into a skill, which is read only when that job comes up. See Claude Code skills.
- Facts that go stale. Version numbers, who owns what, lists of files. They will be wrong in a month, and a wrong fact is worse than none.
- Secrets. The file is committed and read into every session.
What does a short example look like?
# Project notes for Claude
## Commands
- Install: `pnpm install`
- One test: `pnpm test -- path/to/file.test.ts`
- All checks before you finish: `pnpm lint && pnpm typecheck && pnpm test`
## Things the code does not say
- Money is stored as integer cents. Never use floats for it.
- `src/legacy/` is frozen. Do not edit it; wrap it instead.
## How to work here
- Ask before adding a dependency.
- For changes across more than three files, show a plan first.Where can you check this?
How do I know it is working?
Watch for the same correction twice. If you tell Claude "we use pnpm, not npm" in two sessions, that line belongs in CLAUDE.md. If a line has been there for months and you cannot remember it mattering, try deleting it.
Config Studio for Claude Code has CLAUDE.md among its 20 surfaces: it shows every file one can live in, in order of precedence, and starter packs to begin from instead of a blank page.
