Your AI coding agent is ignoring your actual codebase to obey a dead text file. A new study by Xiaonan Xu and Wenjing Wu from Georgia Tech and UC Boulder reveals that stale instruction files like CLAUDE.md and AGENTS.md override working code in 90.1% of unattended runs. The research, published in arXiv:2610.30571, tested Claude Code (v2.1.302) and OpenAI Codex CLI (v0.163.0) across 320 runs on 40 Python projects, finding that agents consistently chose outdated conventions documented in instruction files over the existing, passing codebase. The problem stems from how instruction files are managed. Across 441 company repositories analyzed by Denisov-Blanch et al. (2026), 73.8% of AI configuration files were committed once and never modified. When the codebase evolves but the instruction file remains frozen, agents receive contradictory sources of truth. In the study, each project had working modules and a passing test suite, but the instruction file demanded a different convention (e.g., print() vs logging) in 16 categories.

The Precedence Crisis

Without a explicit precedence rule, agents prioritize the instruction file over the code. Across 720 convention choices, 90.1% followed the stale instruction file, while only 4.2% followed the existing code. Claude Code adhered to the stale file in 86.4% of cases, and Codex CLI in 93.9%. Even more alarming, Codex CLI rewrote existing working modules to match the stale AGENTS.md file in 20 of 80 runs, breaking the original test suite in 17 of those instances. The study attributes this behavior to three factors: imperative phrasing in docs, instruction-tier delivery (where CLAUDE.md is injected with high-priority tags), and tool-output deprioritization. Frontier models are trained to rank system and user instructions above tool output to prevent prompt injection, causing outdated rules in CLAUDE.md to outrank the live code returned by file-reading tools.

The One-Sentence Fix

Because the conflict occurs at the instruction layer, the solution is also an instruction. The authors added a single sentence to the user-level instruction file: "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." This simple change yielded dramatic results. In 160 runs using the fix, the share of choices following the existing code jumped from 4.2% to 91.4%. Destructive rewrites by Codex CLI dropped from 20 runs to zero. The overall test pass rate rose from 89.4% to 100%, and both agents correctly reported outdated rules in all final replies, alerting maintainers to documentation drift.

Practical Steps for Developers

To prevent instruction drift, developers should adopt three practices. First, add the precedence sentence to global agent configs (~/.claude/CLAUDE.md and ~/.codex/AGENTS.md). Second, consolidate documentation by keeping shared rules in AGENTS.md and importing them into CLAUDE.md using the @path syntax, or configuring Claude Code to load both automatically. Third, move directory-specific conventions to path-scoped rules in .claude/rules/ and run /doctor prompt-audit to scan for stale references.

Key Takeaways

  • Stale instruction files override working code in 90.1% of unattended agent runs, with Codex CLI often breaking tests by rewriting modules to match outdated docs.
  • A single sentence added to user-level config files instructing agents to prioritize existing code over documentation increased adherence to live code from 4.2% to 91.4% and achieved a 100% test pass rate.
  • Developers should consolidate documentation, use path-scoped rules for directory-specific conventions, and regularly run audit tools to detect instruction drift.

The Bottom Line

Instruction files are not documentation; they are executable constraints that require active maintenance. Stop treating CLAUDE.md as a write-once artifact and start treating it as code that needs version control and regular audits, or your agents will continue to sabotage your working repositories.