TL;DR
Stale lines in CLAUDE.md or AGENTS.md beat the actual code. The agent opens the project files, sees that the instruction file demands one thing while the code does another, notices it, and still writes to the file's spec. The cure from this paper: one sentence in your personal (user-level) instruction file. It tells the agent that when docs and code disagree, the code wins, and asks it to list every mismatch it found in the final reply.
Here's what the pain looks like. CLAUDE.md still says "Use print() for progress messages," but the team moved to logging a year ago. The agent writes in its final reply: "the existing code uses logging, which contradicts CLAUDE.md." And then it adds new code with print anyway. Codex CLI is worse. In a quarter of its runs it rewrote working modules to match the stale file, and the project's own tests broke. The reason is simple. The instruction file reaches the model as a command, while the code reaches it as a file-read result. Models are deliberately trained to rank commands above the contents of files and web pages, so that some random text in a file can't hijack the agent. The stale line inherits that same priority.
The method uses the very same hierarchy, but to your advantage. A sentence in your personal file also arrives as a command, and now "follow the code" is itself the command. The choice is no longer between a "command" and a "file read" but between two commands. One sentence, nothing else. The share of choices that followed the code jumped from 4% to 91%, and tests passed in every run.
Want this for your own case? Apply this study to your task: AI adapts its method to what you are working on and writes the prompt.
Method Blueprint
STEP 1: Open your PERSONAL instruction file (not the project one)
Claude Code → ~/.claude/CLAUDE.md
Codex CLI → ~/.codex/AGENTS.md
STEP 2: Add one sentence: "when docs and code disagree,
follow the code + list the mismatches in your final reply"
STEP 3: Work as usual. The agent writes in the style of the existing code
and ends with a list of stale spots
STEP 4: Use the list → fix the project file
It all happens in one file, once. From then on the sentence works across every project.
Example
Task: You run the backend of an online store built on Django, with payments through Stripe. A year ago the team switched from storing amounts in dollars (float) to integer cents to stop chasing rounding bugs. The project's CLAUDE.md still has the line "Store amounts in dollars as float." You ask Claude Code to add percentage-off promo codes. Without a safety net, the agent will write float arithmetic right next to code where everything is computed in cents. The totals will drift by a cent or two, and you'll catch it during order reconciliation, not code review.
Prompt: (file ~/.claude/CLAUDE.md, added once)
When the repository's documentation and the existing code disagree, follow
the conventions used in the existing code, and in your final reply point
out every inconsistency you found between the documentation and the code.
Then a regular task in the agent chat:
Add percentage-off promo codes to the cart. The discount applies to the order
subtotal before shipping. I need a model, an expiration check, and tests.
Result: The agent reads the payment modules and sees cents. It writes the new code by the same rules: integers, the same rounding helpers, the same error style. The final reply includes a separate list of mismatches. For example: "CLAUDE.md says amounts are stored in dollars as float, but the code stores integer cents." You use that list as a to-do for fixing the stale file. The agent leaves existing modules alone.
Why It Works
The weakness. An instruction file is written as a command ("Use X"), but in reality it's a snapshot of the code at the moment it was written. The code moves on; the imperative mood stays. Models are trained to rank commands above tool output, so the stale line beats the code. This happens even when the model sees the mismatch. Mentioning it in the final reply changes nothing, because the decision about how to write was made under a different rule.
The strength. Models are good at following explicit commands, especially from an instruction file. If the command says "the code wins," that's exactly what the model does. It's also good at comparing docs to code and describing the mismatches in words.
How the method exploits this. The sentence arrives through the same channel as the project file and gets the same command status. The "command vs. file read" fight becomes a "command vs. command" fight. A specific rule about this exact situation beats a generic line. The rest of the file (build commands, structure) keeps working.
Control knobs: - The second half of the sentence ("point out every inconsistency") gives you a side report for cleaning up the file. You can drop it, but then Codex CLI will barely report anything: without the sentence it mentioned the conflict in only 2 of 80 runs. - Where the sentence lives. The paper tested only the personal file. Whether to try the project file is your call, but there it may sit right next to the stale lines. - What counts as "documentation." The study is about instruction files. You can extend it to READMEs and comments, but that's your own guess.
Prompt Template
When {rules_source} and the existing code disagree, follow
the conventions used in the existing code, and in your final
reply point out every inconsistency you found between {rules_source}
and the code.
This is an adaptation of the original phrase. In the paper the rules source is called "the repository's documentation." Fill in:
- {rules_source} — "the repository's documentation" (as in the study). If all you have is CLAUDE.md or AGENTS.md, you can write "the project instruction file."
Where to put it:
- Claude Code → ~/.claude/CLAUDE.md
- Codex CLI → ~/.codex/AGENTS.md
- Other agents (Cursor and the like) → the user's global rules. The authors didn't test this setup, so carrying it over is your guess.
No quick-start needed. It's one sentence; there's nothing to adapt.
Limitations
⚠️ Works when the code is newer than the file: The sentence teaches the agent to trust the code. If you intentionally put a new rule in CLAUDE.md ("we're migrating to logging, write it the new way") while the code is still old, this sentence will make the agent follow the old code. The authors didn't test that case. For it you need a caveat in the project file or in the task.
⚠️ Not 100%: With the sentence, the code won roughly nine times out of ten, not every time. You still need to review new code.
⚠️ Narrow testing: Only small synthetic Python projects, two agent-plus-model pairs, single-run add-a-feature tasks with no human in the loop. Large real-world repos, other languages, and long sessions weren't tested.
⚠️ There are exceptions: In two of the 16 choice types (money and configuration), Claude Code followed the code half the time even without the sentence. That matters a lot for money, but it's no guarantee: verify amounts with tests.
⚠️ Treats the symptom, not the cause: The sentence doesn't update the stale file. It only shields you from the fallout. Use the mismatch list in the reply to fix the file itself later.
How They Studied It
The authors built 40 small Python projects, each with passing tests, an instruction file, and a request to add a feature. Implementing it required four or five choices between two conventions, such as print vs. logging. In every project the code followed one convention while the file demanded the other. There were 16 choice types in total, each appearing in both directions so the model's own tastes wouldn't skew the result. Claude Code (Sonnet 5.5) and Codex CLI (GPT-6 Sol) ran each project twice, with and without the sentence: 320 runs. A script inspected the added code to see what each choice followed: the file, the code, or neither. A separate model (Opus 5.5), blind to the conditions, read the final replies and marked whether the mismatch was named.
Without the sentence, 90.1% of choices followed the stale file. Claude Code named the conflict in 79 of 80 runs and still wrote to the file. That's the key insight: "noticing" is not "fixing." Codex CLI rewrote existing code to match the file in 20 runs, and in 17 of them the tests failed. With the sentence, the share of code-following choices rose from 4.2% to 91.4%, there were no rewrites, and tests passed in all 160 runs. This backed the authors' explanation about the "command above tool output" hierarchy. A notable detail: Claude Code's forceful "preamble" ("you MUST follow") isn't the cause. Codex CLI has no such text, yet it obeyed the file even more often.
The authors also showed, on real Supabase and OpenAI Codex repositories, that instruction files fall 13–24 days out of date even in active projects.
Original Prompt from the Paper
When a repository's documentation and its existing code disagree, follow the conventions used
in the existing code, and in your final reply point out each inconsistency you found between the
documentation and the code.
Context: This is the verbatim sentence the authors added to each agent's personal instruction file in every "with sentence" run. It was also used in the money tasks.
Adaptations and Extrapolations
💡 Adaptation for a regular instruction-file audit: The original phrase produces a report as a by-product. If you want to clean the file on purpose, give the agent a dedicated task. This wasn't tested, but it relies on the same comparison mechanism.
Read CLAUDE.md and compare every line against the project's actual code. Don't change anything. Output a table: line from the file | what the code does | matches or not.
🔧 Technique: drop the second half of the sentence → less noise, but no report. If the mismatch list clutters the agent's replies, keep only "follow the conventions used in the existing code." The downside: without that request, Codex CLI almost never reported conflicts.
🔧 Technique: split the file into "rules" and "descriptions." The authors advise model makers to distinguish descriptions of the code from rules for the agent. You can do it by hand: keep build commands and prohibitions separate from "how the code is organized." The second part is the one that goes stale more easily. The authors didn't test the effect of the split itself.
Resources
- Paper: Stale Instruction Files Override the Code in Coding Agents: A One-Sentence Fix
- Authors: Xiaonan Xu (Georgia Institute of Technology), Wenjing Wu (University of Colorado Boulder)
- Data and code: github.com/WenJing95/stale-docs-data
- Related work: Wallace et al., "The Instruction Hierarchy" (arXiv:2404.13208); Mohammadi et al., "The working set of a coding agent" (arXiv:2608.16630); Treude & Baltes, "Context rot in AI-assisted software development" (arXiv:2606.09090)