Documentation as Source-of-Lies
Repo context files often hurt agent success more than help. Docs drift, code moves on, agents follow stale instructions confidently. Code is source of truth; docs are hints.
Counterintuitive finding from recent agent benchmarks: providing repository context files (CLAUDE.md, AGENTS.md) often reduces agent task success compared to no context at all. The documentation drifts, the code moves on, and the agent dutifully follows stale instructions instead of reading the live source.
The mental model upgrade: docs are not source of truth, code is. Agents should be configured to read code first and treat docs as hints. The opposite default — docs first, code second — produces confident wrong answers because the agent trusts what's written over what's executed.
The fix is operational, not philosophical: every doc gets a freshness check against the code it claims to describe, automatically, on every commit. Stale docs get flagged or auto-archived. Otherwise they keep poisoning agents who can't tell the doc is lying.