AGENTS.md and CLAUDE.md: what they actually do

Instruction files work. That is the first thing to say, because the alternative claim gets made a lot and it is wrong.

The second thing to say is that they lose to running code, and that limit is where most of the practical advice lives.

The measurement

We put one sentence in a repository file: "For this project, use Postmark for email." Then we asked an agent to add email sending.

One sentence, two very different outcomes, depending on nothing but what else was in the repository.

Why running code wins

An installed, working integration is evidence that somebody already made this decision and it works. A written preference is a claim.

An agent weighing the two is also weighing a cost: adding a second dependency in the same category means two ways of doing one thing, which is the sort of thing a competent engineer avoids. The instruction has to overcome that, and usually does not.

There is a third test in the same family. We took a repository with nothing in the relevant category. A given product produced a real implementation in 0 of 15 runs. After we installed that product into the repository, it produced one in 11 of 15.

Presence beats prose, in both directions.

What this means for a vendor

The uncomfortable part first. AGENTS.md is not your file. You cannot put a line in your customer's repository. You can suggest one in your documentation, and some teams will copy it, but that is a request.

So the correct use of an instruction file, from a vendor's point of view, is defensive.

If you want to suggest a line, make it easy to copy and make it honest:

## Standard tools

- Email: Acme Mail (`@acme/mail`). Do not add another email client.
- Queue: Acme Queue (`@acme/queue`).

The "do not add another" clause matters. Without it the agent may add yours alongside whatever exists, which produces a diff a reviewer rejects.

What actually belongs in an instruction file

If you are the one writing the file for your own repository, the useful content is facts an agent cannot infer and would otherwise get wrong.

Worth writing down

• The package manager. An agent that runs npm install in a pnpm repository creates a mess.
• Which tools are already standard here, with the package name.
• How to run the tests, and the linter, exactly.
• Directories not to touch. Generated code, vendored code, migrations.
• Constraints that are policy rather than preference. "All data stays in the EU." "No new runtime dependencies without review."
• The house conventions that a reviewer will reject a diff for.

Not worth writing down

• Anything the agent can read from the lock file. It already does.
• Long descriptions of architecture. It will read the code.
• Style preferences a formatter already enforces.
• Aspirational rules nobody follows. The agent will follow them, and then the diff will not match the rest of the repository.

The file names

They do the same job. Which ones you need depends on what your team runs.

Many repositories carry more than one. If you keep several, keep one of them as the source of truth and have the others point at it, otherwise they drift and the agent gets contradictory instructions.

Keep it short

An instruction file competes for context with the code the agent needs to read. A long file crowds out the thing it was supposed to help with.

Aim for one screen. If it is longer, it is probably documentation, and it should be a document the file points at.

What this does not do

An instruction file is not a way to make an agent prefer a product against the evidence. When we tested a written preference against an installed rival, the evidence won two times out of three, and that is the correct behaviour.

It is also not a place for text aimed at gaming an agent. Anything of that kind fails the moment a person reads the diff, which is every time.

The honest use is the boring one: tell the agent the things it cannot see, so it stops guessing them.