AGENTS.md Explained
A single Markdown file at the root of a repository that tells coding agents how to build it, test it, and behave inside it. It has no version number and no formal specification, and that turns out to be the interesting part.
A Convention, Not a Format
What the file is, who maintains it, and how widely it is used
AGENTS.md is a convention for putting agent-facing instructions in a predictable place. The idea is narrow on purpose: a README is written for humans and is full of badges, marketing, and contribution etiquette, while an agent mostly needs to know which package manager to use, how to run the tests, and which parts of the tree it must not touch. AGENTS.md is where that goes.
The project reports adoption by more than 60,000 open-source repositories, based on a GitHub code search. It is stewarded by the Agentic AI Foundation under the Linux Foundation, the same home as the Model Context Protocol, and it emerged from collaboration between several agent vendors rather than being published by one of them. The site lists more than twenty compatible tools, among them OpenAI Codex, Google Jules, GitHub Copilot, VS Code, Cursor, Zed, JetBrains Junie, Aider, Factory, goose, Devin, Gemini CLI, RooCode, and Warp.
One predictable location
The file lives at the repository root. Monorepos commonly add nested files in each package, with agents preferring the closest one to the code being edited. Check your agent's documentation, because nested-file handling is a per-tool behavior and not something the convention guarantees.
Plain Markdown
No front matter, no schema, no reserved keys. The project's own FAQ is explicit: "AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide."
No required fields
There is nothing to validate against, so there is no such thing as an invalid AGENTS.md. A file with one useful sentence is conformant. So is a file with two thousand lines of contradictory advice.
What Belongs In One
Facts an agent cannot infer, written concretely enough to check
The useful filter is simple: include what an agent would get wrong by guessing, and leave out what it can read from the code. A dependency list is already in the manifest. A directory tree is already on disk. What is not discoverable is that this repository uses one package manager and not the obvious one, that the fast test command skips the suite that actually gates merges, or that a generated directory must never be hand-edited. Write instructions specifically enough that you could verify compliance, in the same way you would write a good onboarding note for a new engineer.
# AGENTS.md
## Project
Payments API. Go 1.24 service behind an internal gateway. Handles card
authorization only; settlement lives in a separate repository.
## Setup
Use `make bootstrap`, not `go mod download` directly - it also generates
the protobuf stubs the build needs.
## Build and test
- `make test` runs unit tests. Fast, but it does NOT gate merges.
- `make test-integration` is what CI gates on. It needs Postgres, which
`make bootstrap` starts in a container.
- Run `make lint` before proposing changes. CI rejects lint failures.
## Conventions
- Errors are wrapped with `fmt.Errorf("...: %w", err)`. Never return a
bare error from an exported function.
- All new endpoints need a table-driven test in the same package.
- Use the `internal/clock` package instead of `time.Now()` so tests can
control time.
## Do not touch
- `internal/gen/**` is generated. Change the `.proto` files and rerun
`make bootstrap`.
- `deploy/prod/**` requires a platform team review. Do not edit it.
## Pull requests
Title format: `[payments] short imperative summary`. Keep changes under
roughly 400 changed lines; split larger work into several PRs.Worth including
- The exact setup, build, test, and lint commands
- Which test command actually gates a merge
- Generated or vendored paths that must not be hand-edited
- Conventions that differ from the language's defaults
- Pull request expectations: title format, size, required checks
- Boundaries that need a human, such as schema or deploy changes
Leave it out
- Secrets, tokens, or internal hostnames - this file is committed
- Dependency lists that duplicate the package manifest
- Directory trees the agent can read from disk
- Marketing copy and project history
- Vague exhortations such as "write clean code"
- Anything you would not be willing to keep up to date
Why It Deliberately Has No Specification
The design choice, and the price you pay for it
It is worth being precise about this, because AGENTS.md is often described as a standard in the same breath as MCP or ACP, and it is a different kind of thing. Those are versioned protocols with schemas, negotiation, and conformance. AGENTS.md has no version number, no specification document, and no required fields. The consumer is a language model reading prose, so a schema would add ceremony without adding much the reader can use.
That choice is defensible, and it explains the adoption curve: there is nothing to implement, so a repository adopts the convention simply by adding the file. But an unspecified format shifts every hard question onto individual tools, and the consequences are real rather than theoretical.
What you gain
Zero implementation cost on both sides. A repository adds one file; a tool adds one file read. No versioning treadmill, no deprecation policy to run, and no schema migrations when practice changes. Instructions stay readable to humans, which is what keeps them from rotting quietly.
What you give up
No validation, so mistakes surface as odd agent behavior rather than an error. No guarantee that two tools interpret the same file the same way, or read nested files with the same precedence. No conformance claim to hold a vendor to. And critically, no enforcement: the file is advisory context, not a control.
AGENTS.md is not a security boundary
A line reading "never modify production configuration" is a request, not a permission. It competes for attention with everything else in the context window, and a model may not follow it. Anything that must not happen belongs in a mechanism that does not depend on the model's cooperation: branch protection, required reviews, scoped credentials, egress restrictions, or a tool-level hook that blocks the action outright. Treat the file as documentation that improves the odds, and put the guarantees in the environment.
Tool-Specific Files and the Duplication Problem
AGENTS.md did not eliminate the per-tool instruction file
Several tools maintain their own instruction file alongside the shared convention. Claude Code uses CLAUDE.md, GitHub Copilot uses .github/copilot-instructions.md, Cursor uses .cursor/rules/, and others have their own. This is exactly the fragmentation AGENTS.md set out to reduce, and it has not gone away.
Claude Code is the clearest illustration, and it is worth quoting the primary source rather than repeating the common assumption that a listing on agents.md implies native parsing. Anthropic's documentation states plainly: "Claude Code reads CLAUDE.md, not AGENTS.md." The documented workaround is to create a CLAUDE.md that imports the shared file, so both tools read the same instructions without duplicating them, with tool-specific additions below the import.
<!-- CLAUDE.md: import the shared file, then add tool-specific notes -->
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.The general pattern generalizes even where the syntax does not. Keep one canonical file, and make every tool-specific file a thin pointer to it - an import where the tool supports one, a symlink where it does not, or a generated file written by a pre-commit hook as a last resort. What you want to avoid is several files that started identical and have since drifted, because an agent reading a stale copy will confidently follow instructions that no longer describe the repository.
Verify support rather than assuming it
A tool appearing on a compatibility list is not proof that its current release parses the file the way you expect. Behavior changes between versions, and nested-file precedence in a monorepo is a particularly common divergence. The cheap check is empirical: put a distinctive, harmless instruction in the file, such as a specific commit message prefix, and see whether the agent follows it. That takes a few minutes and tells you more than any list.
Common Failure Modes
Recurring problems in real files, and what to do instead
Length that crowds out the code
The file is loaded into the context window before the agent has read a single source file. A sprawling document consumes budget that would otherwise hold the code being changed, and dilutes the instructions that actually matter. If it has grown past a page or two, the fix is usually deletion rather than reorganization. Ask of every line whether an agent would get this wrong without it.
Instructions that contradict each other
Files accumulate. One section says to use a package manager the setup section abandoned two years ago; another forbids something an example later demonstrates. Because there is no validator, nothing flags the conflict, and the agent simply picks one. Contradictions are worse than omissions, because an omission at least leaves the agent uncertain enough to ask.
Advice too vague to check
"Follow best practices" and "keep it maintainable" cost tokens and change nothing. The test is whether you could look at a diff and say definitively that the instruction was violated. "Run make lint before proposing changes" passes that test; "write quality code" does not.
Documented commands that no longer work
An agent trusts the file. If the build command has changed, the agent will run the old one, watch it fail, and start improvising a fix for a problem that does not exist. This is the failure mode most worth engineering against: have CI run the commands the file documents, so a stale instruction breaks the build rather than quietly wasting agent turns.
Content that should not be in a committed file
AGENTS.md is committed, public in an open repository, and now routinely read by third-party tools. Internal hostnames, ticket links, staging credentials, and unreleased project names do not belong in it. Review it the way you would review any other file that leaves your network, and keep secrets in a secret store.
AGENTS.md and Centralized Environments
Where it fits alongside devcontainers and platform policy
There is a natural overlap with devcontainers, and the two solve genuinely different halves of the same problem. A devcontainer definition makes the environment reproducible: the toolchain is installed, the services are running, and the commands will work. AGENTS.md explains which of those commands to run and why. When both exist, the instruction file gets shorter, because it no longer needs to describe installing anything - the environment guarantees it, and the file can spend its budget on intent and boundaries instead.
For platform teams, the more useful framing is a layered one. AGENTS.md is per-repository advisory context maintained by the team that owns the code. Organization-wide requirements do not belong in it, partly because they would be duplicated across every repository, and mostly because advisory text is the wrong mechanism for a requirement. Those belong in the layers that hold regardless of what the model decides.
Repository layer
AGENTS.md. Owned by the code owners, reviewed like code, and kept short. Best for build commands, local conventions, and where the sharp edges are.
Environment layer
The workspace image and its network policy. Determines what tools exist and what the agent can reach at all. Enforced by construction, not by persuasion.
Platform layer
Branch protection, required reviews, scoped credentials, and audit logging. This is where non-negotiable rules live, because they hold even when an agent ignores every instruction it was given.
Related Reading
Standards, environments, and governance around coding agents
Agent Client Protocol
The editor-to-agent standard that makes agents portable.
MCP Servers
How agents reach tools and data, and how to run that centrally.
DevContainers
Reproducible environments that shorten your instruction file.
AI Coding Assistants
The tool landscape and what the published evidence supports.
Agentic Engineering
Working practices for teams whose agents write real code.
AI Governance
Policy layers that hold when instructions are ignored.
Autonomous Development
What changes when agents run unattended against a repository.
Platform Engineering
Paved paths that make the right thing the easy thing.
Sources
Every citation used across this site, with publishers and dates.