AGENTS.md Is a Config File, Not a Wishlist

AGENTS.md files often start off concise, but over time they can balloon into unwieldy documents filled with outdated rules and contradictory instructions. Rather than a documentation tool, AGENTS.md serves a more functional purpose: it is a configuration file that asserts conditions affecting how the agent interacts with the codebase.

As the code evolves, AGENTS.md can quickly become obsolete, with lines asserting things that no longer hold true. This decay is compounded when there are contradictions between the file's instructions and the actual code. The accumulation of outdated rules, known as "ghost rules," can distract and confuse the agent, leading to inconsistent behavior.

To combat this, the author advocates treating AGENTS.md as configuration, subject to version control, meticulous review, and stringent testing. Recommendations include versioning the file like any other code change, small size limits, golden set evaluations to verify behavioral impact, and periodic purging of lines that no longer hold true.

By applying these config discipline practices, AGENTS.md can remain short, factual, and reliable, serving as a true configuration guide rather than a wishful wishlist.