One instruction file was built for one agent. The moment you add a second, every rule in it gets obeyed twice, billed twice, and misread once. Here's the three-layer layout that fixes it.
Picture the setup. A root AGENTS.md with one sensible line: "Run the full test suite before you consider any change done." One agent, that's fine. Then you add a planner, a coder, a tester, and a reviewer, and hand them all the same file.
The planner runs the test suite before it plans. The coder runs it after every edit. The tester runs it, which is at least its job. The reviewer runs it before reviewing. Four agents, one line, and the suite runs a dozen times per task, each one billed as tool output flowing back into a context window.
Nobody wrote a bug. Everybody followed the instructions. That is the whole problem with AGENTS.md in a multi-agent system, and it's worth getting right before you scale from one agent to five.
The file you wrote for one agent doesn't scale by copying it
Here's the part most guides skip. AGENTS.md was designed as a single file at the root of a repo, read by a single coding agent, and it's very good at that. It's now in 60,000-plus public repositories and is stewarded under the Linux Foundation's Agentic AI Foundation. Around thirty tools read it.
But the spec is deliberately thin. The FAQ says two things about conflicts: the AGENTS.md nearest to the file being edited wins, and anything typed directly into chat overrides all of it. That's it. What happens when three agents with three different jobs read the same file is left to the tools, and the tools disagree.
Codex concatenates every AGENTS.md from the root down to the working directory and caps the combined text at 32 KiB by default. Factory's Droid walks nearest-first. Claude Code doesn't read AGENTS.md at all; it reads CLAUDE.md, and the common workaround is a one-line @AGENTS.md import at the top. Three tools, three loading orders, one file.
"Nearest file wins" is a rule about directories. It says nothing about roles. A tester and a deployer in the same directory get the same instructions, and only one of them should be allowed to touch production.
Then there's the cost. An ETH Zurich study published in February 2026 tested context files across four coding agents on SWE-bench and a new benchmark built from repos with developer-written files. Every context file, human or LLM-written, increased inference cost and step count, by more than 20 percent. LLM-generated files nudged success rates down. Human-written files nudged them up by roughly 4 percent, and neither shift was statistically significant.
The behavioural finding matters more than the headline. Agents follow context files too faithfully. Mention uv instead of pip and agents invoke it 1.6 times per task versus almost never without the mention. That's great when the instruction is right and expensive when it's stale. Now multiply the 20 percent overhead and the obedience by every agent that loads the file.
Three layers, not one file
The fix that has held up in every multi-agent setup I've seen work is to stop thinking of AGENTS.md as the instructions and start thinking of it as one of three layers.
Layer one: root invariants. The root AGENTS.md holds only what is true for every agent in every directory. Toolchain choices, the test command, the branch naming rule, the "never commit secrets" line. If a rule doesn't apply to every agent, it doesn't go here. Aim for under 60 lines. The ETH data says a bloated root is worse than no root.
Layer two: scope files. Nested AGENTS.md files in the directories that have their own conventions. packages/api/AGENTS.md knows about migrations. packages/web/AGENTS.md knows about component rules. This is what the nearest-file-wins rule was built for, and OpenAI's own monorepo reportedly runs about 88 of them. Scope files describe places, never roles.
Layer three: role files. This is the layer the spec doesn't cover, so you build it with whatever your tooling gives you. In Claude Code it's a markdown file in .claude/agents/ whose body becomes that subagent's system prompt. On OpenClaw it's a per-agent SOUL.md alongside a per-agent AGENTS.md in each agent's workspace. On a hosted platform it's the per-agent instruction field. The role file says what this agent is for, what it may touch, and what it must hand back.
Root answers "what is always true here." Scope answers "what is true in this folder." Role answers "what is true for you." A rule in the wrong layer is a rule that will be obeyed by the wrong agent.
The tester's role file says "run the suite and report failures as a list." The coder's says "do not run the full suite; run the tests for the files you touched." The reviewer's says "read only; never execute." Same root, same scope files, four different behaviours. The dozen redundant test runs from the opening go away without deleting the rule that caused them.
What a subagent actually sees, and what it doesn't
This is where multi-agent AGENTS.md goes wrong quietly, because the failure looks like a model problem rather than a config problem.
Take Claude Code's documented behaviour, since it's the most explicit. A standard subagent starts with its own system prompt from the role file, the delegation message from the parent, the CLAUDE.md hierarchy, and basic environment details like the working directory. It does not get the parent's conversation history, the files the parent already read, or the parent's earlier tool calls. Only the subagent's final message comes back. The built-in Plan subagent skips CLAUDE.md entirely.
So if your root file says "we decided in the kickoff to use the v2 schema," the subagent that reads it has no idea what kickoff that was. And if the parent decided something at message 30 that never made it into a file, the subagent will happily contradict it at message 31.
Two rules fall out of this.
First, never put state in an instruction file. Decisions, current task, who's doing what: those change per run and belong in the delegation message or a scratch file the parent writes. AGENTS.md is for what's still true next week.
Second, the parent's delegation message is the real interface, and it deserves the same care as the file. Claude Code even warns you at startup if your combined subagent descriptions cross 15,000 tokens, because every description loads into the parent's context so it can decide whom to delegate to. Keep descriptions to a sentence. Put the detail in the role body, which only loads when that agent runs.
Anthropic's engineering team put a number on the stakes when they built their multi-agent research system: agents use roughly four times the tokens of a chat, and multi-agent systems roughly fifteen times. Every stray paragraph in a shared file is paid at that multiplier.
The handoff contract is the part everyone forgets to write
Single-agent AGENTS.md tells the agent how to work. Multi-agent AGENTS.md also has to tell each agent how to stop, and what to leave behind for the next one.
I've started calling this the handoff contract, and it's the most valuable forty lines in the whole setup. Each role file should answer four questions in plain language:
- What does "done" mean for you, specifically? A passing test list, a diff, a review with severity tags, a deployment log.
- What format do you return it in? Fixed headings, a JSON block, a file path. The parent and the next agent should never have to parse prose.
- What must you never touch? The coder doesn't edit tests. The reviewer doesn't edit anything. The deployer doesn't read source.
- When do you stop and escalate instead of continuing? A failing migration, a missing credential, a scope that has grown past what you were asked.
That last one is the safety line. An agent with a clear "stop here" instruction fails loudly. An agent without one keeps going, and keeps billing, and occasionally keeps deleting. If you've read our piece on why agents drift from their rules, the pattern is the same: the rule that matters most is the one that says when to stop.
A minimal tester role file, for reference:
You are the tester for this repository.
Done means: the test suite for the files listed in your task ran, and you returned results.
Return format: a heading "RESULTS", then one line per failing test: file, test name, first line of the error.
Never edit source or test files. Never run the full suite unless the task says "full".
Stop and report if: more than 10 tests fail, a test takes over 5 minutes, or a required service is unreachable.
Eight lines. No architecture overview, no "the codebase is organised as follows." The ETH paper found that codebase-overview prose had essentially no effect on how fast agents found files, because agents read the codebase anyway. What moved behaviour was specific, non-obvious instruction. Write that and nothing else.
Conflict rules you have to write down yourself
The spec's precedence is directory-based and tool-dependent. Your system has role-based conflicts the spec can't see. So say them out loud, in the root file, in one short block:
- A direct instruction in the current task beats every file. (This is also what Codex's own guidance says, and most tools follow it.)
- A role file beats a scope file on behaviour. The tester's "never edit" wins over a scope file's "always fix lint on save."
- A scope file beats the root on conventions. The api package's migration rule wins over the root's generic database line.
- The root wins on safety and secrets, always, and no lower file may loosen it.
Four lines. Every agent reads them, and when two files disagree, the agent has a tiebreaker instead of a coin flip. If you use Codex, keep temporary experiments in AGENTS.override.md rather than editing the root, so the override is obviously temporary and easy to delete.
One more thing to make explicit: personal instruction files. Codex reads ~/.codex/AGENTS.md, Factory reads ~/.factory/AGENTS.md, Claude Code has CLAUDE.local.md. In a multi-agent setup with several humans, a personal file that says "always use tabs" will fight the repo file that says spaces, on every agent, silently. Personal files should hold preferences, never requirements. Repo files and task instructions should always be able to override them.
What to delete before you add anything
If your root AGENTS.md is over a hundred lines, you almost certainly have one of these three things in it, and each one gets worse with every agent you add.
Redundant documentation. The ETH team ran a clever control: strip all READMEs and docs from the repos, then test the LLM-generated context files again. The same files that hurt performance in documented repos improved it by 2.7 percent in bare ones. The content wasn't useless. It was duplicated. If your AGENTS.md restates the README, delete the restatement and link the README.
Explanations of why. Agents don't need the history of a decision to follow it. "Use uv" works. "We migrated to uv in March because pip was slow in CI" is thirty tokens of context per agent per run that changes nothing.
Anything about a single agent's job. If a line only matters to the reviewer, it's a role-file line living in the root, and every other agent is now paying to read and, per the obedience finding, probably trying to follow it.
We built BetterClaw's per-agent instruction model after watching exactly this happen on our own agents, where one shared file kept teaching the briefing agent things only the scraper needed to know. Each agent gets its own instructions, its own trust level, and its own cost cap, so a bloated rule can't quietly multiply across the fleet. Free plan, bring your own keys.
A layout you can copy
Here is the shape that has worked, tool-agnostic:
repo/
AGENTS.md # root: invariants + the four conflict rules, under 60 lines
CLAUDE.md # one line: @AGENTS.md (only if Claude Code is in the mix)
packages/
api/AGENTS.md # scope: migrations, db, api conventions
web/AGENTS.md # scope: components, build, a11y rules
.claude/agents/ # role files (Claude Code), one per agent, body = system prompt
planner.md
coder.md
tester.md
reviewer.md
On OpenClaw the role layer moves into each agent's workspace as its own AGENTS.md plus SOUL.md, and the SOUL.md and AGENTS.md configuration guide covers what goes in which. If you're running three or more agents on OpenClaw specifically, the multi-agent setup guide handles the memory isolation and session binding that this post deliberately leaves alone. For the single-agent version of this file, start with AGENTS.md best practices.
Whatever the tooling, the test is the same. Pick any line in any file and ask: which agents will read this, and should all of them obey it? If the answer is "not all of them," it's in the wrong layer.
Where this lands
Two years ago the question was whether an agent would read the file at all. Now the file gets read, obeyed, and billed by every agent you point at it, and the research says the honest default is to write less than feels comfortable.
The multi-agent version of that lesson is sharper. A single agent with a bloated AGENTS.md wastes tokens. A fleet with a bloated shared AGENTS.md wastes tokens in unison, and occasionally does something four times that should have happened once. The layout above isn't clever. It's just the discipline of asking, for every rule, who it's actually for.
If any of this resonated, give BetterClaw a try. The free plan gives you one agent and 100 credits a month, bring your own API keys, no inference markup, and it never asks for a card. Pro is $49 a month for five agents, or $39 a month billed annually. Per-agent instructions and trust levels are on by default, so the three-layer model is how the product already thinks. Start free or see full pricing.
Frequently Asked Questions
What is AGENTS.md in a multi-agent system? AGENTS.md is a plain Markdown instruction file that AI coding agents read before working, now used in 60,000-plus repositories and stewarded by the Linux Foundation's Agentic AI Foundation. In a multi-agent system it works best as one of three layers: a short root file with rules true for every agent, nested scope files for directory-specific conventions, and separate per-agent role files that hold each agent's job, boundaries, and handoff format.
How does AGENTS.md compare to CLAUDE.md and per-agent role files?
AGENTS.md is cross-tool and directory-scoped, with the nearest file winning on conflict. CLAUDE.md is Claude Code's own file, supports @imports, and is commonly pointed at AGENTS.md with a single import line. Role files (for example, the markdown files in Claude Code's .claude/agents/ folder, or a per-agent SOUL.md on OpenClaw) describe one agent's behaviour rather than one directory's conventions, which is the gap the AGENTS.md spec doesn't cover.
How do I stop multiple agents from running the same instruction redundantly? Move any instruction that only one agent should act on out of the root AGENTS.md and into that agent's role file, then give each role file an explicit "never do X" line for the behaviours it should skip. For example, the tester runs the suite and the coder runs only the tests for touched files. Add a four-line precedence block to the root so agents have a tiebreaker when files conflict.
Is a detailed AGENTS.md worth the cost for a team of agents? Only if it's short and specific. An ETH Zurich study from February 2026 found every context file raised inference cost by over 20 percent per run, LLM-generated files slightly lowered success rates, and hand-written files gained roughly 4 percent, not statistically significant. In a multi-agent system that overhead is paid per agent, so a lean root plus targeted role files beats one comprehensive file on both cost and reliability.
Is it safe to let subagents read the same AGENTS.md as the main agent? Yes, as long as the shared file contains no state and no role-specific behaviour, and the root's safety rules are marked as non-overridable. Subagents in Claude Code receive the CLAUDE.md hierarchy but not the parent's conversation, so anything decided mid-session must travel in the delegation message. Put "stop and escalate" conditions in every role file and use per-agent trust levels or approval gates for anything that writes to production.
