Why CLAUDE.md keeps growing, and how rule rationale fixes it
- Source
- x.com
- Date
An agent repeats a mistake, so you add a rule. Months later, nobody remembers why it exists. “Why Does CLAUDE.md Keep Growing?” calls this “catastrophic remembering.” The study tracks 247,694 instruction lifetimes across 1,867 repositories. Files like CLAUDE.md more than triple over their lifetime. The cause is lost reasoning, not changing requirements. Without the reason, deleting anything feels risky. The paper tests attaching a comment to each rule. Those comments record: > The failure behind the instruction > The hypothesis behind the fix > Evidence from previous attempts The author built tests where the ideal prompt was known. Uncommented prompts ended 211% longer than that ideal. Informative comments cut the excess to 1.4%. The agent followed constraints equally well both ways. In an interview with AlphaSignal, author Kushal Chakrabarti (@kushalc) recommends a cache approach. “The cache should have triggers and pointers, not summaries.”
Context
Recording why an instruction exists can make it easier to remove unnecessary rules later. A study of instruction-file growth tested comments that preserve the triggering failure, the proposed fix and what happened afterward. The comments were passed to the next prompt-maintaining agent but stripped before the task-performing model saw the instructions.
In controlled tasks with a known reference instruction set, uncommented prompts finished 211.3% above its size after 51 steps; informative comments reduced that excess to 1.4%, with the same measured constraint-satisfaction rate. The 51-step condition used a single seed and a wide uncertainty interval. This supports preserving maintenance evidence alongside rules. The result measures an experimental maintenance process, rather than proving that adding comments will shrink any project's CLAUDE.md by the same amount.
- AI agent — An AI system that doesn't just answer once but works toward a goal in a loop — taking actions, reading the results, and deciding what to do next.
Checking sign-in…
Loading comments…