What to put in CLAUDE.md: one test for every line
By Christophe Paka · Facts checked on 23 October 2026
"Do you guys ever clean up your CLAUDE.md or just keep adding to it?" one reader asked. "I'm not even sure it reads half of it anymore." The file started short. Every bad day added a line.
A long file costs room in every session, and Claude follows it less. So what to put in CLAUDE.md? Only what Claude cannot read or guess. The figure below sorts the usual lines into two columns and ends on one question you can ask of each.

Use this diagram on your site
Free to share in your blog post, docs, course or slides, as long as the credit link stays. Paste the code below where the figure should go.
How to read this figure
Read the green Include column. CLAUDE.md is a short note Claude reads at the start of every session. The left column, under a green header, lists what belongs in it: commands Claude can't guess, such as build, a single test or deploy, and style rules that differ from defaults.
Finish the Include list. Next come testing instructions, architectural decisions and why, environment quirks and gotchas, and repo etiquette for branches and commits. Last is where key things live, with the example API handlers: src/api/handlers/.
Read the Leave out column. The right column lists what to cut: anything Claude can read from code, standard language conventions, and API docs it can fetch or read. Then often changing facts such as versions, file by file descriptions, and write clean code platitudes.
Stop at the last Leave out line. Secrets, API keys and credentials: never, especially if committed. An API key is a password that lets a program use a service. Claude reads the file every session, and you usually commit it to git.
End at the litmus test box. Both columns point down to one question: would removing this cause Claude to make mistakes? If not, cut it. A line earns its place only when it fixes a mistake Claude would make without it.
Key takeaways
- Open your CLAUDE.md and ask the litmus test of every line; cut each line that fails it.
- Write commands and paths exactly: Run npm test before committing beats Test your changes.
- Add a line when Claude makes the same mistake twice, or you type the same correction again.
Worked example: a CLAUDE.md for a small expenses app
The book builds a CLAUDE.md for one small app that adds up receipts. Every line fixes something Claude could not guess.
- Commands: run all tests with
npm test, and one test file withnpm run test totals. Claude cannot guess the second one. - Where things live: receipts.csv holds sample data to keep, totals.js adds up, index.html is the page.
- Gotcha: amounts in the CSV are in cents, so divide by 100 only to show them. Only you know this trap.
- Left out: a tour of each file, habits Claude already knows, and any secret.
Result: The whole file fits on one screen. Ask Claude to change the page title and check nothing broke: it runs the test command from the file without you naming it.
Questions readers ask
What's in your CLAUDE.md?
The lines that win share one trait: they fix a mistake Claude really made. Exact commands, where key things live, rules that differ from the usual, and traps you learned the hard way. Readers rate one line highest: verify, don't trust, so Claude checks its own summary against the source.
Do you guys ever clean up your CLAUDE.md or just keep adding to it?
Prune it after something goes wrong, not only add to it. Aim for under 200 lines per file. A 600 line file does not make Claude obey more; it buries the five rules that matter. Then watch behavior: rerun a prompt that used to go wrong.
Are generated CLAUDE.md files good or bad practice?
A good start, if you cut. /init reads your project and writes a draft. Then ask the litmus test of every line it wrote. Which file loads first is in the CLAUDE.md hierarchy.
Sources: How Claude remembers your project (Claude Code docs); Best practices (Claude Code docs).
This figure is from Claude Code Made Crystal Clear, chapter 5.
The chapter builds the idea step by step, with recipes you can follow, a Try it to check yourself, and every source.
Get the book


