AGENTS.md or a decisions log: the costs nobody names

Ask whether decisions belong in AGENTS.md or in a decisions folder and you get the same answer everywhere: use both. The instruction file carries how to work; the records carry what was decided; point one at the other.

That advice is correct. It is also useless, because it does not say what either one costs, and the reason teams get this wrong is not that they never heard "use both" — it is that both files quietly do the other's job until something breaks.

Here are the three costs, and they are the whole decision.

First, what these two things actually are

AGENTS.md is a README for agents: one predictable file at the repo root carrying build commands, test procedure, code style, and the boundaries an agent must not cross. It is read natively by more than twenty tools, is used by over 60,000 open-source projects by its own count, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. It is, in other words, a real standard rather than a convention somebody blogged about.

A decisions log — ADRs — is one file per decision, committed with the code, recording what was chosen and why it beat the alternative. It is much older than agents and it suits them better than anyone expected.

They are not competing formats. They are competing places to put a sentence, and that is the thing nobody is precise about.

Cost 1 — the instruction file is loaded every session

This is the one that decides everything else. AGENTS.md is ambient: it is read at the start of every session, whether or not anything in it is relevant to what you asked. A decisions folder is not — it is read when something points at it.

So a sentence you put in the instruction file is a sentence you pay for on every run, forever. In our own repository the instruction section is 591 bytes, which is nothing. That is the point: it is nothing because nothing lives there but rules.

The failure is gradual and it is the most common one. Somebody appends a note after a confusing session. Somebody else adds the reasoning behind a schema choice. Six months later the file is the project's entire memory, every session reads all of it, and the file that existed to save context is the largest fixed cost in the project. Nobody decided that. It happened one useful paragraph at a time.

The rule that follows: if it will not change what the agent does in most sessions, it does not belong in the file every session reads.

Cost 2 — pointing at the records moves the cost, it does not remove it

The standard advice is to reference docs/adrs/ from AGENTS.md and let the agent read the decisions when it needs them. Good. Now measure what "when it needs them" costs.

The agent has a question and a folder of prose. It does not know which files apply, so it greps, and grep answers with candidates, not answers. We measured that across five real questions: 1.3 MB → 39 KB — a megabyte of candidate documents where a link names thirty-nine kilobytes.

That gap is the cost of searching rather than knowing, and it is invisible in a small repository, which is where everybody evaluates this. It is also the cost that grows with the thing you were proud of: the more decisions you have recorded, the more expensive it becomes to find the one that matters.

A pointer is not free. It converts an ambient cost into a search cost, which is usually the right trade — and is still a cost you should be able to name.

Cost 3 — superseding is a convention, not an operation

This is the one that actually hurts, and neither format solves it.

Reversing a decision is two edits: write the new record, and mark the old one superseded. The second edit is not enforced by anything. It is a habit. Skip it once — and it is skipped under exactly the conditions where reversals happen, in a hurry, late — and the folder now states two contradictory things with no machine-readable way to tell which is current.

A human reading the folder notices the contradiction and resolves it from context. An agent does not. It reads both, and both look like accepted decisions, because in the file system they are.

AGENTS.md has the mirror of this problem and it is worse: because it is one mutable file, a reversal is a line being edited. There is no old version in the document at all. Git has the diff, but nothing in the file says the rule changed, when, or why — so the why was never recorded, it was overwritten.

Neither format makes reversal safe. Both rely on somebody remembering. If you take nothing else from this, take that the moment a decision gets reversed is the moment your record becomes wrong, and the only fix is to make superseding a thing the tool does rather than a thing you remember.

So what goes where

Follow the costs and the split writes itself:

• AGENTS.md: things that are true in most sessions and change what the agent does. Build and test commands with exact flags, style that differs from the default, and the boundaries — the files it must never touch. Keep it small enough that you would be happy to pay for all of it on every run, because you are.
• The decisions log: the reasoning. What was chosen, what it beat, and what would make you reverse it. Write one only when the decision was genuinely contested, or when the obvious choice was wrong for a non-obvious reason — the rest is noise that makes cost 2 worse.
• Neither: what happened. Task history, who moved what, what the last session actually finished. That is a different problem and both of these files are bad at it.

The test worth running on your own repo

Open AGENTS.md and, for every paragraph, ask: would this change what the agent does in a session that has nothing to do with it? Every "no" is a paragraph you are paying for on every run and should move.

Then take the last decision your team reversed and go and find its record. If it still reads as accepted, cost 3 is not theoretical in your repository — it has already happened and nobody noticed, which is precisely the shape of it.

---