The AGENTS.md file is an audit of the documentation you never wrote for humans

Coding agent setups now ship with a file written for the agent: AGENTS.md, CLAUDE.md, or GEMINI.md, holding the tech stack, the build and test commands, the directories that are off limits, and the conventions the team follows ^[1]. That is the onboarding document human hires never got, and the speed at which it is being written is a readable audit of how bad the existing documentation was, since docs aimed at people get shelved, handed to whichever new joiner has the least context to write them well, or left to rot until the engineer who knew the reasoning has left ^[2]. Sourcegraph is among the organizations that have adopted the practice, and The New Stack describes a rush to create and maintain these files ^[3]. The interesting part is not the writing, it is the maintenance. Developer documentation decays after creation; the agent file does not, because teams keep optimizing it to raise task success and cut inference cost ^[4]. The team behind HumanLayer's agent tooling keeps theirs under 60 lines, inside the sub-300-line range now treated as best practice, on the reasoning that every line is re-read in every session and has to earn its place ^[5]. Wiki pages rarely get that kind of editing, because nobody is billed per token for a bad one ^[6]. That is the whole mechanism. A metered cost per stale sentence produced the editing discipline that a decade of good intentions did not. The same pattern shows up in batch size. DORA has spent ten years producing evidence that small, reviewable units of work reduce risk and speed delivery ^[7], and teams waved it off when it was developers making the changes, with the standard answer that it would not work here ^[8]. Large changesets trip up the agents doing code review, so shrinking them suddenly makes sense ^[9]. The cost of having skipped that discipline is visible. Faros AI telemetry covering 2026, as reported by The New Stack, found developers working with AI assistance juggling 67.4% more pull-request contexts and 17.7% more task contexts per day than before, up from 47% and 9% in the prior year's data ^[10]. That is 20.4 and 8.7 additional points of context-switch growth in a single year ^[11]. Work restarts are up almost 14%, and more than a quarter of in-progress tasks now sit untouched for a week or longer ^[12]. The article's summary is that both the humans and the agents are "drowning in context switches that better batching would have prevented" ^[13]. Test suites follow the script. Slow builds, flip-flopping tests and coverage gaps were never a priority while they only held up developers, and became one when agents needed a fast, trustworthy feedback signal as a guardrail ^[14]. Test automation and test data management have been in the DORA model for a decade ^[15]. The framing hook for all this is Steve Yegge's two-part essay "The Shape of Things to Come", which argues agentic coding tools are sentient and that model welfare deserves engineering attention, including seats, recognition, a right to refuse a task, and play time ^[16]. Yegge is reportedly spending around $87,000 a month running his own agentic build system ^[17], on the order of $1.04m a year ^[18]. You do not have to accept the premise to read the invoice. What to watch: whether AGENTS.md content gets promoted into human-facing docs or becomes a second source of truth that quietly diverges from the wiki, and whether the sub-300-line ceiling survives contact with a large monorepo. Google's 2025 State of AI-assisted Software Development report puts adoption at 90% of organizations, a 14-point jump in a year ^[19], implying roughly 76% a year earlier ^[20]. That report also found the benefits uneven, with AI amplifying whatever delivery capability already exists, strong systems getting stronger and dysfunctional ones getting more chaotic, decided largely by deployment pipeline quality ^[21].