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

Abstract: Agentic coding READMEs like CLAUDE.md grow without bound in real repositories, stopping only when the repository retires or someone rewrites the file wholesale. We trace this to imperfect recall: appending an instruction is always cheap, but once an instruction's rationale is gone, deleting it without risking a correctness regression costs O(2^|D|) in a prompt of |D| instructions. We name the resulting divergence catastrophic remembering, the inverse of catastrophic forgetting around which continual learning is organized. First, we characterize this phenomenon across 247,694 instruction lifetimes in 1,867 repositories: agentic prompts grow without bound, more than tripling over their lifetime (+226%), gaining +4.9 net instructions every commit; further, the older an instruction gets, the less likely it is to be deleted (log-hazard -0.032/commit). Then, we show that prompt comments can halt the growth: inverting IFEval yields verifiable worlds whose optimal prompts are known, and there comments encoding latent reasoning remove 99.3% of excess instructions (+211.3% to +1.4%). Finally, applying the same inversion to WildIFEval, we show that prompt comments can improve real-world agentic instruction-following by up to 23.1%. If English is the new code, why don't we have comments yet?

• The paper introduces catastrophic remembering, a theory and empirical account of agentic coding prompts accumulating instructions because maintainers lose access to the rationale needed for safe deletion.
• Repository analysis of 1,801 context files found a median terminal size of 39 instructions, a mean growth of 226% over file lifetimes, and declining deletion hazard, especially in multi-author projects.
• Controlled experiments show that outcome-grounded, executor-invisible comments reduced excess instructions by 99.3% and improved instruction following by up to 23.1% amid distracting context, though automated deletion still requires safeguards.

Catastrophic Remembering in Agentic Coding

Thesis and conceptual contribution

“Why Does CLAUDE.md Keep Growing? Catastrophic Remembering in Agentic Coding” (2608.11095) examines the persistent growth of agentic coding context files, including CLAUDE.md, AGENTS.md, and copilot-instructions.md. Its central claim is that this growth is not primarily caused by changing requirements, poor instruction quality, or simple maintainer preference. Instead, it results from the decay of the latent rationale behind individual instructions. Instructions remain visible after the reasons for introducing them have become unrecoverable. Addition therefore remains comparatively inexpensive, whereas safe deletion requires reconstructing counterfactual evidence about what would fail if an instruction were removed.

The paper names this dynamic catastrophic remembering, presenting it as an analogue—and inverse—of catastrophic forgetting in continual learning. In catastrophic forgetting, a learner overwrites information that should have been retained. In catastrophic remembering, maintainers retain instructions that should have been removed because the evidence authorizing deletion has disappeared. The resulting prompt becomes append-only in practice, even when the underlying task distribution is stationary.

The paper combines a theoretical model of prompt maintenance, a large-scale longitudinal analysis of public repositories, and controlled experiments based on inverted instruction-following benchmarks. Its strongest claim is causal: preserving latent reasoning in comments can arrest prompt growth while maintaining correctness, and can recover instruction-following performance lost to irrelevant context.

A model of prompt maintenance under censored feedback

The theoretical framework treats prompt maintenance as online estimation of an unobservable constraint set from noisy and censored feedback. A task has an objective and a hidden collection of constraints, while the maintained prompt contains a set of instructions intended to cover those constraints. The executor receives the instructions but not the comments or rationale. The maintainer observes only partial feedback: failures may indicate a violated dimension, but they do not identify the responsible instruction, the relevant parameter, or whether a passing instruction was necessary.

This formulation establishes five properties of the maintenance environment:

• Instructability: some instructions improve satisfaction of hidden constraints.
• Interference: adding an instruction can reduce performance on other constraints.
• Redundancy: multiple instructions can cover the same constraint.
• Censoring: feedback does not identify which instruction caused an outcome.
• Stochasticity: even a correctly covered constraint may fail intermittently.

Under these assumptions, determining whether an instruction is excess requires evaluating counterfactual prompt subsets. Redundancy makes one-at-a-time deletion tests insufficient: two instructions may each appear dispensable individually while being jointly necessary. An exhaustive audit can therefore require $O(2^{|D|})$ subset probes for a prompt containing $|D|$ instructions. By contrast, recording the rationale at write time costs approximately $O(1)$ and can substantially reduce the cost of future maintenance.

The model introduces a recoverability function, $\rho(d,a)$, representing the probability that the rationale for instruction $d$ remains available after age $a$. As rationale recoverability declines, deletion hazard declines as well. If additions continue at a roughly stable rate while the aggregate deletion hazard approaches zero, the equilibrium prompt size diverges. This result does not require task drift: a stationary constraint set is sufficient for unbounded prompt growth if rationale decays independently of the instruction itself.

The proposed mechanism also yields a prediction that distinguishes imperfect recall from competing explanations. If instructions become stale, their deletion hazard should increase with age. If fragile instructions die young, population-level hazard may decline, but the decline should not depend systematically on the number of maintainers. Imperfect recall predicts both an age-related decline and a stronger decline in files edited by multiple authors.

Repository-scale evidence for the ratchet

The empirical analysis reconstructs instruction histories across 1,867 public GitHub repositories and 1,801 multi-version context files. The corpus contains 299,440 version transitions, 247,694 instruction lifetimes, and 28,426 tracked deletions after censoring wholesale rewrites and cross-file migrations.

The growth pattern is substantial. The median terminal file contains 39 instructions, while the 90th percentile contains 131. Across multi-version repositories, 64.3% increase their instruction count compared with 26.6% that decrease it. Excluding wholesale rewrites, the mean net change is +4.9 instructions per commit. Over normalized file lifetimes, the mean instruction count increases by +226%, while mean instruction length increases by only approximately +10%. The accompanying payload also grows, indicating that the result is not primarily an artifact of reclassifying existing prose as instructions.

The paper therefore identifies a ratchet rather than merely a positive trend: additions accumulate during ordinary maintenance, a wholesale rewrite occasionally reduces the file, and growth then resumes. This pattern is especially important because it shows that rewriting is not a durable maintenance solution.

Figure 1: Wholesale rewrites account for most instruction deaths, but prompt growth resumes rapidly after the rewrite.

A mass rewrite removes at least half of a file’s instructions. Such rewrites account for 76.8% of instruction deaths in the headline analysis, or 77.3% when the broader rewrite-and-migration censoring category is used. Following the first rewrite, the mean file falls to 59.5 instructions relative to its pre-rewrite level and returns to 91.5 within ten commits across the aligned sample.

The post-rewrite growth rate is not lower. Files gain approximately 4.1 instructions per commit before rewriting and 4.9 afterward.

Figure 2: A wholesale rewrite resets prompt size but does not remove the underlying growth process.

This result supports the paper’s interpretation of rewriting as a reset of state rather than a correction of mechanism. A maintainer can remove many instructions simultaneously without determining which individual instructions are unnecessary. The operation avoids the need for instruction-specific justification, but it also discards useful constraints indiscriminately. Once new failures occur, additions rebuild the prompt, often at an even higher rate.

Deletion hazard and identification of imperfect recall

The paper estimates deletion hazard as a function of instruction age using a repository-stratified Nelson–Aalen analysis. The estimated log-hazard slope is −0.032 per commit, with a 95% bootstrap interval of [−0.047, −0.019].

Figure 3: Instruction deletion hazard declines with age, consistent with decaying rationale recoverability.

The negative slope contradicts the prediction of instruction staleness, which would produce increasing deletion risk as requirements become obsolete. The authors also fit gamma frailty models to address content fragility and survival heterogeneity. Shared frailty associated with recurring instruction text absorbs part of the decline, but the negative age slope remains. In the strongest specification, the slope is −0.0355, with a 95% interval of [−0.0414, −0.0296].

The multi-author interaction provides additional evidence. The age-by-multi-author coefficient is −0.0211, with $z=-11.7$. This indicates that deletion hazard decays more steeply in files edited by multiple human authors, consistent with the loss of rationale during handoffs and author turnover. The result is exploratory rather than fully preregistered, and the measure is only a proxy: counting authors does not establish whether the original author actually left or whether a particular instruction’s rationale was lost.

The identification strategy is technically thoughtful but bounded by measurement assumptions. Instructions are segmented using a fixed corpus-level grammar and matched across versions with exact, normalized, and fuzzy matching. Validation on 50 hand-annotated transitions produced precision of 1.000 and recall of 0.933. However, the annotation sample is small relative to the 299,440 transitions. The 50% rewrite threshold also censors a large share of deaths. These choices could affect the magnitude of the estimated hazard, although the authors argue that missed rewordings would bias the age slope toward zero, making the observed decline conservative.

Informative comments as a causal intervention

The proposed intervention is to separate executor-facing instructions from maintainer-facing comments. An instruction specifies what the executor should do. Its associated comment records why the instruction was added, including the observed failure, the hypothesized cause, recurrence information, falsified alternatives, and—in replacement cases—the exact text of the superseded instruction.

The executor receives the instruction with comments stripped. Future maintainers receive both. This separation is essential: rendering comments to the executor would increase context length without providing the intended maintenance benefit and could contaminate the execution prompt.

To test the mechanism under controlled conditions, the paper inverts IFEval (Zhou et al., 2023). The original instructions become a known minimum cover $D_\star$, while the associated verifiers remain hidden constraints. A stronger model produces a general task objective, and a maintainer must reconstruct an effective prompt from censored feedback over repeated rounds. This design makes excess size observable: correctness can be measured against the hidden verifiers, while prompt size can be compared with the known optimal cover.

The controlled experiment includes three arms: no comments, comment-shaped placebo noise, and informative comments. At 15 maintenance steps, informative comments reduce excess size from +60.4% to −5.8%, while maintaining comparable constraint satisfaction. At 51 steps, the effect becomes more pronounced: excess size decreases from +211.3% to +1.4%, representing a 99.3% reduction in excess instructions relative to the no-comment condition.

Figure 4: Informative comments stabilize prompt size near the known optimum without reducing correctness, whereas absent or uninformative comments permit continued growth.

The placebo condition is critical. Comment-shaped noise produces excess sizes of +53.2% at 15 steps and +147.9% at 51 steps, close to the no-comment arm. The result therefore cannot be attributed to formatting, additional channel capacity, or the mere presence of auxiliary text. The comments must encode useful maintenance state.

The effect is not uniformly risk-free. The informative-comment protocol ends with an empty prompt in 12.1% of controlled worlds, compared with 2.4% in the no-comment arm. On these difficult worlds, the commented arm performs worse, demonstrating that rationale-supported pruning can still delete instructions that remain necessary. The paper consequently recommends human review and safety floors for deletion. Writing comments is low risk; automating deletion based on them is not.

The ablations further indicate that outcomes are the critical content. Narrative descriptions without observed outcomes perform poorly, while removing recurrence counts, falsification lineage, or restoration quotes weakens pruning to varying degrees. This supports a specific interpretation of comments as compact empirical records rather than generic explanations.

Effects on real-world instruction following

The WildIFEval (Lior et al., 9 Mar 2025) experiment evaluates whether comments can recover correctness in prompts containing irrelevant instructions. The setup seeds prompts with true instructions and distractors sampled from other benchmark items. With one withheld true instruction and 16 distractors, irrelevant context reduces satisfaction of the true instructions by 24.1 percentage points, from 65.6% to 41.5%.

Informative comments raise satisfaction from 50.4% to 62.0% over three maintenance rounds, an absolute gain of 11.6 points and a relative gain of 23.1% compared with the uncommented condition. Comment-shaped placebo noise produces an effect close to zero. The result replicates under a second LLM judge, although the point estimate falls from 11.6 to 7.8 points and the confidence interval for the difference between judges includes zero.

The scope of this result is important. Comments do not constitute a general instruction-following improvement in clean prompts. Their benefit appears when prompts contain distractors that can be identified and pruned. The experiment measures recovery from seeded noise rather than the full longitudinal ratchet observed in repositories. It establishes that the maintenance intervention has execution-level consequences, but not that the controlled benchmark reproduces the scale or dynamics of production coding repositories.

Relationship to software engineering and continual learning

The paper’s practical proposal resembles established software-engineering practices: comments, commit messages, architecture decision records, and literate programming all preserve information intended for future maintainers. The contribution is to adapt this principle to agentic prompts, where instruction text is executable policy and comments are explicitly excluded from the executor’s context.

The connection to continual learning is conceptually productive. Conventional continual-learning systems must preserve parameters or representations that future tasks require, while context-file maintainers must preserve rationale that future deletion decisions require. In both cases, the update fails when the information licensing the update is absent. However, the mechanisms differ. Catastrophic forgetting concerns parameter interference under changing objectives; catastrophic remembering concerns textual accumulation under approximately stationary objectives and noisy feedback.

This distinction has implications for agent-memory design. Existing memory systems often use explicit staleness, contradiction, timestamps, or context pressure as eviction signals. The paper argues that authored instructions require a different criterion: the principal maintenance variable is not whether an instruction is old, but whether its rationale remains recoverable and whether its empirical contribution has been falsified.

Practical and theoretical implications

For coding-agent platforms, the most direct intervention is a first-class comment syntax with strict projection semantics. A context file should expose separate views for maintainers and executors. Comments should be attached to stable instruction identities rather than line positions, and should preserve outcome-grounded provenance through instruction replacement and deletion.

A robust production implementation would require additional safeguards:

• comments should record observed failures and validated outcomes rather than unsupported narratives;
• deletion should require confidence thresholds, regression tests, or human approval;
• safety-critical instructions should be excluded from automatic pruning;
• comments should be versioned independently when an instruction is rewritten;
• prompt compilers should enforce that rationale does not leak into the executor context;
• maintenance dashboards should track instruction age, provenance completeness, recurrence, and empirical support.

The theoretical contribution suggests a broader research program on continual learning over natural-language policies. Candidate methods include rehearsal of historical failures, rationale-aware regularization, Bayesian instruction utility estimation, counterfactual execution, and bounded prompt architectures. A future system could maintain a structured evidence graph in which instructions, failures, hypotheses, tests, and replacements are distinct objects. Such a representation would avoid the paper’s protocol limitation that rationale disappears when its associated instruction is deleted.

The empirical claims also motivate better benchmarks. Inverted IFEval provides a known optimum and mechanically verifiable constraints, but its covers are only two or three instructions—far smaller than the median real context file. Future evaluations should use larger, interacting constraint sets; real code-level verifiers; nonstationary objectives; multi-agent authorship; instruction rewriting; and long horizons. WildIFEval’s LLM-based judging should be supplemented with human annotations and executable tests where possible.

Limitations and interpretation

The evidence supports the proposed mechanism, but it does not establish that imperfect recall is the only cause of context-file growth. The observational corpus is restricted to public GitHub repositories and three filename classes. Language distribution, repository domain, organizational structure, and non-English instructions are not analyzed. The author-count interaction is correlational and does not directly measure rationale transfer or personnel turnover.

The controlled experiments also operate in a deliberately constrained regime. The maintenance horizon is short relative to repository lifetimes, both maintainer and executor are instantiated from a single model family in the main experiment, and the known minimum covers are much smaller than real prompts. The WildIFEval result is based on an LLM judge rather than ground-truth annotations. These limitations temper claims about deployment-scale magnitude, even though they do not undermine the central pattern: comments containing empirical rationale reduce unnecessary retention under censored maintenance feedback.

Conclusion

“Why Does CLAUDE.md Keep Growing? Catastrophic Remembering in Agentic Coding” (2608.11095) explains agentic prompt growth as a failure of rationale preservation. Across 247,694 instruction lifetimes, prompts exhibit persistent accumulation, wholesale rewrite cycles, and declining deletion hazard. The theoretical model shows how decaying rationale recoverability makes append-only maintenance rational under noisy feedback. Controlled experiments then demonstrate that outcome-grounded comments can reduce excess prompt size by 99.3% in a known-optimum setting and improve instruction-following by up to 23.1% under distractor-heavy conditions.

The paper’s principal implication is architectural: agentic coding systems should treat maintainer rationale as a first-class, executor-invisible artifact. Comments do not merely document prompts; they provide the information required to delete, revise, and prevent instructions safely. Future systems will need to combine this provenance channel with verification, human oversight, and explicit mechanisms for selective retention if agentic prompts are to remain compact, interpretable, and operationally reliable.