Skip to content

Claude Code

Coding-agent prompt files grow 226% and never shrink

3 min read

Written by an AI model from the linked sources and checked against them by a second model. How we work

All about: Claude Code versions and changes →
Image: arxiv.org

Instruction files for coding agents like CLAUDE.md almost never shrink, according to a preprint Kushal Chakrabarti posted to arXiv on August 11. In real repositories the growth stops only when the repository is retired or someone rewrites the file from scratch.

The study tracks 247,694 instruction lifetimes across 1,867 repositories. Over its lifetime a prompt file grows by 226%, more than tripling, and gains a net 4.9 instructions with every commit. Age protects an instruction: the older it gets, the less likely it is to be deleted, with the log-hazard of deletion falling by 0.032 per commit.

Claude Code reads CLAUDE.md automatically when it starts work in a repo. The file holds what the agent can’t work out from the code, such as build commands, testing conventions and architectural rules. Anyone on the team can add to it.

The paper explains the growth through a difference in cost. Adding an instruction is always cheap. Deleting one is cheap only while someone remembers why it was added. Once nobody remembers, removing a rule without risking a correctness regression costs O(2^|D|) for a prompt of |D| instructions. The exponent comes from combinations: any unexplained rule might matter only alongside others, so a safe deletion in principle means checking every combination of rules. Nobody does that, so nobody deletes.

The authors call the result catastrophic remembering. The name flips catastrophic forgetting, where a model trained on new tasks loses the old ones. Continual learning as a field is organized around that problem. Here nothing is lost and everything piles up.

The advice Claude Code users got follows the same arc. In January 2026 Boris Cherny recommended writing a new rule into the file every time the model got something wrong. After Opus 5 shipped, he told YC Startup School to delete CLAUDE.md, skills and hooks every six months and add lines back only when a failure repeats.

The paper’s proposed fix comes from ordinary code: comments inside the prompt that record the latent reasoning behind each instruction. To test the idea, the authors inverted IFEval, a benchmark of instructions whose compliance can be checked automatically. Inverting it produces verifiable worlds where the optimal prompt is known, so every excess instruction can be counted. Without comments, prompts in those worlds grew by 211.3%. With comments, growth fell to 1.4%, and 99.3% of the excess instructions were removed.

The same inversion applied to WildIFEval, a collection of real-world user instructions, showed prompt comments improving agentic instruction-following by up to 23.1%. The near-total cleanup holds only in the constructed worlds where the right answer is known in advance. On real-world instructions the evidence is only that more modest “up to” figure.

The abstract closes on a question:

If English is the new code, why don’t we have comments yet?

No comments yet. Be the first.

Join the conversation

Sign in to leave a comment. It appears after moderation.