Project Instructions an Agent Actually Follows

What it is, and where the standard stands

By its own definition AGENTS.md is a "README for agents": one designated, predictable place in the repo where you hand the coding agent the project's context and rules.

Four things are worth knowing about its state in September 2026:

• There is an organisation behind it. The format is stewarded by the Agentic AI Foundation under the Linux Foundation, since December 2025. Most of the large model developers and cloud providers are founding members.
• It is widespread. More than 60,000 open source projects use it, and roughly 26 tools read it.
• It has no format. "Plain Markdown. Use whatever headings you like, the agent simply reads the text." There are no required fields, and no versioned, normative specification either.
• The location is fixed: the root of the repo. With nested packages, each one may carry its own.

Having no format is the standard's strength and its weakness at once. A strength, because you can adopt it in five minutes. A weakness, because nothing tells you what belongs inside — and that is why most of these files end up unusably long.

Which tool reads which file

Here is the most common trap, and the vendor documentation is worth quoting word for word: one of the big terminal agents reads its own file, not AGENTS.md.

The fix is simple and worth adopting: keep one source, and let the rest point at it. Either with an import from the other file, or with a symlink. On Windows a symlink needs administrator or developer mode — there, the import is the way.

Precedence differs too. In one tool the personal instruction is strongest, then the repo, then the organisational one. In another, the files do not override each other, they concatenate, running from the root down towards the working directory.

What measurement tells us — and what it does not

There is a 2026 experiment on this, published at a conference, and its methodology is unusually clean.

Ten repos, 124 pull requests, paired comparison: the same task, the same repo state, the same codebase — once with a project instruction file, once without. Isolated containers, a fresh checkout at the matching commit. Small changes only: at most a hundred lines, at most five files.

And now the caveat, without which all of this misleads: correctness was not measured. On a hand-checked sample of fifty tasks the authors confirmed only that "a non-empty, non-trivial code change matching the task" had been produced. A comprehensive evaluation of correctness was left to future work.

So here is what a project instruction file is demonstrated to do today: it makes the agent faster and cheaper, by roughly a fifth. That it makes the agent write better code, nobody has shown. This is not an argument against it — but it is an argument against treating it as a quality assurance tool.

How long should it be?

The three big vendors recommend three different numbers, and that in itself is instructive:

• Under 200 lines per file. The stated reason, word for word: "longer files consume more context and reduce adherence."
• Under 500 lines per rule, split across several composable rules.
• Under two pages.

The strictest of the three — 200 lines — satisfies all of them. Start there.

And there is independent research telling you where the real ceiling sits. A 2026 experiment tested five models to see what happens as you pile on more simultaneous rules: 10, 20, 40, 80, 120, 160 rules, in four different formats, with two placements, 960 calls per model.

The result: for every model, in every format, at eighty rules the share of "perfect answers" fell to zero. It did not degrade — it fell to zero. At a hundred and sixty rules every model sat at zero under every condition.

A 200-line file holds roughly 30–60 real rules. That is just under the ceiling — and now you know why the ceiling is where it is.

Why it is a suggestion, not an order

The vendor documentation says this itself, and it deserves to be taken seriously:

The contents of the project instruction file arrive after the system prompt, as a user message, not as part of the system prompt. The model reads it and tries to follow it, but strict compliance is not guaranteed — especially with vague or conflicting instructions.

Three practical consequences:

• Do not leave a contradictory rule in there. When two rules collide, the model "may arbitrarily pick one".
• An overwritten file achieves the opposite. The documentation, word for word: a bloated instruction file makes the model ignore your actual instructions.
• Emphasis can be abused too. If a line keeps getting skipped, put weight on it — but "if you emphasise many lines, none of them stands out".

There is a self-test question for every line, and it is the best filter you have: "If I deleted this, would something go wrong?" If not — delete it.

What is mandatory should not be an instruction

This is the most important technical advice in the article, and once again the vendor phrases it most precisely:

Unlike project instructions, which are advisory, hooks are deterministic and guarantee that the operation happens.

In other words: if you want the formatter to run before every commit, do not write that into the instruction file. Wire it up as a hook, or put it in CI. The instruction file exists so that the model understands the project — not so that you can compel it.

The structure that scales

1. ONE file in the repo root, UNDER 200 LINES.
   What holds everywhere: the goal of the project, the main
   commands (build, test, lint), the non-obvious conventions.

2. WHAT HOLDS FOR ONE PART ONLY -> a path-scoped rule.
   The rule about the API should load only when the agent
   touches an API file. All three major tools have their
   own format for this.

3. WHAT IS MANDATORY -> a hook or CI, not an instruction.

4. WHAT CONTRADICTS -> delete one of them. It is not the
   model's job to work out which one you meant.

5. SEVERAL AGENTS -> ONE source + import or symlink.
   Do not maintain three files with the same content.

6. REVIEW every quarter: for every single line,
   "if I deleted this, would something go wrong?"

The 37-page policy nobody follows

There is a 2026 measurement here that is not about coding, yet belongs exactly in this discussion.

Ten fictional companies, five business areas, 65 tasks, each paired with a company policy in a realistic format: 20–124 pages, median 37 pages, as PDF, Word and HTML. Between them the tasks carried 824 programmatically checkable acceptance criteria — required and forbidden actions.

The strict result: the best model reached 36.2%, and most frontier models stayed below 25%.

And the most telling detail: allow one single failed criterion per task and the scores roughly double. So agents do get through most of the work a policy governs — and then skip precisely the critical controls.

That is the strongest argument there is that a project instruction file does not replace review. A thirty-seven-page policy gets broken on at least one point by even the best model in two thirds of cases. What that leaves you to go through by hand is the subject of the reviewing generated code post, point by point.

Common misconceptions

• "Every tool reads AGENTS.md." No. One of the big agents deliberately reads its own file. Maintain a single source and let the rest point at it.
• "The more detailed it is, the better it is followed." At eighty simultaneous rules the rate of perfect adherence drops to zero. And a bloated file is how your real instructions get lost.
• "If I write it down, it gets done." It is advisory, it arrives as a user message, and strict compliance is not guaranteed. What is mandatory belongs in a hook or in CI.
• "It makes the model write better code." The measurement showed a 20% saving in tokens and in time. Correctness was not measured.
• "If I emphasise everything, everything gets followed." "If you emphasise many lines, none of them stands out."

What to take away

A project instruction file makes the agent faster and cheaper, not more accurate. Keep one file, in the repo root, under two hundred lines; anything that applies to only part of the code belongs in a path-scoped rule; anything mandatory belongs in a hook or in CI. And put the question to every line: if I deleted this, would something go wrong?

Handing out that first real task is what the first task with an agent post walks through; and where all of this should run is covered by the choosing a development setup post instead.