Three sessions in, you notice you keep typing the same three sentences. The test command. The folder that is generated and must not be edited. The convention nobody wrote down.
Write them once instead.
What CLAUDE.md is
A file in your project that Claude Code reads automatically when it starts there. Whatever is in it applies to every session in that project, without you saying anything.
You can also keep a personal one under your home directory’s .claude folder for preferences that follow you across every project — how you like explanations, conventions you always want. Project rules go in the project; personal habits go with you.
Let it draft the first one
Claude Code has an /init command that inspects the project and writes a starting CLAUDE.md for you. Use it — then read every line and cut what is not true. A generated file full of confident wrong statements about your project is worse than no file.
What to actually put in it
The test that a line belongs: would I otherwise say this at the start of every session?
Commands. How to run the tests, the dev server, the build. This is the highest-value section, because it turns the agent from “suggests a command” into “runs the right command”.
Boundaries. Generated folders, vendored code, anything that must not be edited by hand.
Conventions that are not obvious from the code. “Dates are stored as UTC strings.” "New API routes go in src/api/, one file per route."
The thing that bit you. Every time you correct the same mistake twice, that correction has earned a line.
Write the exercise version below: create a CLAUDE.md with the test command and one hands-off folder.
Quick check
Which of these earns a line in CLAUDE.md?
Keep it short
Every line is in front of the agent every session, competing with everything else for attention. A tight file of fifteen useful rules beats three hundred lines of aspirational style guide, every time.
Prune it the way you prune code. If a rule has never changed an outcome, delete it. If you find yourself correcting the same thing despite a rule, the rule is probably vague — make it concrete and specific.
It is instructions, not a guarantee
A rule in CLAUDE.md makes the right behaviour far more likely. It is not an enforcement mechanism — the agent can still get it wrong, and you still review. If something must never happen, back it with a permissions rule, which is the last lesson of this level.
Split it when it grows
Large projects often want per-area instructions — a note in the folder that owns the API, another where the UI lives. Claude Code supports pulling other files into your instructions with an @path/to/file reference, so the root file can stay a short index instead of a monolith.
Start with one file and fifteen lines. Split it when it hurts, not before.
Should CLAUDE.md be committed to Git?
What if the agent ignores something in it?
Try it yourself
The same correction, for the third time.