TL;DR — A hand-written AGENTS.md rots the day you write it. And unlike a stale README (which a human skims skeptically), a stale AGENTS.md is obeyed by your coding agent with full confidence: wrong build command, missing guardrail, dead convention — followed to the letter. The fix isn't more discipline. It's writing the file so every line traces to a fact you can verify, and refusing to let it drift.
In the field guide, I covered what an AGENTS.md is and what belongs in it. In the build-along, we wrote a complete one against a real repo and watched an agent use it. This is the part nobody warns you about — the part that decides whether all of that pays off: keeping it true.
Why you need to know this
You probably already have an AGENTS.md — or you're about to. Here's the part nobody says out loud: it's a cache, and a stale cache is worse than an empty one.
A human reads a stale README and thinks "hmm, that looks old." An agent reads your AGENTS.md and acts on it — it runs the build command you renamed three sprints ago, skips the guardrail you added last week, follows the convention you already abandoned. Confidently. No second-guessing.
So the real question isn't "should I have an AGENTS.md." (Yes.) It's "how do I keep it true?"
How to do it
A good AGENTS.md answers exactly one question: how do I work in this repo? Not what the project is — that's the README. How to actually operate here. Six moves:
1. Orientation — one line. What it is, the language, the stack. Then stop.
2. The real commands. Setup, build, and — most important — how to run the tests. Copy-pasteable. Tests rank above build, because tests are the agent's only way to check its work against reality instead of trusting a stale belief.
3. Where things live. Entry points and key directories — not a file dump (the agent can run ls). Just the non-obvious "start here."
4. Conventions — only what resolves ambiguity. "Validate input at the route boundary with Zod" is useful. "Write clean code" is ignored. And if a rule is already enforced by your linter or formatter, point at the config — don't restate it.
5. Guardrails — what NOT to do. The landmines. Three tiers is the sweet spot: what's always safe, what to ask first, what to never do (force-push, touch prod, commit secrets).
6. A definition of done. "Done when lint passes, tests pass, changes committed." Make it mechanically checkable — the agent should be able to know it's finished, not guess.
Keep it short — 20–50 lines. Every line earns its place by one test: does it resolve a real ambiguity, or save the agent an expensive hunt? If it does neither, cut it. (Past ~150 lines you're adding cost with no gain.)
The part almost everyone gets wrong
There are two failure modes, and they're opposite:
Hand-written and left alone → it rots. You change the code; the file quietly lies.
"Let an AI write it for me" → it bloats. The research here is blunt: auto-generated instruction files measurably reduce task success and add cost, because the model pads them with plausible-sounding requirements the agent then over-obeys.
The fix is the same for both: every line should trace to a fact. A real command. A real file. A real constraint. Not prose, not padding, not guesses. And when the code changes, the file changes in the same PR — treat it like code, because your agent already does.
Get those two things right — facts only, kept current — and your AGENTS.md stops being a liability and starts being the most reliable thing in the repo.
Why we care about this
We maintain a lot of repos, and we kept paying the same tax: the AGENTS.md goes stale, everywhere, every week. Getting the file right is an afternoon. Keeping it true is the harder half — and it's the half that actually decides whether your agent helps you or confidently ships you the wrong thing.
Write one well. Keep it honest. Your agent is only as good as the last true thing you told it.
Further reading: the standard itself at .
Coming next: the exact discipline to keep it true — step by step, stopping the rot, with an agent you can watch trust it.
SOCIAL SHARE CARD GENERATOR