🤖 machine learning

Why Does CLAUDE.md Keep Growing? Catastrophic Remembering in Agentic Coding

This paper identifies "catastrophic remembering" as the cause of unbounded growth in agentic coding prompts like CLAUDE.md, demonstrating that appending instructions is cheap while deleting them is computationally prohibitive, and proposes that embedding latent reasoning in prompt comments can effectively halt this divergence and significantly improve instruction-following performance.

Original authors: Kushal Chakrabarti

Published 2026-08-12

📖 6 min read🧠 Deep dive

CC BY 4.0

Original authors: Kushal Chakrabarti

Original paper licensed under CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ This is an AI-generated explanation of the paper below. It is not written or endorsed by the authors. For technical accuracy, refer to the original paper. Read full disclaimer

Imagine you are teaching a very smart, but slightly forgetful, robot assistant how to do a specific job, like writing blog posts or fixing code. You start by giving it a simple list of rules: "Use three paragraphs," "Don't use the word 'very'," and "Always end with a smile." This is called a prompt. In the world of artificial intelligence, these prompts are like the instruction manuals for robots.

Now, imagine the robot makes a mistake. You fix it by adding a new rule: "Okay, and make sure to use exactly five bullet points." The robot tries again, fails, and you add another rule: "And remember to capitalize the first letter of every sentence." Over time, this list of rules gets longer and longer. In computer science, there's a famous problem called catastrophic forgetting, where a robot learns something new and accidentally wipes its memory of the old stuff. But this paper talks about the opposite problem: catastrophic remembering. This is when a robot (or the human managing it) keeps adding rules but never deletes the old ones, even when they aren't needed anymore. The list becomes so huge and messy that the robot gets confused, slows down, and starts making mistakes again. The big question is: Why does this list keep growing forever, and how do we stop it?

The Mystery of the Never-Ending List

The author of this paper, Kushal Chakrabarti from South Park Commons, decided to investigate why these "agentic" instruction lists (files often named CLAUDE.md or AGENTS.md in software projects) seem to grow without bound. They looked at nearly 1,870 real-world software projects on GitHub and tracked the lives of over 247,000 individual instructions.

They found a strange pattern: these lists almost never shrink. Instead, they grow by an average of 4.9 new instructions for every single update to the file. Over the life of a file, the number of instructions more than triples, growing by 226%. The average file ends up with 39 instructions, but some have over 100.

The researchers asked: Why don't people just delete the old, useless rules?

They discovered the culprit isn't that the rules are "stale" (outdated) or that the bad rules die young. Instead, the problem is imperfect recall. Think of it like this: When you add a new rule to the list, you know why you added it. Maybe you added "Use three paragraphs" because the robot kept writing four. But that "why" is just a thought in your head. It's not written down.

As time passes and other people edit the file, or as the project changes, that original reason fades away. If you look at the list six months later, you see the rule "Use three paragraphs," but you have no idea why it's there. Was it because the robot was too chatty? Was it because the boss asked for it? Without that reason, deleting the rule feels risky. You're afraid that if you delete it, the robot will break again. So, you leave it there. Meanwhile, you keep adding new rules for new problems. The result is a bloated, confusing list of rules that nobody understands anymore. The author calls this catastrophic remembering: keeping everything you should have forgotten.

The "Bulldozer" Effect

The study also found something funny about how people try to fix these messy lists. They rarely delete just one or two bad rules. Instead, they tend to hit the "delete all" button. The data showed that 76.8% of all instruction deletions happen in one giant "rewrite" where someone deletes half or more of the file at once. It's like a gardener who can't decide which weeds to pull, so they just burn the whole garden down and start over.

But here's the kicker: even after this "burning," the garden grows back. The list starts growing again immediately, at the same fast pace as before. This is called the ratchet effect. The size drops, but the rate of growth doesn't change. The root cause—the fact that people can't remember why the rules were added in the first place—was never fixed, so the list just starts filling up again.

The Magic of "Comments"

So, how do we stop the list from growing forever? The paper suggests a solution that software engineers have used for decades: comments.

In regular computer code, programmers write little notes next to their code to explain why they wrote it that way. These notes are invisible to the computer but helpful for the next human who reads the code. The researchers tested if this same trick works for AI prompts.

They set up a simulation where "maintainers" (AI agents) had to build and fix a prompt. In one group, they had to write instructions without any notes. In the other group, they were allowed to add a comment next to each instruction explaining the reason. For example, next to "Use three paragraphs," the comment might say: "Added because the robot kept writing four paragraphs in round 3."

The results were dramatic.

Without comments: The prompt grew to be 211.3% larger than the perfect, minimal size needed to do the job.
With comments: The prompt stayed almost perfectly sized, growing only 1.4% larger than the minimum.

The comments acted like a time machine. They preserved the "latent reasoning" (the hidden reason) for each rule. When a maintainer looked at the list later, they could see the comment, understand that the rule was still needed, or realize it was no longer necessary, and delete it safely. The comments removed 99.3% of the excess, unnecessary instructions.

Does It Actually Work Better?

The researchers didn't just stop at making the lists shorter; they checked if the robots actually did a better job. They found that when prompts were bloated with useless, noisy instructions, the robots got confused and made more mistakes. By using comments to keep the list clean and focused, the robots' ability to follow instructions improved by up to 23.1%.

The study also showed that this works even when the instructions are complex and the "maintainers" are very smart AI agents. The more capable the AI, the more it tends to over-add rules, but the more it benefits from having those helpful comments to keep things in check.

The Big Takeaway

The paper concludes with a playful but serious question: "If English is the new code, why don't we have comments yet?"

Just like human programmers learned long ago that you need to explain why you wrote a line of code, the people (and AI agents) managing these AI prompts need to start writing down why they added a rule. Without that explanation, the rules pile up, the system gets confused, and performance drops. The solution isn't to stop adding rules; it's to write a little note next to each one so that the next person (or robot) knows exactly what to keep and what to throw away. It turns a chaotic, growing monster into a clean, efficient tool.

Technical Summary: Catastrophic Remembering in Agentic Coding

1. The Problem: Unbounded Growth of Agentic Prompts

Agentic coding repositories increasingly rely on context files (e.g., CLAUDE.md, AGENTS.md, copilot-instructions.md) to guide AI agents. Empirical observation reveals a pathological growth pattern: these files accumulate instructions without bound, rarely shedding them until the file is wholesale rewritten or the repository retires.

This growth is not merely a matter of adding new requirements; it represents a failure of maintenance. As constraints accumulate, instruction-following performance degrades. The paper identifies the root cause not as "instruction staleness" (where old instructions become irrelevant) or "content fragility" (where weak instructions die young), but as imperfect recall.

When a maintainer adds an instruction, the rationale (latent reasoning) for that addition is often implicit or unrecorded. Over time, as multiple authors edit the file, this latent reasoning decays. Deleting an instruction without its rationale carries a high risk of correctness regression. Consequently, the "hazard" (probability) of deleting an instruction decreases as the instruction ages. This leads to a ratchet effect: additions are cheap and frequent, while deletions are risky and rare, causing the prompt size to diverge. The author terms this phenomenon Catastrophic Remembering—the inverse of catastrophic forgetting in continual learning, where a system retains what it should have overwritten because the license to update (the rationale) has been lost.

2. Methodology

2.1 Empirical Analysis of Real-World Repositories

The author conducted a large-scale observational study across 1,867 GitHub repositories containing agentic context files.

Data Scope: They tracked 247,694 instruction lifetimes across 299,440 version-to-version transitions.
Segmentation: Instructions were segmented from file payloads using markdown structure and sentence boundaries.
Matching: A three-stage cascade (exact string, normalized string, fuzzy match) tracked instruction survival across commits.
Competing Risks: The study distinguished between "deletions" (maintainer judgment) and "wholesale rewrites" or "migrations" (mass removals). 77.3% of instruction deaths occurred in wholesale rewrites, which the study censored as competing risks to isolate the deletion hazard.
Statistical Modeling: The author used Nelson-Aalen estimators and gamma frailty models to analyze the deletion hazard $h(a)$ as a function of instruction age $a$ and the number of authors.

2.2 Theoretical Framework

The paper models prompt maintenance as the online estimation of an unobservable constraint set $C$ from censored, noisy feedback.

Latent Reasoning Decay: The recoverability of the rationale $r_d$ for an instruction $d$ decays with age $a$ , denoted as $\rho(d, a)$ .
Equilibrium: Without recoverable rationale, the optimal estimator becomes append-only. The equilibrium size $|D_\infty|$ diverges as $\bar{\rho}(a) \to 0$ , even if the task constraints remain fixed.
Cost Asymmetry: Adding an instruction costs $O(1)$ , but verifying that an instruction is excess (and safe to delete) without its rationale costs $O(2^{|D|})$ due to the combinatorial explosion of counterfactuals required to test subsets of instructions.

2.3 Controlled Experiments (Inverse-IFEval)

To test the causal mechanism, the author constructed a controlled environment by inverting the IFEval benchmark.

Setup: Instead of evaluating a model's ability to follow instructions, they tasked a "maintainer" agent with reconstructing a known set of instructions (the minimum cover $D^\star$ ) from a general objective and noisy feedback.
The Intervention: The maintainer could annotate new instructions with comments encoding the latent reasoning (the failure observed, the hypothesis, and the outcome).
Arms:
1. Control: No comments.
2. Placebo: Comment-shaped noise (generic text without reasoning).
3. Treatment: Informative comments encoding specific latent reasoning.
Evaluation: The system measured excess size ( $|D_t|/|D^\star| - 1$ ) and constraint satisfaction.
WildIFEval Extension: A second experiment applied this to real-world, human-written prompts with noisy distractors to measure instruction-following recovery.

3. Key Contributions and Results

3.1 Empirical Evidence of Catastrophic Remembering

Unbounded Growth: Agentic prompts more than triple in size over their lifetime (+226%), gaining a net +4.9 instructions per commit.
The Ratchet: When a file is wholesale rewritten, it resets to ~60% of its previous size but immediately resumes growing, often faster than before (4.9% per commit post-rewrite vs. 4.1% pre-rewrite).
Deletion Hazard: The probability of an instruction being deleted decreases as it ages (log-hazard slope: -0.032/commit). This contradicts the "staleness" hypothesis (which predicts rising hazard) and supports "imperfect recall."
Author Interaction: The hazard of deletion decays even faster when more distinct human authors have edited the file, confirming that the loss of the original author's rationale is the driver.

3.2 The Solution: Prompt Comments

Encoding latent reasoning in prompt comments acts as a sufficient intervention to halt unbounded growth.

Excess Size Reduction: In the controlled IFEval inversion, informative comments reduced excess size from +211.3% (control) to +1.4% (treatment) over 51 steps. In a 15-step horizon, this reduced excess from +60.4% to -5.8%.
Correctness Parity: This reduction in size was achieved without degrading constraint satisfaction; in fact, satisfaction remained at parity or slightly improved.
Real-World Impact: In the WildIFEval experiment, adding informative comments to prompts containing noisy distractors improved instruction-following by 23.1% (11.6 percentage points) compared to an uncommented control.
Ablation: The benefit is driven specifically by outcome-grounded reasoning. Comments that merely narrate attempts without outcomes, or generic "noise" comments, failed to reduce excess size.

3.3 Theoretical Insight

The paper formalizes that recoverability of latent reasoning is the necessary and sufficient condition for stable prompt maintenance. Without it, the system is forced into a "catastrophic remembering" state where the only safe deletion strategy is a wholesale rewrite, which fails to address the underlying accumulation of unverified constraints.

4. Significance and Claims

The paper claims to provide the first root-cause analysis of unbounded agentic prompt growth, shifting the blame from "instruction staleness" to imperfect recall.

Paradigm Shift: It reframes prompt maintenance as a problem of information preservation rather than just constraint management. Just as software engineering solved the "why" problem with comments decades ago, agentic coding requires the same practice.
Practical Utility: The study demonstrates that simple, structured comments can reduce prompt bloat by over 99% in controlled settings and recover significant instruction-following capability in noisy, real-world scenarios.
Limitations: The author is modest about their scope. The corpus is limited to English-language public GitHub repositories. The controlled experiments rely on mechanically verifiable constraints (IFEval) and specific model configurations. The paper does not claim that comments solve all prompt engineering challenges, but specifically addresses the growth and maintenance dynamics of agentic context files.

The central thesis is that if English is the new code, agentic prompts must adopt the discipline of software engineering: recording the "why" (latent reasoning) is the only way to safely manage the "what" (instructions). Without this, agents will inevitably suffer from catastrophic remembering, accumulating unusable constraints until the system becomes non-functional.