AI coding tools
Agent instruction files grow by an average of 226%; study curbs CLAUDE.md bloat with “rule rationales”
A study of 1,867 public repositories found that agent instruction files such as CLAUDE.md continually accumulate rules while older rules are deleted less and less often. Controlled experiments showed that retaining model-readable rationales for adding rules can eliminate 99.3% of superfluous instructions, though the results have yet to be prospectively validated in large real-world codebases.
Coding agents often write fixes back to `CLAUDE.md`, `AGENTS.md`, or `copilot-instructions.md`, preserving lessons for the next task. New research, however, suggests that this low-cost memory creates a ratchet in which instructions are added but rarely removed. The author tracked 1,867 public GitHub repositories, 299,440 file-version transitions, and 247,694 instruction lifecycles, finding that instruction counts increased by an average of 226% over a file’s lifetime. After excluding large-scale rewrites, each relevant commit added a net average of 4.9 instructions, and the longer a rule remained in place, the less likely it was to be deleted.
The author calls the phenomenon “catastrophic remembering”: adding a rule requires addressing only the immediate failure, whereas deleting one requires reconstructing why it was introduced, or risking the reintroduction of an error. Even after an entire file was substantially rewritten, its average instruction count recovered within ten commits from 59.5% of the pre-rewrite level to 91.5%, indicating that one-off cleanups do not address the underlying information loss.
The study then reverse-engineered IFEval into an environment with a known minimal rule set and asked models to maintain prompts iteratively. When each rule also recorded the failure case from which it was derived, excess rules after 51 rounds fell from 211.3% to 1.4%. Adding superficially similar text without causal information did not produce the same effect. In WildIFEval experiments, these rationales improved instruction-following rates by as much as 11.6 percentage points.
The engineering takeaway is not to indiscriminately pack more explanation into the startup context, but to give rules provenance, scope, and revocation conditions, while moving content that applies only to particular paths into rules or skills loaded on demand. Claude Code’s official documentation likewise recommends keeping CLAUDE.md concise and notes that HTML block comments are stripped when the file is loaded; the study’s required “model-visible rationales” therefore cannot be implemented directly with such comments. This remains a prototype study by a single author: its controlled tests cover only a small set of mechanically verifiable constraints, and it does not establish that automatically deleting rules is safe in large production repositories.