When Your Project Files Become Digital Packrats

You know how it goes. Fresh project, clean slate. Maybe you create a CLAUDE.md, drop in a few useful reminders. A tip about that quirky authentication behavior. A note about which API to use for what.

Six months down the road? You've got a monster on your hands. Walls of text nobody reads anymore. Contradictory advice that nobody remembers adding. A sprawling appendix of desperate afterthoughts.

Sound familiar? You're not alone.

The Numbers Don't Lie

Researchers got curious about this phenomenon. They dug into 247,694 instructions across nearly 1,900 repositories, tracking how these files evolved over time.

What they found should make every developer wince: these files don't just grow—they grow indefinitely. The typical trajectory showed instruction counts ballooning by 226% over their lifetime. That's more than tripling in size.

Here's the kicker: every single commit added an average of 4.9 new instructions. Zero deletions. The file only knows one direction.

But it gets weirder. The data showed something almost counterintuitive—older instructions become more permanent over time. The longer a piece of advice sits in your file, the less likely it ever gets removed. Instructions become fossilized. Not because anyone loves them, but because nobody wants to be the person who deletes something important.

The Exponential Tax

So what's driving this? Researchers gave it a name: "catastrophic remembering." It's basically the opposite of the "catastrophic forgetting" problem we worry about with AI models.

But here's why it happens in practice, no machine learning jargon required.

Adding a new instruction is easy. You spot an issue, you jot down a fix, you move on. The cost is negligible. The payoff is immediate.

Removing one? That's a whole different calculation. You have to trace every possible dependency. Figure out how it might interact with other rules. Verify nothing breaks in ways you'll only discover at 2 AM when something goes wrong in production. Researchers quantified this cognitive overhead as O(2^|D|)—meaning the mental cost explodes as your file gets bigger.

So what do rational people do? They give up. They add their new note. They leave the old ones alone. The file swells.

The Humble Comment Saves the Day

Here's where things get genuinely interesting. The researchers didn't come up with better prompting tricks or fancier model architectures. Their breakthrough was simpler: comments.

They built an experiment around inverting IFEval, a standard benchmark, creating scenarios where the "right answer" was actually knowable. Then they added comments that captured the reasoning behind instructions—not just the instructions themselves.

The results were striking. Instruction growth plummeted from 211.3% to just 1.4%. That's a 99.3% reduction.

But wait, it gets better. These comments didn't just slow the bloat—they made the instructions work better. Real-world task performance jumped up to 23.1%.

Comments aren't decorations. They're load-bearing walls.

We're Relearning an Old Lesson

Something fundamental is shifting in what we mean when we say "code." English is becoming the new programming language, and yet we haven't applied the lessons we learned decades ago.

Every developer knows that undocumented code is technical debt. Comments explain the why, not just the what. They capture intent, edge cases, the institutional knowledge that lives in someone's head but never made it into the actual implementation.

When we hand work off to AI coding assistants, we seem to forget this. We write commands—"do this, don't do that, remember X"—without ever explaining ourselves. We treat natural language instructions like they're somehow exempt from the rules that govern everything else we write.

The result is those bloated CLAUDE.md files full of directives nobody can untangle. Rules that might contradict each other. Growth with no mechanism for rationalization.

What Actually Helps

Based on what the research shows, here's what works:

Comment your instructions the way you'd comment code. That rule about preferring the backup API in production? Explain why. Document the edge case. Capture the reasoning, not just the directive.

Rebuild periodically, don't just append. Full rewrites are one of the few things that actually break the growth cycle. Treat it like refactoring, not maintenance.

Imagine handing this to a new developer. Would you give someone a 400-line wall of undifferentiated rules with no organization? Your AI assistant deserves the same courtesy.

The pattern we're in isn't sustainable. Every project starts with good intentions and ends with an unmaintainable mess. But maybe the fix is simpler than we thought: write for the version of yourself (or your AI assistant) reading this six months from now, not just the one asking a question right now.

Comments aren't clutter. They're the scaffolding that makes understanding possible.