Keeping AGENTS.md Files Accurate: Why Stale Agent Instructions Are Worse Than None

Short summary

An AGENTS.md file rots the day you write it, and unlike a stale README, a coding agent follows its instructions with full confidence — wrong commands, missing guardrails, dead conventions all executed without question. The fix is ensuring every line traces to a verifiable fact and updating the file in the same PR as code changes. Keep it to 20-50 lines covering orientation, real commands, file locations, conventions, guardrails, and a mechanical definition of done.

• •Stale AGENTS.md files cause agents to confidently execute wrong instructions
• •Every line must trace to a verifiable fact — real commands, files, constraints
• •Update AGENTS.md in the same PR as code changes; treat it like code

Generated with AI, which can make mistakes.