How to Structure a CLAUDE.md
A CLAUDE.md that grows by accident turns into a wall of text, and Claude skims a wall of text the way people do. Structure keeps it short, easy to search and easy to follow.
The rule
Short, specific, sectioned: every line something a newcomer could act on.
Short. Every line is loaded into every session and costs context each time. Aim for something you can read in a minute. Move long material, such as a deployment guide or an architecture write-up, into its own file and point to it. CLAUDE.md can also import another file by writing its path after an @, but an import is loaded every session too; a plain pointer ("see docs/deploy.md before deploying") keeps the material out of context until it is needed.
Specific. "Format Python with ruff format" can be followed and checked. "Write clean code" cannot.
Sectioned. Headings let Claude, and your teammates, find things. A pattern that works for most projects:
- About: one or two lines on what the project is.
- Commands: build, run, test, lint.
- Map: only the non-obvious parts of the layout.
- Rules: conventions and hard limits.
- Workflow: how to verify and commit.
- Gotchas: known traps.
Give reasons. "Keep pricing in pricing.py, because the billing tests import it directly" lets Claude apply the rule to cases you did not list.
Say what to do, not only what to avoid. "Put new price rules in pricing.py" points somewhere; "don't put prices in the routes" leaves Claude guessing where they should go instead.
Emphasise sparingly. Mark the one or two rules that matter most as IMPORTANT. If everything is important, nothing is.
The shortcut
Test each line: could a new teammate act on this tomorrow? If they could not, Claude cannot either. Vague: rewrite it as a command or a concrete rule. Obvious: delete it. Long: move it out.
The messy version
"Please write good clean code and be careful with pricing and tests and don't break stuff. app.py is a Python file." Then an 80-line deployment guide.
Drills
Answer fast — trust the rule.
Which is the better line for a CLAUDE.md?
Your CLAUDE.md contains an 80-line deployment guide that is rarely needed. What should you do?
Why not mark every rule as IMPORTANT?
What single test does the shortcut apply to each line?
Remember
- Short, specific, sectioned: every line something a newcomer could act on.
- Shortcut: rewrite the vague, delete the obvious, move the long.
- Trap: a growing wall of text in which the one critical rule is buried.