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 whole skill is knowing what belongs in it — and, just as importantly, what does not. The sections that earn their place Start with a one or two line project description and your stack, with version numbers. Claude infers 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. Then a directory map — not every file, just the top-level layout with a 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. # Project: Acme Dashboard Next.js 15 (App Router), TypeScript, Drizzle ORM, Vitest. ## Structure src/app/ # routes and pages src/lib/ # shared utilities, db client db/migrations/ # generated - never hand-edit ## Commands Build: npm run build Test: npm run test ## Conventions - API routes return { data, error } - never throw to client - Server components by default ## Do not touch - db/migrations/ is generated. Never edit by hand. Every line in that file would cause a mistake if removed. That is the bar. What to leave out This is where most files go wrong. Two kinds of content waste your budget: Personality instructions. "Act as a senior engineer," "think step by step," "be thorough." These feel productive but change nothing — Claude already does them. General advice that does not prevent a specific mistake is pure noise. Rules a tool already enforces. If you have a formatter or linter, do not restate what it enforces. Wire it into a hook instead, and keep CLAUDE.md for what tools cannot enforce. The one-line test For every line, 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. A bloated file buries the rules that matter in noise, so Claude cannot tell which line is the