Every repository I work in has a CLAUDE.md, and every one of them is longer than it was three months ago. I do not think I have ever deleted a line from one. Skimming this morning's arxiv list, I found a paper that puts a number on exactly that reflex — and then, unusually, does something about it instead of just scolding me. The thesis I came away with: your agent instruction file only grows because deleting a line is exponentially more expensive than adding one, and the missing piece is a comment syntax.
What it does#
Why Does CLAUDE.md Keep Growing? Catastrophic Remembering in Agentic Coding, a single-author paper by Kushal Chakrabarti posted August 11, stacks three parts on one claim. Part one is a measurement study: clone 1,867 GitHub repositories carrying a CLAUDE.md, AGENTS.md, or copilot-instructions.md, walk the full commit history, and track every clause-level imperative from birth to death. That yields 247,694 instruction lifetimes across 299,440 version-to-version transitions. Instructions are matched across versions by exact, then normalized, then fuzzy comparison at a 70% threshold, validated at 1.000 precision and 0.933 recall against hand annotation.
The framing is what makes it more than a scraping exercise. Continual learning is organized around catastrophic forgetting — models losing what they knew. Chakrabarti names the inverse for prompts: catastrophic remembering. The mechanism is a cost asymmetry. Appending an instruction is cheap and always safe. Deleting one safely means estimating its marginal contribution, and because instructions interact — two rules that each cover half of a constraint both look disposable in isolation — probing them one at a time does not work. Auditing whether an instruction is genuinely excess costs O(2^|D|) subset probes for a file of |D| instructions. But if you know why the line was added, that check collapses to O(1). Rationale is the thing that decays, so the file diverges.
The key result#
The observational half is precise and bleak. The median file holds 39 instructions (90th percentile: 131). 64.3% of multi-version repositories grew their instruction count, only 26.6% shrank, at a rate of +4.9 net instructions per commit — +226% growth in instruction count over a file's lifetime, with +140% total size growth confirming this is accumulation, not text migration. The survival analysis is the part that got me: the deletion log-hazard slope is −0.032 per commit (95% CI [−0.047, −0.019]), meaning the older an instruction gets, the less likely it is to ever be deleted. Files are not pruned, they are amputated — 76.8% of instruction deaths occur in wholesale-rewrite commits that cut a file to ≤50% of its instructions, after which it climbs back to 91.5% of its pre-rewrite size within ten commits. Then the intervention. Inverting IFEval into verifiable worlds where the optimal prompt is known, uncommented maintainers drift to +211.3% excess instructions over 51 steps; maintainers allowed to annotate each instruction with a comment recording the failure, the hypothesis, and the outcome land at +1.4% — 99.3% of the excess removed, at parity on constraint satisfaction. On WildIFEval's human-written prose constraints, comments lifted satisfaction from 50.4% to 62.0%, an 11.6pp absolute and 23.1% relative gain.
Why it matters#
The artifact here is small enough that I can adopt it this week. A prompt comment is a line addressed to the next maintainer and stripped by the harness before the prompt reaches the model. The paper's own example: Write your response as three sentences, each ending with a period. # r3: 'response is not split into the right number of paragraphs' recurring across r2–r3; previous directive d18 specified two blank lines but failed; increasing to three. Failure observed, hypothesis tested, outcome. Nothing in the CLAUDE.md format prevents this today; the strip step is a few lines in a hook. What it buys is the ability to answer “can I delete this?” by reading, rather than by re-running an eval suite or — honestly — by leaving it in forever. One detail worth internalizing before you try it: the arm that wrote narrative comments without recorded outcomes was the paper's worst arm at +70.0% excess. The comment has to carry the result, not the story.
The wider reframing is that your agent instruction file is not documentation. It is an append-only log with no compaction strategy, and its growth is structural rather than a failure of discipline on your part. This lands on top of a run of recent results all saying prose guidance is weaker than it feels — SIGIL's finding that prose skills hit 56% mandate compliance against 86% for compiled harnesses, the AGENTS.md ablations that found context files barely move correctness, Probe-and-Refine showing repo guidance buys coverage rather than precision and does not transfer across models. Put them together and the working model is uncomfortable: every line in CLAUDE.md spends context budget and dilutes attention, most lines are not earning it, and you have no mechanism to find out which ones. The WildIFEval arm quantifies the dilution directly — 16 distractor instructions cost 24.1 percentage points of correctness on the true ones (65.6% down to 41.5%). Read that way, the 23.1% is not the agent getting smarter. It is the maintainer finally being able to throw things away.
The caveats#
The inverse-IFEval worlds have optimal prompts of 2–3 instructions over a 15-step horizon. The median real file holds 39. That the mechanism scales to real file sizes is argued, not demonstrated.
One model plays both maintainer and executor, and the backbone is never named. Real repositories have several humans plus several agents editing the same file, which is precisely the setting where rationale goes missing.
The 50% rewrite threshold is an internal tracker parameter that censors 77.3% of observed deaths, and it is never varied. That is a large knob sitting directly under the headline hazard result.
The matcher was validated on 50 hand-annotated transitions against 299,440 tracked ones. WildIFEval scoring is an LLM judge, and a secondary judge moved the effect from 11.6pp to 7.8pp — same direction, notably smaller.
Public GitHub only, with no language-distribution analysis, and the author flags that automated deletion driven by comments can remove valid instructions if the comments mislead. Keep a person in the deletion path.
The takeaway#
What I am filing away is the cost asymmetry rather than the specific intervention: adding is O(1), deleting safely is O(2^|D|), and recorded rationale is the only thing that collapses the second one. That is why every prompt file I own behaves like a ratchet, and why the periodic bulldoze-and-rewrite is not carelessness but the rational response to an unaffordable audit. Starting this week I am appending a # rationale to every new line I add to a CLAUDE.md — failure seen, hypothesis, outcome, three clauses — and stripping them at load time. I am not going to retrofit the existing lines; that is the O(2^|D|) problem, and the paper is honest about the risk of automating it. But the next two hundred lines will be deletable, and that is the difference between a file I maintain and a file I periodically demolish.