The Slow Death of Every CLAUDE.md File

You know how this goes. You fire up a new project, create a pristine CLAUDE.md, and drop in a few helpful notes. "This API works weirdly—always check for null." "We use date-fns, not moment." Simple stuff.

Six months later, you've got 800 lines of increasingly contradictory advice. Someone added a note about the auth flow. Then someone else added a caveat about that note. Then a third person added a warning about the caveat. Nobody touches anything because nobody's sure what will break.

You're not alone. This happens everywhere.

The Numbers Behind the Chaos

A study looked at nearly 250,000 instructions across almost 2,000 repositories. What they found tells a familiar story: agentic prompts don't just get bigger—they explode. Over their lifetime, these files more than triple in size. Each commit adds roughly 5 new instructions on average.

The creepy part? Old instructions never die. The data shows that the longer a rule sits in a file, the less likely anyone is to delete it. Instructions become fossilized. Not because developers don't want to clean things up, but because they have no idea if they safely can.

Why Deleting Is Scary

Adding a new instruction feels painless. You spot a problem, you jot down a solution, done.

But taking one away? That requires understanding every possible connection that instruction might have. Every interaction it could have with other rules. Every subtle thing that might break if you remove it. The researchers calculated this mental load as exponential—doubling with every new instruction added to the file.

So people stop trying. They just append. The file grows and grows.

Here's Where It Gets Interesting

The researchers found a surprisingly simple fix. Not better prompting frameworks. Not new AI models. Just one thing developers have used since programming began: comments.

They ran an experiment using inverted benchmarks where they knew the "right answer." When they added explanatory comments to prompts—explaining why rules existed, not just what to do—instruction growth plummeted from over 200% down to barely 1%.

Ninety-nine percent reduction.

And it got better. These comments didn't just slow growth—they actually made the AI perform better at its job. Up to 23% improvement on real tasks. Comments aren't decoration. They're load-bearing.

The Big Question We're Ignoring

Here's a thought: if natural language is the new code, why are we writing it like we're leaving notes for ourselves that only we will ever read?

We know code needs comments. We know "why" matters as much as "what." We've internalized this for decades.

But when we write instructions for AI? We switch modes entirely. We bark orders. Do this. Don't do that. No context. No reasoning. Just imperatives floating in a void.

And then we wonder why those instructions become incomprehensible messes.

What Actually Works

Based on what the research shows:

1. Explain your rules. Why does this pattern exist? What edge case does it handle? The reasoning matters, not just the directive.

2. Rebuild occasionally. Full rewrites are one of the few things that actually stop the growth. Don't just keep adding—step back and restructure.

3. Write for tomorrow. Imagine handing your instructions to someone who's never seen your project. Would they understand it? Your AI deserves the same consideration you'd give a human teammate.

The pattern we're in now—clean start, inevitable bloat, eventual abandonment—isn't inevitable. The fix might be the oldest trick in the book: write like someone will read it later. Because they will.

Comments aren't clutter. They're the difference between instructions that work and instructions that just accumulate.