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

A developer outlines best practices for crafting an effective CLAUDE.md file, emphasizing brevity and specificity to avoid wasting context. The post advises including only project details, directory structure, build commands, and critical conventions, while omitting personality instructions and rules already enforced by tools. A leaner file improves Claude's reliability by reducing noise.

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. 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. 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. 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 important one. Pruning is not tidying — it is what makes the file work. CLAUDE.md loads into Claude's context every session, and performance degrades as context fills. A leaner file is not just easier to read — it makes Claude more reliable, because the rules that matter are not competing with filler for attention. Short is not a style choice here. It is a performance requirement. Free starter: The format, a complete annotated example, and the one-line test are all on a free cheat sheet: CLAUDE.md Quick-Start Cheat Sheet https://promptmasterstore.gumroad.com/l/claude-md-cheat-sheet Go deeper: The full guide covers the entire configuration stack — hooks, subagents, commands, skills and plugins — with real-world walkthroughs and a 30-day plan: CLAUDE.md: The Complete Claude Code Configuration Guide https://promptmasterstore.gumroad.com/l/claude-md-configuration-guide What is the one rule in your CLAUDE.md that has saved you the most? Share it in the comments.