A CLAUDE.md that gets read.

Claude Code reads CLAUDE.md at the start of every session, so every line costs attention. Fifteen checks for what earns its place, then a starter file to copy.

0of 15 done

Your ticks stay in this browser, on this device. Nothing is sent anywhere.

01/Start it0/2

Run /init in your project.
Claude Code writes a first CLAUDE.md from your project's structure. Cut it down from there rather than starting blank.
Claude Code best practices ↗
Check it into git.
Everyone's agent reads the same rules, and a change to them gets reviewed like any other change.

02/Keep these0/6

The commands it can't guess.
How to run the tests, the type check and the dev server, wherever they differ from the defaults for your stack.
Rules that break the usual way.
Conventions your project departs from on purpose. The usual ones it already knows.
How to test, and with what.
The test runner, and whether to run one file or the whole suite.
Decisions it would otherwise undo.
A choice that looks wrong from the code alone, with the reason in one line.
The quirks of your setup.
A required environment variable, a service that has to be running, a port that's already taken.
What it must never do.
Edit generated files, change a migration that has already run, add a dependency without asking.

03/Cut these0/4

Anything it can read in the code.
A tour of your folders goes stale, and costs every session.
Rules every developer already follows.
"Write clean code" changes nothing it does.
Long docs and tutorials.
Link to them instead. Knowledge it needs only sometimes belongs in a skill, which loads when it's needed.
Anything that changes every week.
It will be wrong by next week, and the agent will believe it.

04/Keep it working0/3

Ask of every line: would removing it cause a mistake?
If not, cut it. A long file gets its important lines skipped, which is the advice in Anthropic's own best practices.
Claude Code best practices ↗
When a rule gets ignored, shorten the file first.
A skipped rule is usually lost in length. Mark one line as important, not ten.
Run /context to see it was loaded.
It shows what is in the session, CLAUDE.md included.

Copy/A starter file

CLAUDE.md

# Commands
- Tests: npm test (one file: npm test -- path/to/file)
- Type check: npm run typecheck
- Dev server: npm run dev

# Rules
- Before you say it's done, show the command you ran and what it returned.
- Never edit files in /generated: they are rebuilt.
- Never change a migration that has already run. Write a new one.
- Ask before adding a dependency.

# Why things are the way they are
- Prices are stored in pence, as whole numbers, so totals add up exactly.

Swap the commands for yours, keep the rules that apply, and add a line only when the agent got something wrong without it.