Why Does CLAUDE.md Keep Growing? Catastrophic Remembering in Agentic Coding
Kushal Chakrabarti
cs.AI, cs.LG, cs.SE
2026-08-12
Across 247,694 instruction lifetimes, agentic prompts only grow (+226%) from 'catastrophic remembering'; prompt comments cut 99.3% of the bloat and lift real instruction-following 23.1%.
Anyone who has used Claude Code or Cursor knows the file: CLAUDE.md, AGENTS.md, copilot-instructions.md. It tells the agent the project's red lines, style, and working habits. The file only gets longer. Over a repository's lifetime, instruction count climbs 226% on average, and almost nothing comes back out.
Not deleting is not laziness. Before you delete an instruction you need to know why it was added, which bug or which failure it was guarding. Once that rationale has been ground down across many commits, deleting it safely means running every subset of the other few dozen instructions to see whether some verifier starts failing again. That is an O(2^|D|) job, where |D| is the current instruction count. Adding an instruction costs a few keystrokes; deleting one costs a powerset traversal. Under that asymmetry, growth-only is close to the only stable state. The paper calls it catastrophic remembering, the exact dual of catastrophic forgetting from continual learning: there a gradient learner overwrites what it should have kept, here a maintainer keeps what they should have overwritten, and both fail for the same reason, the information that would license the update is gone.
The paper does three things: a large-scale measurement, a controlled experiment that isolates the mechanism, and a fix.
Measurement. The author decomposes CLAUDE.md, AGENTS.md, and copilot-instructions.md in 1,867 GitHub repos commit by commit into individual instructions, matches them across versions, and recovers 247,694 instruction lifetimes and 28,426 deletions. The matcher reaches 1.000 precision and 0.933 recall on 50 hand-annotated transitions. The key statistic is the deletion hazard, the probability that an instruction gets deleted at a given age.
Telling the mechanisms apart. Three candidates predict different signs. If instructions go stale, hazard should rise with age. If fragile instructions die young, a selection effect, hazard falls but only through composition. If maintainers lose the rationale (imperfect recall), hazard falls with age, and uniquely among the three, also with the number of people who have edited the file, because more authors dilute the original reasoning faster.
The fix: prompt comments. Borrowed straight from software engineering, where comments record why, not what. Each instruction gets a comment naming the failure behind it, the hypothesis, and the outcome, including how often it recurred. The comment is read only by the next maintainer and stripped before the prompt reaches the executor. Recording a comment is O(1); reconstructing the rationale later is O(2^|D|), so the comment banks the cheap version.
Evaluating the fix. The hard part is that a real prompt's optimal size is unknowable, so excess is unmeasurable. The author inverts IFEval: hide each item's original instructions and treat them as the known minimum cover D⋆, keep the verifiers as the hidden constraint set, and have a stronger model compress the instructions into a vague objective. A maintainer then relearns the instructions round by round from censored, noisy pass/fail feedback. For the first time, excess size (|Dt|/|D⋆| minus 1) is measurable.
The observational numbers are strong:
| Metric | Value |
| Instruction growth over file lifetime | +226% (mean) |
| Net instructions per commit | +4.9 (excluding mass rewrites) |
| Deletion hazard vs age | -0.032/commit (95% CI [-0.047, -0.019]) |
| Multi-author × age interaction | β = -0.021 (z = -11.7) |
| Instruction deaths in a wholesale rewrite or migration | 77.3% |
76.8% of instruction deaths come in a single commit that bulldozes the file: removing one instruction needs a reason, removing all needs none. More telling is what happens after a rewrite. The file drops to 59.5% of its prior size and climbs back to 91.5% within 10 commits, and it grows faster afterward (4.9%/commit against 4.1% before). The rewrite resets size, not growth rate, which is why the paper calls it a ratchet.
Hazard falling with age falsifies staleness outright, since staleness predicts a rise. A gamma frailty model, in its strongest form stratified by identical instruction text, absorbs 30.8% of the slope but leaves it at -0.0355. And the effect that more editors means a lower chance of deletion is something only imperfect recall predicts.
On the fix, the inverted-IFEval controlled study runs three arms: no comments, comment-shaped noise, and informative comments. At 15 rounds, excess falls from +60.4% (no comments) to -5.8% (informative), a 66.2-point cut, at parity constraint satisfaction. Stretched to 51 rounds, the no-comment arm inflates to +211.3% while the comment arm holds at +1.4%, removing 99.3% of the excess. Ablations show the comment must carry outcomes: a narrative of attempts with no outcomes is the worst arm at +70.0%, handing successors an unverified premise to extend, and dropping the recurrence-count field alone costs 37% of the reduction.
On real prompts, the same inversion applied to WildIFEval seeds a maintainer's prompt with noisy instructions borrowed from other items. Sixteen distractors cost 24.1 points of compliance on the true instructions already in the prompt. Comments lift satisfaction from 50.4% to 62.0% over three rounds, a 23.1% relative gain.
This is directly actionable. Pair every instruction in a CLAUDE.md with a one-line comment recording the failure it guards, the hypothesis, and the outcome, and strip it before the prompt reaches the model. It is the same discipline as commenting code. There is also a counterintuitive trend: as the maintainer gets stronger (here, swapping in a stronger agent maintainer), the ratchet tightens, and the no-comment arm's excess runs from +67.7% to +571.9%. The more capable the agent, the more this discipline matters, not less.
For anyone building coding agents, this is a product-level suggestion: give prompts a comment syntax so rationale survives between maintainers. The paper's prototype is only a prototype.
The author states the boundaries plainly. The controlled experiment runs in a "retention is nearly free" regime: optimal covers of two or three instructions against a median file's 39, a 15-step horizon, one model serving as both maintainer and executor, and mechanically verifiable English constraints. The WildIFEval arm seeds excess into benchmark prompts rather than growing it in real files, so it prices what excess costs and what a comment recovers, not whether the ratchet persists at that size.
The judge problem matters more. WildIFEval's constraints are prose with no code verifiers, so every satisfaction rate comes from an arm-blind LLM judge. The author re-scored all 6,336 verdicts under a second judge; the criteria reproduce, but the effect size disagrees, 7.8 points for the second judge against the 11.6 quoted, with a 95% CI of [-1.9, +9.6] that includes zero. Neither judge is ground truth, so this measures reproduction, not accuracy.
The corpus covers only public GitHub CLAUDE.md, AGENTS.md, and copilot-instructions.md, with no measured language distribution and no claim for non-English instructions. Whether catastrophic remembering reaches system prompts or agent skill files stays open.