I have a confession. I’ve spent an unreasonable number of hours crafting CLAUDE.md files. Tweaking the wording. Reorganizing sections. Adding rules I’ve seen the AI violate. Removing rules it already follows. I’ve read the blog posts about the perfect .cursorrules. I’ve studied the community templates.
And at some point, sitting there editing line 47 of a markdown file for the third time that week, I realized I was maintaining a wiki. A wiki for a tool that should be smarter than a wiki.
Every Tool Reinvented the Same Dead End
Claude Code has CLAUDE.md. Cursor has .cursorrules. Copilot has instruction files. Windsurf has rules. Aider has conventions files. Different names, same idea: A static file where you, the human, write down everything the AI should know about your project.
The pitch is always the same: “Tell the AI about your project and it’ll follow your conventions.” And it does! For about three weeks. Then:
- Someone makes a new architectural decision in a PR review. Nobody updates the file.
- The team switches from pip to uv. The rule in .cursorrules still says pip.
- A junior engineer adds a rule that contradicts a senior engineer’s rule from six months ago. Both stay in the file.
- The file hits 300 lines and nobody reads it anymore — including the AI, which is now drowning the relevant rules in a sea of stale context.
I’ve watched this cycle play out on three teams now. The file starts useful. It grows. It decays. Within six months, half the rules are outdated and nobody knows which half. Engineers start ignoring it. The AI gets worse, not better, because it’s following instructions that no longer reflect reality.
We’ve Seen This Movie Before
This isn’t new. Every generation of dev tools produces the same artifact:
- .editorconfig — when was yours last updated?
- CONTRIBUTING.md — does it describe how your team actually works?
- ARCHITECTURE.md — does it describe the system as it is, or as it was two years ago?
- .eslintrc — how many rules are disabled with “it was easier”?
These files share a failure mode: They require manual maintenance, nobody is responsible for maintaining them, and the cost of staleness is invisible until it causes a problem. .cursorrules is joining this graveyard. It just hasn’t been around long enough for people to admit it.
The Real Problem With Flat Files
But the staleness issue is actually the minor problem. The bigger issue is structural.
A flat file treats everything the same. “Always use const” and “the billing service has its own database because we had a cascading failure in March” are both just lines of text. One is a coding preference. The other is an architectural decision with critical historical context. They have fundamentally different semantics, different scopes, different lifespans. But in a .cursorrules file? Same treatment. Same weight. Same probability of going stale.
And scope — a .cursorrules file lives in one repo. But organizational decisions span repos. “We use Postgres, not DynamoDB” isn’t a per-project rule. It’s an org-wide decision. You’d need to copy it into every project’s config file. Now you’re maintaining N copies of the same rules, where N is your number of repos. That’s not a knowledge system. That’s a distributed staleness generator.
The Question I Couldn’t Stop Asking
Here’s what bothered me: I was spending hours writing instructions for an AI that is literally designed to understand natural language and extract structured information from unstructured text. Why was I doing its job?
When I explain to the AI why the billing service uses a separate database, the AI understands. It follows the constraint perfectly — for that session. Then it forgets. And I go back to the markdown file and add another line.
What if instead of me writing the file, the AI wrote it itself? Not a raw dump of conversation transcripts — that’s noise. But the actual knowledge: the decision, the rationale, the scope, the relevance. Extracted from the conversation where the knowledge was created. Stored somewhere persistent. Available in every future session. For every engineer on the team.
No file to maintain. No manual updates. No decay.
The conventions aren’t in a file because someone wrote them down. They’re in the system because the system learned them from how the team works. The architectural decision about billing isn’t line 47 of a markdown file — it’s a typed knowledge item with context, rationale, and history, available to any engineer who touches anything near the billing service.
“But I Like My CLAUDE.md”
Fair. I liked mine too. And honestly, a well-maintained CLAUDE.md is better than nothing. If your choice is between a handcrafted config file and zero project context, write the config file.
But recognize what it is: A manual, unscoped, untyped workaround for a tool that doesn’t have memory. The effort you spend maintaining it is effort that should be spent on actual work. The fact that the file needs to exist at all is evidence that the tool is missing something fundamental.
The AI coding tool you use in two years won’t have a config file for project conventions. It’ll know your conventions because it learned them. The time we’re spending today debating the perfect .cursorrules format will look, in retrospect, like debating the optimal way to hand-crank a car engine.
The engine should just start.
