AGENTS.md, Kept True: Stop the Rot Step by Step (and Watch Your Agent Trust It)

Short summary

A practical guide to keeping AGENTS.md files accurate by tying every line to verifiable repo facts, running commands before documenting them, and making updates part of the same PR as code changes. It outlines six steps including listing real commands, enforcing conventions via linters, setting guardrails, and testing the file with real agent tasks. The core insight: treat AGENTS.md like code that must be continuously validated, not a one-time write.

• •Tie every AGENTS.md line to a verifiable repo fact — no aspirations
• •Make AGENTS.md updates mandatory in the same PR as code changes
• •Test the file by giving the agent a real task and fixing lines that cause failures

Generated with AI, which can make mistakes.