CLAUDE.md: the file that decides how good Claude Code is

The starting mistake is treating CLAUDE.md as technical documentation. People dump the full architecture into it, the rationale behind every choice, the history of the project. The file swells, and its value drops.

This file is a table of contents. Its job is not to contain everything, it is to say where everything lives. Where the code sits, which commands to run, which conventions to respect, and which documents to open for the detail.

The blank page is the real reason this file does not exist in most projects. Nobody knows where to start, so nobody starts.

You do not have to write the first version yourself. From your project root:

claude

Then, inside the session:

/init

Claude Code walks the project, picks up the stack, the scripts, the folder layout and the recurring patterns, then generates a starting CLAUDE.md from it. You go from nothing to a structured base in one command.

This is where most people stop. They run /init, see a file appear, decide it is done, and move on. The result is a file that correctly describes the surface of the project and misses everything that matters.

What /init produces is a starting point, never a finished deliverable. It needs a line-by-line review.

A structure that holds on just about any project, in this order.

At the end of the file, add the pointers to deeper documentation: the spec file, the contributing guide, the database schema. One line per pointer, with the exact path.

The tip almost everyone ignores, and the one with the most impact.

A CLAUDE.md that swells dilutes its own instructions. When a critical rule is buried in six hundred lines of context, it carries less weight in the agent's attention than it would among eighty. You do not get more compliance by writing more, you get less.

Two hundred lines is the official target, and the stated reason is exactly that trade-off: longer files eat more context and reduce adherence. Past that point, you have started pasting documentation instead of pointing to it.

Here is the point guides on this topic almost always skip, and it completely changes how you hold the previous tip. CLAUDE.md is not a single file, it is a layered system where every level stacks.

The benefit is immediate: your root file no longer has to carry the rules of every sub-area of the project. You push the detail down to the level where it applies, and the root stays under your two hundred line ceiling.

The detail that makes this genuinely pay off: subfolder files are not loaded at startup. They enter the context only when the agent touches files in that folder. In other words, you can be precise and detailed in src/api/CLAUDE.md without spending a single line of context on the sessions where you are not working on the API.

A CLAUDE.md written once and then forgotten goes stale within weeks. Commands change, conventions evolve, and the file turns into a source of errors instead of a source of truth. The problem is not willpower, it is timing: nobody opens their editor to document a rule in the middle of a task.

The fix is to capture the rule at the exact moment it shows up, without leaving your session. There is nothing special to learn: ask in plain language, and the agent saves it to memory.

Remember that tests run with npm run test:unit, never with npx jest directly.

That is three seconds instead of a round trip through your editor, and it is the whole difference between a living file and a dead one.