README for people, AGENTS.md for agents
Why every repository of mine has four documents, and why a person and an executor must never get the same text.
Every repository of mine — from a Go library to a wrapper around someone
else’s image — has four files: README.md, CONTRIBUTING.md, CHANGELOG.md
and AGENTS.md. All four are required, with no exceptions by repository type.
There is one main rule: README, CONTRIBUTING and CHANGELOG are written by a person for a person. AGENTS.md is written by an agent for an agent. They don’t mix in either direction.
Why one text won’t do
A document addressed to both readers serves neither. The person is put off by machine density: lists of commands, invariants, prohibitions with no explanation. The executor is put off by everything else: introductions, reasons, invitations to “read this to get the idea”. In the end each reads half and misses what matters.
Hence a few consequences you can check at a glance:
- the human files never mention “agents” or “AI” — they are written as if agents didn’t exist;
- the human files don’t link to AGENTS.md: for their reader it isn’t there;
- AGENTS.md doesn’t say hello or explain “why this matters to people”; it lists facts, commands and prohibitions;
- AGENTS.md is self-contained and repeats the facts it needs. This is the only duplication allowed, and it is deliberate.
Four files, four questions
| file | reader | question |
|---|---|---|
| README | someone opening the repository for the first time | what is this and how do I use it |
| CONTRIBUTING | someone about to change something | how to change it and what gets checked |
| CHANGELOG | someone updating the version on their side | what changed and what will break |
| AGENTS.md | an executor starting work | what lives where, what must stay true, what is forbidden |
“But there’s nothing to write here”
The most common objections, and why I disagree with them:
- “It’s a one-person repository, there’s no one to agree with.” You are agreeing with yourself a year from now. CONTRIBUTING is the only place that records why things are done this way and not another.
- “The executor will figure it out from the code.” It will figure it out and do it its own way: the code shows neither the prohibitions, nor what is generated, nor which check has to stay green.
- “It’s three lines, what code style?” Three lines follow rules too: one source of truth, generated files are not edited by hand, the build runs in the pipeline.
A missing file of the four is as much a defect to me as a red build. It sounds strict, but in practice it saves time: neither people nor agents have to guess anymore.