TheMost CLAUDE.md files are a graveyard of rules the agent quietly ignores. Ours was too — around two hundred lines of good intentions, of which maybe five actually changed what the agent did. The other hundred and ninety-five were decoration: rules it skimmed, contradicted, or silently overrode while we congratulated ourselves on having "guidelines."
So we ran an audit. Here is the exact five-step cut, with the reasoning — steal it.
1. Instrument before you edit
For one week, don't touch the file. Instead, tally every time the agent skips a line. No guessing, no vibes — a count. Open a scratch note, and every time you catch the agent doing the thing an instruction told it not to do (or not doing the thing it was told to do), mark which line failed.
The lines that never fire are your audit list. You cannot delete confidently until you know which rules are actually load-bearing, and you will be surprised in both directions: rules you loved that never once fired, and one sleeper line that turns out to be doing all the work.
2. Delete anything obeyed zero times
An instruction the model never follows isn't guidance — it's decoration. And it isn't free: every dead line dilutes the lines that do work, because instructions compete for the model's attention. A 200-line file doesn't give you 40× the control of a 5-line file. It gives you a model skimming, weighting early tokens, and treating your painstaking style guide as ambient noise.
Delete without ceremony. If it never fired in a week of instrumentation, it was never real.
3. Kill contradictions
"Be concise" sitting three lines above "explain your reasoning thoroughly" cancels out. The model doesn't throw an error on contradiction the way a compiler would — it just picks one, effectively at random, per response. Which means your output quality has a coin-flip in it that you put there.
Find every pair of rules that can't both be satisfied and pick the winner yourself. You are the tiebreaker. If you can't decide, the agent certainly can't.
4. Rewrite the vague ones until they're testable
"Write clean code" is unfollowable — there is no moment where the model can check whether it complied. "No function over 40 lines" either passed or it didn't. The test for every surviving rule: could a reviewer (human or machine) look at the output and answer yes or no on whether the rule was followed?
If the answer is "well, it depends" — rewrite until it doesn't, or delete it. Vague rules don't just fail; they train you to believe instructions don't work, which makes you write more of them, which makes everything worse.
5. Collapse to five lines
Shorter files get followed more. Every rule you keep is attention taken from the others, so the question is not "is this rule good advice" — most advice is good — but "is this rule worth weakening the other four for." What survives that bar is what you actually meant all along.
Five is not a magic number; it's a forcing function. If you genuinely need seven, take seven. But make the number hurt a little, or the graveyard grows back.
The receipts
We ran this on the lab's own repo. The result: a five-line core that the agent follows essentially every time, and a measurable drop in "why did it do that" moments — because when a rule fails now, we notice, and the audit list has exactly one suspect.
Instrument, delete the dead lines, kill contradictions, make each rule testable, cap it at five. Receipts beat theory — save this one.