CLAUDE.md Files Grow 226% and Almost Never Shrink

Agentic instruction files grow 226% over their lifetime, per an analysis of 247,694 instruction lifetimes across 1,867 repositories.

That's a maintenance problem for anyone running an AI coding agent against a shared instruction file. Instructions gain 4.9 net additions per commit. Older ones get less likely to ever be deleted, with the log-hazard of deletion dropping 0.032 per commit.

The researchers call this catastrophic remembering, the mirror image of catastrophic forgetting. They trace it to a cost asymmetry: appending a new rule is nearly free, but deleting one safely means reconstructing reasoning nobody wrote down. That verification cost scales as O(2^|D|) with the number of instructions already in the file.

The fix the researchers tested was simple. Adding comments that record the reasoning behind each instruction, not just the instruction itself, removed 99.3% of excess instructions in verifiable settings. It also improved real-world instruction-following on WildIFEval by up to 23.1%.

The take

Teams write CLAUDE.md files like changelogs: append the fix, ship it, move on. That's the cheap half of the cost asymmetry the paper describes. The expensive half, verifying an old rule is safe to cut, never happens. Files survive editing well when every rule carries its reason inline, because a visible why lets a future editor cut it with confidence. Rules without a reason just pile up until nobody wants to touch the file at all.