You wrote a detailed CLAUDE.md, and Claude Code still gets things wrong — wrong convention, touches files it should not, ignores rules you clearly wrote down. The cause is almost never that the rules are missing. It is that they are buried.
The over-specified file problem
CLAUDE.md loads into Claude's context every single session, and performance degrades as that context fills. When the file grows too long, something counterintuitive happens: Claude starts ignoring parts of it. The important rules get lost in the noise, and the genuinely critical instructions sit too deep to reliably influence output.
A bloated file does not just waste tokens. It actively makes Claude less reliable, because it cannot tell which of your hundred lines is the one that matters.
The trap of good intentions
It always starts reasonably: "let me put everything relevant in here." But relevant is a low bar. The file grows until it is impossible to scan, full of duplication, and so noisy that the truly important rules carry no weight. More content felt like more control. It was the opposite.
The fix: prune ruthlessly
Run every line through one question: "If I remove this, will Claude make a mistake?" If the answer is no, the line is noise — delete it.
And if something only matters in a specific situation rather than always, it does not belong in the always-loaded file at all. That is what skills and subdirectory CLAUDE.md files are for — they load on demand, only when relevant.
Let Claude fetch what it needs
Instead of embedding everything, tell Claude how to pull context when it needs it. Rather than pasting an entire API guide into the file:
# Wasteful - embeds the whole file every session:
@docs/api-guide.md
# Better - Claude reads it only when relevant:
For Stripe integration work, read docs/stripe-guide.md
The second form costs almost nothing until the moment it is needed.
The result
A pruned CLAUDE.md is often a third of the length and many times more effective. The rules that matter are no longer competing with noise, so Claude actually follows them. If your CLAUDE.md is being ignored, the fix is almost never to add emphasis — it is to cut until only what matters remains.
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
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
Have you hit the point where Claude started ignoring your CLAUDE.md? How long had it gotten? Curious to compare notes below.
