An agent breaks something. Someone adds a line to CLAUDE.md so it will not happen again. Three months later nobody remembers exactly why the rule exists, so nobody wants to delete it.

Then another rule arrives. Then forty more.

Kushal Chakrabarti calls this “catastrophic remembering.” The study tracks 247,694 instruction lifetimes across 1,867 repositories and finds a strong ratchet effect in files used to steer coding agents.1

Files triple, then somebody bulldozes them

In the GitHub corpus, instruction counts increase by 226% over a file's lifetime. Age also works against deletion: the older an instruction becomes, the less likely it is to disappear.1

The most revealing detail is how rules finally die. The paper reports that 76.8% of instruction deaths happen in commits that rewrite the file wholesale. Growth then resumes after the reset.1

The proposed explanation is simple. Adding a rule after a failure is cheap because the reason is still present. Deleting it months later requires reconstructing why it was added and which regression it prevented. That context is often gone.1

The incentives are asymmetric. Adding a rule feels immediately safe. Removing one creates a visible risk. The cost of carrying obsolete instructions is diffuse.

A rule needs a comment

The paper's proposed fix is almost embarrassingly familiar: store the reason with the rule.

The author builds synthetic environments where the minimum necessary instruction set is known. Without useful comments, prompts keep accumulating. With comments that preserve the reasoning behind each rule, reported excess instructions fall from +211.3% to +1.4% in that experiment.1

The useful comment is not just “don't do X.” It records what failure caused the rule, why a broader instruction was insufficient and what behaviour the rule protects.

That turns an instruction into something maintainable.

In a separate experiment derived from WildIFEval, the paper reports up to a 23.1% improvement in instruction following with the approach.1

Those numbers should not become a universal law overnight. The causal mechanism is tested in constructed worlds where the optimum can be observed. The GitHub corpus shows real growth, but observational data alone cannot prove why each maintainer kept each line. This is also a fresh preprint, not a peer-reviewed result.1

Character count is not the problem

A script that truncates CLAUDE.md at 200 lines would miss the point.

One long instruction may be essential. A six-word rule may survive for months after the bug that created it is gone. The missing property is provenance.

Software already has tools for this. Comments explain local decisions. Commits preserve change history. ADRs record architectural choices. Regression tests turn old accidents into executable constraints.

Agent instruction files are still often treated as magical lists that receive another incantation after every incident.

The study suggests a better discipline: important rules should carry their “why,” and ideally a way to test whether they are still needed.

That changes how an agent should be improved too. Instead of asking “which instruction is missing?” after every failure, ask whether the behaviour belongs in a test, tool, type, permission or mechanical gate rather than another paragraph of prose.

The best CLAUDE.md may not be the one that remembers everything. It is the one that still knows why it remembers.