Rohit Ghumare · July 31, 2026 · 5 min read

The AGENTS.md Genre

Somewhere in the last two years, without anyone announcing it, repos grew a second README. It goes by AGENTS.md or CLAUDE.md or a handful of other names, always in capital letters, and it is the first document in the history of software written primarily to a machine rather than about one.

We spent forty years making configuration more machine-readable. INI gave way to XML, XML to YAML, YAML to TOML, each step stricter and more parseable than the last. Then the most important configuration file in the repo turned out to be paragraphs of English prose. (The machines learned to read our language, and our response was to immediately start writing them memos.)

And it is already a genre, with conventions as recognizable as a haiku's. There is the shouted modal verb: NEVER commit directly to main, ALWAYS run the linter first. There is the bulleted commandment list. There is the section that patiently explains the build system the way you would to a bright intern on their first morning. Open five of these files from five unrelated companies and you will find the same rhetorical moves, arrived at independently, because everyone is negotiating with the same kind of reader.

My favorite property of the genre: every rule is a scar. Nobody writes "NEVER run the database migration script twice" speculatively. Somebody ran it twice. The file is a fossil record of incidents, and you can read a team's operational history in it the way you can read a coastline's storms in its cliffs. The angrier the capitalization, the more expensive the memory. (I have written a few all-caps lines myself. I remember each incident personally.)

## Rules
- NEVER push directly to main            <- someone pushed to main
- ALWAYS check for an existing helper    <- someone wrote a fourth date formatter
- Do NOT "fix" unrelated tests           <- oh, someone definitely fixed unrelated tests

The genre is also drifting somewhere familiar: toward case law. The reader obeys the letter of the text, not the spirit, and it explores loopholes with the tireless creativity of a tax attorney. So the files grow qualifying clauses. "Do not delete files" becomes "do not delete files, including moving them to a temp directory, including renaming them out of the build path." Each edit is an amendment closing a loophole the previous wording left open. Common law took centuries to develop this texture; the average CLAUDE.md gets there in about six weeks.

There is a quieter oddity underneath. These files are read by machines but also, unavoidably, by people, and for a new hire they are the best onboarding document the team has ever produced. Honest, current, ruthlessly practical. All the things we claimed our wikis were. It turns out that when the reader actually obeys what you write, you finally write down what you actually mean. The machine did not just get instructions. It disciplined our documentation.

I do wonder where the genre goes. One future: models get good enough at inferring intent that the files shrink back down to a paragraph of taste, the way a senior engineer needs a sentence where a junior needs a checklist. The other future: the files keep accreting amendments and exceptions until every repo ships a small constitution, versioned and argued over, with the original rule buried under its own clarifications.

Forty years of engineering effort to make config unambiguous, and the endgame is a document whose interpretation we argue about. Which future do you bet on? I notice my own files are not getting shorter.