Most CLAUDE.md files start the same way: five or six bullet points written in the first afternoon of a project — naming convention, package manager, "don't run migrations automatically." Six months later the same file is 300+ lines: half-finished notes from a refactor, a paragraph explaining a decision that got reversed, three slightly different phrasings of "use TypeScript strict mode" added by three different people who didn't check if it was already there. Nobody deletes anything, because nobody's sure what's still load-bearing.
The file still gets read in full on every single turn. That's the part people don't think through.
Length isn't the real problem — signal-to-noise is
A 300-line CLAUDE.md isn't bad because it's long. It's bad because a one-line rule that actually matters ("never touch billing.py, it's synced from another repo") sits at the same visual and semantic weight as forty lines of restated formatting preferences and a stale note about a library you migrated off of two quarters ago. The model has no reliable way to tell which of those lines should change its next action and which are just historical residue. Everything reads as equally "instructions," so nothing gets the emphasis it needs.
This is different from an instruction simply being ignored in a long session — it's noise actively competing with signal for the same attention budget, at every single turn, for the life of the project. A shorter file with the same important rule in it is more likely to get followed, not less, purely because there's less competing for the same slot.
A quick audit: read your CLAUDE.md and cut the dead weight
Go through your file line by line and ask, for each one: if I deleted this right now, would anything I do in the next hour actually change?
Common categories that fail that test and can usually go straight to the trash:
- Explanations of why a convention exists, when the convention itself is one line. Keep the rule, cut the essay.
- Instructions for a tool, framework, or file that no longer exists in the repo.
- Anything phrased as "please try to" or "remember to" for something that must happen every time without exception — that's not a CLAUDE.md line at all, it's a hook (a shell command wired to a lifecycle event, so it's not competing for attention because it isn't a request in the first place).
- Multi-step procedures you only run occasionally ("when doing a release, do A then B then C") — that belongs in a slash command you invoke on demand, not a standing instruction read on every unrelated turn.
- Duplicate phrasings of the same rule added at different times. Keep the clearest one, delete the rest.
What's actually worth keeping
What survives the cut tends to fall into a small set of categories: the shape of the project (where things live, what's generated vs. hand-written), naming and style conventions that aren't enforced by a linter, hard boundaries ("never," "always," specific files or directories that are off-limits), and non-obvious context a new contributor wouldn't guess — the kind of thing you'd tell a new hire in their first ten minutes, not their first week.
If it's procedural and deterministic, it's a hook. If it's a multi-step task you trigger on purpose, it's a command. If it's a standing fact about the project that shapes every decision, it's CLAUDE.md. Most bloat comes from putting the first two kinds of information into the third bucket because it's the easiest file to open and add a line to.
Prune on a schedule, not just when it hurts
The honest fix isn't a one-time cleanup — it's a habit. Every time you're tempted to add a line, check if an existing line already covers it. Every few weeks, re-read the whole file out loud (or have Claude summarize it back to you — if the summary surprises you, the file has drifted from what you think it says). A CLAUDE.md that's actively maintained at 40 tight lines beats one that grew to 400 and hasn't been fully read by a human in months.
A starter CLAUDE.md template with commented placeholder sections (so you begin from a short, deliberate structure instead of an empty file that grows unchecked), plus 12 slash commands, 6 subagents, 5 hooks, and a git-aware statusline, is packaged as the Claude Code Power Pack (copy-paste into .claude/, €29): https://vincentdu2a.gumroad.com/l/bqndfi. It's an independent, unofficial project — not affiliated with, endorsed by, or sponsored by Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic.
(Written with AI assistance.)
Top comments (0)