AGENT.md: Why your README matters more than AI configuration files
August 22, 2025
The AGENT.md specification emerged in July 2025 as an attempt to solve a real problem: developers maintaining separate configuration files for each AI coding tool (.cursorrules, .windsurfrules, CLAUDE.md, and more). Created by Sourcegraph’s Amp team, AGENT.md promises “one file, any agent”. A vendor-neutral standard to unify AI assistant configuration. But a surprising truth has emerged: the proliferation of AI configuration files has inadvertently revealed that most projects have terrible documentation, and fixing your README is more important than adopting any new standard.
Source: AGENT.md: Why your README matters more than AI configuration files – Upsun Developer Center
Write good documentation is the “eat your vegetables” of the developer world. We all know we should do it, but time and again it’s likely we cut corners, took shortcuts, and our documentation wasn’t quite up to the standards that we’d expect even of ourselves.
Turns out documentation is not just valuable for your fellow developers and yourself months later when you revisit your code and scratch your head at what on earth it is doing. It’s also valuable for coding agents because the more context you can provide for your code and what it is doing, the better able agents are to work with it.
So, eat your Brussels sprouts and write your documentation, ironically perhaps with the help of some large language models.
