One brief, several readers.
AGENTS.md exists so the same guidance does not have to be maintained in four files.
The value is a single source of truth, not a new format to learn
Coding agents each arrived with their own instruction file, so a team using more than one ends up maintaining the same guidance in several places — and they drift, because nobody updates all of them. AGENTS.md is the tool-neutral convention that lets you write it once. The content problem is identical to any project brief: it is read on every task, so omission is the skill and discoverable facts are noise. The specific thing worth getting right here is scope — because it is read by tools with different capabilities, it should describe the project rather than any one agent's workflow. Instructions about a particular tool's features belong in that tool's own file, with AGENTS.md holding what is true regardless of who is reading.
- Purpose
- Tool-neutral project brief. One file instead of one per agent.
- Location
- Repository root. Nested files, where supported, scope to their subtree.
- Write here
- Anything true regardless of which agent reads it — commands, constraints, conventions.
- Write elsewhere
- Tool-specific workflow and features. Those belong in that tool's own file.
- Precedence
- A tool's native file generally wins where both exist. Do not duplicate — split.
- Same rule as CLAUDE.md
- Read every task. Discoverable facts are noise; non-obvious constraints are the point.
FAQ
Only if you have genuinely tool-specific guidance. The useful split is: everything true about the project goes in AGENTS.md, and anything about one tool's particular features goes in that tool's file. Duplicating content across both is the outcome the convention exists to prevent.
A tool's native file generally wins for that tool, which is why the split matters more than the ordering. If the same rule is stated in both and they drift apart, you get behaviour that depends on which agent someone happened to run — the exact failure the single-source approach is meant to remove.
Where nested files are supported, a subdirectory file scopes to that subtree, which is genuinely useful in a monorepo where the frontend and the worker have different constraints. Keep the root file to what applies everywhere.
Secrets, obviously — it is committed. Beyond that: anything the agent can find by reading the code, general language or framework explanation, and rules nobody actually enforces. Each of those costs attention on every task and returns nothing.