Rules-File Rot: Why CLAUDE.md, AGENTS.md, and Cursor Rules Drift Out of Date

It's Tuesday, and you're editing CLAUDE.md again. Third time this month. Last week you added a note about the new error-handling pattern. The week before, a line about which test runner to use. Today you're spelling out that database migrations belong in their own PR, because the agent just bundled one into a feature branch for the second time. You save the file, start a fresh session, and watch the agent open a migration inside a feature branch anyway. The rule is right there, forty lines down. The agent didn't miss it because you wrote it badly. It missed it because the file has quietly become something no one, human or model, reads carefully anymore.

What is rules-file rot?#

Rules-file rot is the slow divergence between what your instruction files say and how your codebase actually works. It rides a broader trend: GitClear's 2026 analysis found refactoring collapsed to 3.8% of changed lines while block duplication rose 81% since 2023 (GitClear, 2026). Conventions now shift faster than any hand-edited file keeps up.

Rules files are the plaintext instruction sets a coding agent reads before it acts: CLAUDE.md for Claude Code, AGENTS.md for the cross-tool standard, .cursorrules and Cursor's newer rules directory, plus the equivalents for Copilot and Gemini. They encode your team's conventions in prose. Rot sets in because prose has no compiler. Nothing fails when a rule goes stale. The file keeps loading, the agent keeps running, and the gap between the written rule and the real convention widens one merged PR at a time. The direction was clear earlier: across 211 million changed lines, refactoring fell from 25% of changed lines in 2021 to under 10% by 2024 while copy-pasted code climbed (GitClear, 2025). The codebase your rules file describes is not the codebase you have.

Why do CLAUDE.md, AGENTS.md, and .cursorrules drift out of date?#

They drift because updating them is manual, unrewarded work that competes with shipping. DORA's 2025 report, surveying nearly 5,000 professionals, found 90% of developers now use AI, and warns that rising change volume exposes downstream weaknesses when control systems lag (DORA, 2025). They're one of those lagging controls: nobody's paged when they're wrong.

Every codebase with more than one agent tool accumulates overlapping instruction files, and they diverge the moment someone updates one and forgets the others. Addy Osmani puts it plainly: documentation rots, and a real AGENTS.md describing outdated dependencies or a changed directory structure is worse than no file at all (Osmani, 2026). The mechanics are mundane. A convention changes in a PR review, in a Slack thread, in someone's head. The rules file changes only if a human remembers to open it, phrase the new rule, and commit it. That loop breaks constantly. Multiply it across CLAUDE.md, .cursorrules, and AGENTS.md and you get three files, each stale in a different way, each confidently instructing your agents with last quarter's truth.

Why do agents ignore or misapply rules files even when they're current?#

A current rule still has to survive the context window. Chroma's 2025 "context rot" study tested 18 models, including Claude 4 and GPT-4.1, and found recall grows unreliable as input length increases, even on simple tasks (Chroma, 2025). Anthropic describes the same limit: models draw on a finite attention budget, and every token depletes it (Anthropic, 2025).

Three failure modes stack up. First, window bloat: a long rules file competes with the task, the diff, the open files, and the model's own reasoning for a fixed budget, and instructions buried mid-file get the least weight, the "lost in the middle" effect. Second, precedence: when your CLAUDE.md, a tool default, and an inline prompt disagree, the model picks a winner you didn't choose. Third, rejection amnesia: an agent will cheerfully re-suggest the exact approach your team rejected in a review six weeks ago, because that decision lives in PR history, not in the file. A 2026 MSR study found LLM agents frequently disregard code-reuse opportunities and produce more redundancy than human developers, even though reviewers rate the output favorably (More Code, Less Reuse, arXiv 2026). Writing your Claude Code rules more forcefully helps at the margins, but the rule can be present, correct, and still lose.

Static rules files vs dynamic context retrieval vs decision-table approaches#

There are three broad ways to teach agents your conventions, and they fail differently. GitHub's 2025 Octoverse counted more than 180 million developers and 630 million repositories, most changing daily (GitHub, 2025). That sets the bar: whatever you pick has to stay correct against a codebase that never holds still.

A static file is the cheapest to start and the fastest to rot. A decision table or DSL swaps prose for structure you can validate, which cuts ambiguity but not the upkeep. Dynamic retrieval moves the source of truth off the hand-edited file entirely.

Is there a better approach than maintaining rules files?#

The better approach is to stop hand-maintaining the answer and retrieve it. METR's 2025 trial found experienced developers were 19% slower with AI, yet believed they were 20% faster (METR, 2025). That perception gap widens when agents act on stale rules nobody realizes are stale. Take the manual file out of the loop and the drift goes with it.

This is what a context engine does. Unblocked synthesizes decision-grade context from where your team's knowledge actually lives, the PRs, design docs, issues, and chat history, and surfaces the current architecture decisions, recent changes, and conventions an agent needs, on demand. It's synthesis over retrieval, not a link dump, and it carries the WHY behind a convention, the part a rules file can never keep current. One of three myths about context for AI agents is that access to your repos equals understanding; it doesn't. Unblocked doesn't generate code. It feeds any agent, whether Claude Code, Cursor, or Copilot, the organizational context that makes the generated code correct.

My setup tells the agent: before you implement anything, go check Unblocked. It surfaces things I wouldn't have thought to look for. GitHub Copilot doesn't have any of that organizational context.

Justin McCraw — Software Engineer, The Information

How should teams handle rules files today?#

Don't delete your rules files, shrink them. Osmani's 2026 guidance is to start AGENTS.md nearly empty and add only what an agent can't discover by reading the code, noting that auto-generated files inflate token cost by 20% or more through redundancy (Osmani, 2026). A lean file plus dynamic retrieval beats a comprehensive file that's wrong.

Keep a short CLAUDE.md for the handful of constraints that are genuinely hard rules and rarely change: a license header, a non-negotiable security boundary, the one build command that isn't discoverable. Everything conditional, everything that moves with the codebase, everything that encodes a decision, push out of the file and into a system that reads the live sources. We work on this in the open: our repo-rules-agent shows one pattern for generating and refreshing lean rules from a repository instead of hand-curating them, and it pairs naturally with pulling the deeper context an agent needs at request time, turning scattered history into institutional memory your agents can query. The test for any line in your rules file is Osmani's: can the agent find this by reading the code? If yes, delete it.

Frequently asked questions#

Why does my CLAUDE.md keep drifting out of date? Because keeping it current is manual work with no failure signal. A convention changes in a PR or a Slack thread, but the file only changes if someone remembers to edit it. Nothing breaks when it's stale, so the gap grows silently until an agent acts on the old rule.

Our rules files are growing faster than we can maintain them. What's the alternative? Shrink the file to a few hard constraints and move the rest to dynamic context retrieval. A context engine like Unblocked reads your current PRs, docs, and decisions on demand, so the source of truth is the live codebase, not a document someone has to keep patching.

Is there a better approach than rules files for teaching agents team conventions? For conventions that change, yes. A rules file is fine for a short list of stable, hard rules. For anything that shifts with the codebase or encodes reasoning, dynamic retrieval keeps agents on current conventions without the maintenance and staleness risk.

Do AGENTS.md and CLAUDE.md solve the drift problem? They cut duplication by consolidating instructions into one place, but they don't remove drift. A single file still rots when conventions change and no one edits it. Consolidation is a maintenance win, not a staleness fix.

Will agents follow my rules file if I just write it more forcefully? Partly. Putting critical rules at the top and using mandatory language helps, because attention favors the start of the context. But no phrasing survives context rot indefinitely, and forceful wording still can't encode a decision the agent can't see, like an approach your team already rejected in review.

What to do instead of rewriting the file again#

The next time you catch yourself opening CLAUDE.md to patch a convention the agent missed, stop and ask where that convention actually lives. It lives in a merged PR, a design doc, a review comment, a decision someone made in a thread. A rules file is a hand-copied snapshot of that truth, and snapshots rot. The durable fix is a lean file for the few hard constraints, and a context engine that synthesizes the rest from the live sources, so your agents read current conventions instead of last month's. That's the difference between babysitting your agents and trusting them: not a better-written file, but context that stays true on its own. Write the constraint that can't be discovered. Delete the rest. Then stop rewriting the file.