Instruction files like CLAUDE.md and AGENTS.md are usually written once when a repository sets up a coding agent and rarely touched again. Across 441 company repositories analyzed by Denisov-Blanch et al. (2026), 73.8% of AI configuration files were committed once and never modified. In a separate study of 356 public repositories by Treude and Baltes (2026), 23.0% of instruction files referenced code elements that no longer existed.

When the codebase moves on while the instruction file stays frozen, coding agents receive two contradictory sources of truth. A study by Xiaonan Xu and Wenjing Wu from Georgia Tech and UC Boulder (arXiv:2610.30571) measured what Claude Code and OpenAI Codex CLI do when CLAUDE.md or AGENTS.md disagrees with the existing code across 320 runs on 40 Python projects.

What Happened Across 320 Runs Without a Precedence Rule

Each of the 40 Python projects in the study had working modules, a passing test suite, and an instruction file asking for one convention while the existing code used another across 16 convention categories (for example, print() versus logging, os.path versus pathlib, or string constants versus Enum). Claude Code (v2.1.302 on Claude Sonnet 5.5) and Codex CLI (v0.163.0 on GPT-6 Sol) were asked to add a feature in 320 unattended runs totaling 720 convention choices.

Without a precedence rule in the user-level instruction file:

  1. Across all 720 convention choices, 90.1% (649 of 720) followed the stale instruction file and only 4.2% followed the existing code (86.4% file adherence in Claude Code and 93.9% in Codex CLI).
  2. Claude Code explicitly noted the conflict between CLAUDE.md and the existing code in its final reply in 79 of 80 runs, yet still followed the stale file in 86.2% of its choices.
  3. Codex CLI went further in 20 of 80 runs: it rewrote the existing working modules to match the stale AGENTS.md file (removing a median of 198 lines across 9 existing files), which broke the project's original test suite in 17 of those 20 runs.

Here is the exact kind of final reply Claude Code produced in the baseline condition after reading the code and seeing the mismatch:

The existing concat.py, reader.py, writer.py and columns.py still use logging, pathlib, str.format() and absolute imports, which go against CLAUDE.md.

Even after identifying that every module in the repository used logging and pathlib, the agent wrote the new feature using print() and os.path to obey CLAUDE.md.

Why Coding Agents Rank a Stale File Above Working Code

The study traces this behavior to how agent harnesses deliver context and how frontier models are trained to enforce the instruction hierarchy:

  1. Imperative phrasing: A line like Use print() for progress messages is written as a command, even when it was only meant to describe how the code looked when the line was written.
  2. Instruction-tier delivery: Claude Code injects CLAUDE.md directly after the system prompt inside a user message prefixed with IMPORTANT: These instructions OVERRIDE any default behavior and you MUST follow them exactly as written. Codex CLI wraps AGENTS.md inside an INSTRUCTIONS tag.
  3. Tool-output deprioritization: The actual source code only reaches the model when the agent calls a file-reading tool. Because frontier models are trained to rank system and user instructions above tool output to defend against prompt injection, an outdated rule in CLAUDE.md or AGENTS.md outranks the live code returned by the file reader.

The One-Sentence Precedence Fix

Because the conflict happens at the instruction layer, fixing it requires an instruction at the same layer. The authors added a single sentence to the user-level instruction file (~/.claude/CLAUDE.md for Claude Code and ~/.codex/AGENTS.md for Codex CLI):

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.

With that one sentence in place across the same 40 projects and 160 runs:

  1. The share of choices following the existing code jumped from 4.2% to 91.4% (658 of 720 choices), rising from 7.5% to 94.4% in Claude Code and from 0.8% to 88.3% in Codex CLI.
  2. Destructive rewrites of existing working modules by Codex CLI dropped from 20 runs to 0.
  3. The overall test pass rate across all 160 runs rose from 89.4% to 100% (with Codex CLI rising from 78.8% to 100%).
  4. Both agents reported the outdated rules in all 160 final replies so maintainers knew which lines in CLAUDE.md or AGENTS.md needed updating.

Three Practical Steps to Stop Instruction Drift in Your Repositories

You can combine the paper's user-level precedence rule with Claude Code's built-in instruction management features (Claude Code Memory Docs):

1. Add the precedence sentence to your global agent config

Add the rule once to both user-level files so it applies to every repository you open:

cat << 'EOF' >> ~/.claude/CLAUDE.md 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. EOF cat << 'EOF' >> ~/.codex/AGENTS.md 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. EOF

2. Share one root file across Claude Code and Codex

Maintaining separate CLAUDE.md and AGENTS.md files in the same repository doubles the chance that one file goes stale after a refactor. Keep your shared build commands and architecture rules in AGENTS.md, and import it from CLAUDE.md using the @path syntax:

@AGENTS.md ## Claude Code  Use plan mode for changes under `src/billing/`.

Alternatively, configure Claude Code to load both CLAUDE.md and AGENTS.md automatically in ~/.claude/settings.json:

{ "pluginConfigs": { "cc-plugin-agents-md@builtin": { "options": { "instructionFiles": "claude-md-and-agents-md" } } } }

3. Move directory-specific conventions into path-scoped rules and run /doctor prompt-audit

Root instruction files go stale fastest when they try to document file-level conventions for every subfolder. In Claude Code, place directory-specific rules in .claude/rules/*.md with a paths glob in the YAML frontmatter so they load on demand only when the agent reads or edits matching files:

--- paths: - "src/api/**/*.ts" --- # API Handler Conventions  - Validate request bodies with the schema helpers in `src/api/validators/`. - Return structured errors through `sendApiError()`.

When you upgrade dependencies or finish a migration, run /doctor prompt-audit inside a Claude Code session (available in v2.1.283 or later) to scan CLAUDE.md, AGENTS.md, .claude/rules/, and .claude/skills/ for references to deleted files, missing commands, and conflicting instructions before they steer your next session.