AGENTS.md is a markdown file at the root of your repository that AI coding agents read before they start working. The specification calls it a README for agents: a predictable place to put the context an agent needs, in the same way README.md is a predictable place to put the context a human needs.
There is no schema. No required fields, no reserved headings, no frontmatter. It is plain markdown, and the agent simply parses the text you provide. The value is not in the format. It is in the agreement: because dozens of tools look for the same filename in the same place, one file configures Codex CLI, Claude Code, Cursor, Copilot, Antigravity CLI, Aider, Devin, Zed, and roughly two dozen others at once.
60,000+
Key takeaways:
- One file, every agent. That is the entire proposition, and it is why the format won over per-vendor instruction files.
- No required structure. Write the headings that fit your project.
- Agents read the nearest file, so monorepos layer one per package and the closest wins.
- An explicit chat instruction overrides the file. It is durable policy, not a hard guardrail.
- The commands section and the definition of done are the two highest-value sections, and both are usually missing.
- Length is a real cost. Context-file content loads on every turn, unlike a skill body.
- Governance is neutral now: the Agentic AI Foundation stewards AGENTS.md alongside MCP and goose.
Why This Format and Not Another
Before AGENTS.md consolidated, every agent had its own file: .cursorrules, CLAUDE.md, .clinerules, .github/copilot-instructions.md, and so on. A team using three tools maintained three files describing the same project, which drifted, and the drift showed up as agents behaving inconsistently for reasons nobody could reproduce.
In December 2025 the Linux Foundation formed the Agentic AI Foundation, with AGENTS.md contributed by OpenAI alongside Anthropic's Model Context Protocol and Block's goose as anchor projects. Platinum membership spans AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft, and OpenAI. The Agent2Agent protocol joined the same foundation in August 2026.
The practical read: this is now infrastructure with neutral governance rather than one vendor's convention that competitors tolerate.
What Actually Goes In It
The specification recommends sections rather than requiring them: project overview, build and test commands, code style guidelines, testing instructions, security considerations, commit and pull request guidelines, and deployment steps. Here is a version that reflects what actually changes agent behavior.
# AGENTS.md
## Project
Next.js 16 App Router app with Supabase auth and Postgres. TypeScript strict.
The `app/` directory is routes only; business logic lives in `lib/`.
## Commands
- Install: `npm install`
- Dev: `npm run dev`
- Typecheck: `npm run typecheck`
- Lint: `npm run lint`
- Test: `npm test` (single file: `npm test -- path/to/file.test.ts`)
- Build: `npm run build`
## Definition of done
A task is finished when `npm run typecheck && npm run lint && npm test` all pass.
Run them. Do not report completion without running them.
## Do not edit
- `public/llms-full.txt` — generated by the build
- `supabase/schema.sql` — mirrored from `supabase/migrations/`, never hand-edited
- `.next/`, `node_modules/`
## Conventions
- No `any`. If a type is hard, ask rather than widening it.
- `interface` for object shapes, `type` for unions.
- Tests sit beside their subject as `*.test.ts`.
- Server components by default; add `'use client'` only when a hook requires it.
## Gotchas
- `getTemplateCounts()` returns empty on the client. Use the async server variant.
- Rate limiting fails closed in production without Redis env vars. Do not "fix"
this by falling back to the in-memory store.
## Pull requests
- Conventional Commits. Never add AI tools as co-authors.
- Update `lib/changelog.ts` for any user-facing change.The Two Sections That Matter Most
Commands. This is what agents reach for constantly, and it is what generated drafts get wrong most often, because an init command infers commands from package.json without knowing which ones your team actually runs. Fix them by hand.
Definition of done. An agent told which command proves the work will run it. An agent not told will hand you a confident summary of unverified work. This single section eliminates the most common complaint about coding agents, and almost nobody writes it.
The gotchas section is the sleeper. It is where you record the things that have already burned someone: the function that behaves differently on the client, the config that fails closed by design, the file that looks hand-editable and is not. Every entry there is an incident you do not repeat.
Nesting and Precedence
Two rules, both simple:
- The closest
AGENTS.mdto the file being edited wins. - An explicit instruction in chat overrides everything in the file.
For a monorepo, that means:
AGENTS.md ← org-wide rules, shared commands
apps/web/AGENTS.md ← Next.js conventions, its test runner
apps/api/AGENTS.md ← Go conventions, its migration process
packages/ui/AGENTS.md ← component rules, StorybookThe reference example is OpenAI's own repository, which carries dozens of these files across subprojects. The pattern that works is a short root file with what is genuinely universal, and package files that add the specifics. The pattern that fails is one enormous root file attempting to describe every package, because every task then pays for instructions about packages it is not touching.
Some tools additionally support an override variant that replaces rather than extends the normal file at that level. Use it only when a subproject genuinely contradicts the root rules rather than extending them.
Warning
The second precedence rule has a security implication: AGENTS.md cannot stop you, or anyone who can put text in front of the agent, from overriding it. If a rule must hold absolutely, enforce it with a sandbox, a hook, or CI. A markdown file is policy, not a control.
AGENTS.md vs. CLAUDE.md vs. Skills
Three mechanisms, one decision each.
| Holds | Loads | Use for | |
|---|---|---|---|
AGENTS.md | Facts and rules | Every turn, all tools | Commands, conventions, out-of-bounds paths, gotchas |
CLAUDE.md | Same, tool-specific | Every turn, Claude Code | Only behavior unique to that tool |
| Skill | Procedures | Only when matched | Runbooks, checklists, reference material |
If more than one agent touches your repository, put the real content in AGENTS.md. Keep any tool-specific file short and clearly scoped, or have it point at the shared file. The failure mode is split-brain instructions — two files, overlapping rules, slight divergence, and an agent that follows whichever it happened to read.
The skills distinction is about loading cost. Anything in a context file is in the window on every turn. Anything in a skill body loads only when the description matches. So: facts in AGENTS.md, procedures in skills. When a section of your context file grows from a statement into a numbered procedure, that is the moment to move it.
How to Write One That Works
Run your agent's init command to get a draft, then correct the commands section by hand, because that is the part inference gets wrong.
Add the definition of done. Name the exact commands that must pass.
List the do-not-edit paths: generated output, vendored code, mirrored files.
Write only conventions your reviews actually enforce. Skip general best practices; the model already knows them and they dilute the specific rules.
Start a gotchas section, even if it is empty. Fill it the first time an agent gets something wrong for a non-obvious reason.
Give an agent a small real task and watch it. Every correction you have to type is a missing line in the file.
Re-read it quarterly. Stale commands are worse than no commands, because the agent will confidently run the wrong thing.
The Anti-Patterns
Writing a tutorial. "Use meaningful variable names" is noise. "Repository methods return Result<T, AppError>, never throw" is a rule.
Documenting the obvious. The agent can read package.json. It cannot know that the script named test only runs unit tests and the integration suite needs a separate command with a running database.
Letting it sprawl. Past a couple hundred lines, split it: nested files for packages, skills for procedures, links for reference.
Putting secrets in it. It is committed, and it is read by a model that may be summarizing into logs.
Never testing it. A file nobody has watched an agent follow is a file full of assumptions.
The Honest Limits
AGENTS.md improves consistency. It does not make an agent correct. It cannot enforce anything, because your next chat message outranks it. It does not travel with a task into a subagent unless the tool arranges that. And because it loads on every turn, every line you add makes every unrelated task slightly more expensive.
Within those limits it is the highest-leverage file in an agent-assisted repository. The reason is not sophistication. It is that most agent failures come from missing project context — the command nobody said to run, the directory nobody said not to touch — and a text file is a complete fix for that class of problem.
Where to Go Next
- The category pillar: prompting AI coding agents
- Procedures rather than facts: Agent Skills guide
- The agents that read it: Codex CLI and Antigravity CLI
- The discipline this file supports: spec-driven AI coding
- Turn a repeated instruction into a reusable prompt with the SurePrompts builder