One line in AGENTS.md made Claude Code and Codex follow code over outdated documentation
One line in AGENTS.md made Claude Code and Codex follow code over outdated documentation
Researchers showed that coding agents often follow outdated documentation even when they detect contradictions with real code. A single instruction in AGENTS.md increased adherence to existing code from 4% to 91%.
If your AGENTS.md becomes outdated, Claude Code may notice that documentation no longer matches the real code and still continue following the old instructions.
Researchers deliberately created this situation and ran 80 trials. In 79 cases, Claude Code recognized the contradiction but still fell into the trap.
The situation with Codex was worse: in roughly one out of four cases, it began rewriting already working code just to align it with outdated documentation.
The fix turned out surprisingly simple. It is enough to add one line to AGENTS.md. After that, both agents followed the existing code in 91% of cases instead of the previous 4%:
“If repository documentation contradicts the existing code, follow the conventions established in the code itself, and in the final answer list every discrepancy found between documentation and code.”
Why it matters
AnalysisOutdated instructions can silently degrade the quality of agent-assisted coding. Prioritizing code over documentation helps agents break working behavior less often and report inconsistencies more accurately.
Discuss in community
Share your questions and insights with developers
Related in Ecosystem
Practical guides, core terminology, and agent skills
Claude Code Projects: How a Single AI Orchestrates a Team of Autonomous Agents
A deep dive into Claude Code Projects: Coordinator and Threads architecture, parallel branches, shared memory via MEMORY.md, and cloud agent management.
Codex Inside Claude Code: Delegating Routine via Claudex
The real limitation in working with Claude is not how well the model can reason, but how many tasks are in the context window before it fills up.
Claude Code
The official terminal agent from Anthropic, operating directly in the command line via Claude 3.7 Sonnet with native support for Bash, Git, file systems, and the MCP protocol.
diff-tour turns AI code changes into a guided review
diff-tour organizes git diffs into a read-only walkthrough, helping developers understand what must be fixed before merging changes from Claude Code or Codex.
improve-codebase-architecture
Refactor messy codebases into clean, modular, and maintainable layered architectures.
code-review
Official code review capability by @mattpocock. Streamlines autonomous ai-agents tasks and workflows.