I spent forty minutes last month debugging why an agent kept putting new endpoints in a folder we abandoned two refactors ago. The code was fine. The tests were fine. The agent was doing exactly what it was told, because the instruction was still there in the rules file, and the rules file was wrong.
That is the thing nobody warns you about. A stale rule does not error. A deleted dependency errors. A renamed function errors. But a line in CLAUDE.md that says “always register handlers in routes/legacy.js” keeps working perfectly right up until it produces a confident, well-formed, completely wrong result. The agent trusts the file. You wrote the file. So you trust the output. That is how a lie propagates with a green checkmark.
Why rules go stale faster than you think
There is an old line, cache invalidation and naming things, that Martin Fowler collects among the two hard things in computer science. A rules file is a cache. It is a cached snapshot of how your repo worked on the day you wrote each line, and like every cache it has no idea when the underlying thing changed.
The code has a forcing function keeping it current: it runs, and if it is wrong it breaks. The rules file has none. Nothing executes CLAUDE.md. No test fails when a rule stops being true. It drifts silently while you are busy shipping, and every agent that reads it inherits the drift at full confidence. The better your agents follow instructions, the more damage a wrong instruction does, because they will not second-guess it.
And these files rot faster than documentation ever did, for a simple reason: agents move the codebase faster than you update the prose about it. You merge six agent-written changes in a morning. You update the rules file maybe once a week. The gap between what the repo does and what the file claims widens every single day you do not look.
the code
- runs
- breaks when wrong
- stays true
the rules file
- never executes
- no error when wrong
- drifts silently
The three ways a rule turns into a lie
Not all stale rules are the same, and they need different detection.
The dangling reference. The rule points at a file, folder, script or command that no longer exists or was renamed. “Run ./scripts/deploy.sh” after you moved to a Makefile. These are the easy ones, because they are mechanically checkable. If a rule names a path, the path should resolve.
The abandoned convention. The rule describes how you used to do something. “We use class components.” “State goes in Redux.” Still grammatically valid, still followed by the obedient agent, and completely out of step with the last thirty merges. These are the dangerous ones, because nothing about the rule looks broken. Only the codebase disagrees with it.
The decision that reversed. The nastiest kind. “Never add a database index without review” made sense when one person owned the schema. Now it is a bottleneck, and the team quietly stopped enforcing it, but nobody deleted the line. The agent enforces a policy the humans already abandoned. This one is why decisions should not live in rules files at all, which is the argument in where your decisions should actually live.
How to detect the drift before it costs you
You cannot eyeball a rules file into correctness. You need cheap, repeatable checks.
Start with the mechanical layer. Every path, filename and command in the file should resolve against the current repo. This is a script you can run in CI: grep the rules file for anything that looks like a path or a command, and fail the build if it does not exist. It catches the entire dangling-reference class for almost no effort, and it turns “the rules file is wrong” from a debugging surprise into a red pipeline.
For the conventions, the check is different: use the agents themselves. Periodically, hand an agent the rules file and the current codebase and ask it a narrow question. “Which of these instructions does the actual code contradict?” Not “improve my rules,” which produces slop, but a specific audit against evidence. The agent reading fresh will spot the class component rule against a codebase full of hooks faster than you will, because you stopped seeing that line months ago. This is verification pointed at the instructions instead of the output, and it belongs in the same family as everything in context engineering for coding agents: the file the agent reads is context, and context that lies is worse than context that is missing.
For the reversed decisions, no script helps, because the code and the rule can both be internally consistent while the reason is dead. The only real detection is provenance: a rule you cannot trace to a decision with a date and a reason is a rule you cannot trust. If you do not know why a line is there, you cannot know whether it should still be.
Keeping them alive without a second job
The goal is not a perfect rules file. It is a rules file that fails loudly instead of lying quietly. A few habits get you most of the way:
- Date the load-bearing rules. A one-line reason and a date next to a real constraint. When someone hits it later, they can tell a live decision from a fossil.
- Make the mechanical check part of the pipeline. Broken paths and dead commands should fail CI, not surface at 2am when an agent follows them into a wall. That failure mode connects straight to recovery as a first-class workflow, because a stale rule is one of the quietest ways a long run goes off the rails.
- Prune on a schedule. Rules files only grow if you let them. Every rule you delete is one fewer thing an agent can misapply.
- Keep the decisions out. Operational facts belong here. Product decisions belong in an artifact that persists outside the chat and carries their reason. A convention drifting is annoying. A decision drifting is a rewrite.
Where PaellaDoc fits
A rules file goes stale because nothing forces it to stay true, and the thing reading it cannot tell. That is the same failure as documentation rotting, and the fix is the same: instructions that live close to the code they govern and get re-derived from evidence instead of typed once and trusted forever, the idea behind the product brain that maintains itself. PaellaDoc keeps the operational contract and the product decisions as checked artifacts, not free text an agent reads on faith, so a rule that stops matching reality shows up as a failed gate rather than a confident wrong answer. Because the person holding all of this in their head is the runtime until something else does the checking.
FAQ
How often should I update CLAUDE.md or AGENTS.md?
Continuously for the mechanical parts and on a schedule for the rest. Wire a check that fails your build when a path or command in the file no longer resolves, so dangling references get caught the day they appear. Then do a deliberate audit of the conventions every few weeks, ideally by having an agent compare the rules against the current code.
How do I know if a rule is out of date?
Three signals: it references a path or command that no longer exists, it describes a convention the recent commits contradict, or you cannot say why it is there. The first is scriptable, the second an agent can audit against the codebase, and the third means the rule has no provenance and should not be trusted until it does.
Should I just let the agent maintain its own rules file?
Use the agent to detect drift, not to rewrite the file unsupervised. “Which instructions does the code contradict?” is a good question with a checkable answer. “Rewrite my rules to be better” produces plausible slop. Keep the human deciding what stays; let the agent do the finding.