What to Put in Your CLAUDE.md (and What to Leave Out)

A great CLAUDE.md is not the longest one. It is the one where every line changes what Claude does. The difference between a file Claude follows and one it ignores comes down to knowing what belongs in it — and, just as importantly, what does not.

The Sections That Earn Their Place

Open with a one or two line project description and your stack, with version numbers. Claude can infer a lot from your code, but it will not guess that you are on Next.js 15 instead of 14, or which ORM you chose. State it plainly.

Then a directory map — not every file, just the top-level layout with a brief note on what each part holds. After that, the build and test commands, the conventions a formatter does not enforce, and critically, the things not to touch: generated code, migrations, legacy modules.

A Complete Example

A strong CLAUDE.md might open with "Next.js 15 App Router, TypeScript, Drizzle ORM, PostgreSQL, tests with Vitest," followed by a short structure map, the build and test commands, a couple of project-specific conventions like "API routes return a data-or-error shape, never throw to the client," and a clear "do not touch" note that migrations are generated and must never be hand-edited. Every line would cause a mistake if removed.

What to Leave Out

This is where most files go wrong. Two kinds of content waste your budget. First, personality instructions: "act as a senior engineer," "think step by step," "be thorough." These feel productive but change nothing — Claude already does them. Second, rules a tool already enforces: if you have a formatter, do not restate what it enforces. Wire it into a hook instead and keep CLAUDE.md for what tools cannot enforce.

The Test for Every Line

For every line in your CLAUDE.md, ask: "If I remove this, will Claude make a mistake?" If yes, keep it. If no, delete it. This single question, applied ruthlessly, is the difference between a file Claude follows and one it ignores — because a bloated file buries the rules that matter in noise.