If you have ever watched a coding agent re-invent your project's test command for the fourth time, run the wrong linter, or "helpfully" refactor a generated file you told it never to touch, you already understand the problem AGENTS.md solves. It is the config file the industry finally agreed on — a single Markdown file in your repo root that tells any AI coding agent how your project actually works.
This guide is the practical version: what to put in the file, the patterns that genuinely change agent behavior, and the mistakes that quietly make the file useless.
What AGENTS.md actually is
AGENTS.md is a plain-Markdown file placed at the root of a repository. Where a README.md explains a project to humans, AGENTS.md explains it to agents — build commands, test commands, code-style rules, project structure, and the boundaries an agent must not cross.
It is intentionally boring by design:
- Plain Markdown. No required schema.
- No mandatory YAML frontmatter (the 1.0 spec defines none).
- No custom syntax, no build step, no vendor SDK.
That simplicity is the whole point. The format only works as a cross-vendor standard if no single vendor is incentivized to fork it. The spec is stewarded by the Agentic AI Foundation under the Linux Foundation — the same umbrella that governs Linux, Kubernetes, and Node.js — and originated from collaboration between OpenAI, Amp (Sourcegraph), Google (Jules), Cursor, and Factory. As of May 2026 it has been adopted by more than 60,000 repositories.
Which tools actually read it
Native support means the agent reads AGENTS.md from the repo root automatically, no wrapper script required. The current list is long: OpenAI Codex, Cursor, GitHub Copilot's coding agent, Google Gemini CLI, Jules, Windsurf, Aider, Zed, Warp, Factory, Devin, Amp, Kilo Code, RooCode, Augment, JetBrains Junie, goose, opencode, and more than 20 others.
The one notable holdout is Anthropic's Claude Code, which reads CLAUDE.md by convention rather than AGENTS.md. The standard workaround is a one-line CLAUDE.md that imports the shared file:
@AGENTS.md
## Claude-Code-specific notes
- Use the `db-readonly` subagent for schema questions.
The takeaway: if you commit one file, commit AGENTS.md. It is read by the broadest set of tools. If your team standardizes on Claude Code, add the thin CLAUDE.md importer on top.
The eight sections worth writing
There is no required heading set — the spec's only normative guidance is "use whatever headings make sense." But GitHub's analysis of more than 2,500 real repositories surfaced a consistent, high-value structure. Write these eight and you have covered the cases that actually cause agent failures:
- Project overview — one paragraph on what the code does and its architectural shape.
- Setup and build commands — every command from
git cloneto a running build, with flags. - Test commands — how to run the full suite, a single test, and a single suite.
- Code style — formatter, linter, naming conventions. Cite the config file if one exists.
- Project structure — the top two or three directory levels, one line each.
- Git / PR conventions — branch naming, commit format, PR template.
- Security and secrets — what must never be committed; where env vars live.
- Boundaries — three tiers: always do, ask first, never do.
A canonical minimal example, straight from the spec, looks like this:
# MyApp
## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package.
- Run `pnpm install --filter <package_name>` to add a package.
## Testing instructions
- Find the CI plan in `.github/workflows`.
- Run `pnpm turbo run test --filter <project_name>` from the package root.
- Always add or update tests for code you change.
## PR instructions
- Title format: `[<project_name>] <Title>`
- Always run `pnpm lint` and `pnpm test` before committing.
The patterns that actually change agent behavior
Here is the uncomfortable truth: LLMs are not great at following instructions. They are, however, much better at following certain phrasings. These patterns consistently move adherence in the right direction.
Use imperative voice, not descriptive. "Run pnpm test before every commit" beats "this project uses pnpm test for testing." The agent is looking for instructions, not trivia.
Give concrete commands with flags. pytest -x --tb=short tests/unit beats "run the unit tests." Specificity removes the guesswork that produces wrong runs.
Pin your stack with versions. "Node 22.x, pnpm 9, Vite 5" beats "modern JS stack." Version numbers stop the agent from assuming defaults that don't match your repo.
Write scope sentences per directory. A single line like "Backend code only in packages/api/src/" eliminates an entire class of cross-package edits that should never happen.
Guard generated files explicitly. List every regenerated directory — gen/, __generated__/, migrations/, dist/ — and tell the agent never to edit them by hand.
Use three-tier boundaries. Group rules into always do, ask first, and never do. The explicit hierarchy turns an open-ended judgment call into a clean classification problem. This is the section that prevents agent runaway more than any other.
A boundaries block in practice:
## Boundaries
- Never edit `prisma/migrations/`; generate via `pnpm db:migrate`.
- Never commit `.env*` files.
- Ask before adding a new top-level dependency.
- Always run `pnpm lint && pnpm test` before opening a PR.
Monorepos: nest your files
The single biggest scale lever in the spec is nested AGENTS.md. You put one at the repo root and one inside each package. Agents walk up the directory tree from the file they are editing and combine every AGENTS.md they pass, with the closest file winning on conflicts.
This is not a niche pattern. OpenAI's own Codex monorepo ships 88 nested AGENTS.md files — roughly one per service. The structure looks like this:
repo/
├── AGENTS.md # global: stack, root commands, branch naming
├── packages/
│ ├── api/AGENTS.md # Express, Postgres conventions, test command
│ ├── web/AGENTS.md # React, Tailwind, Vite conventions
│ └── shared/AGENTS.md # zod schemas, no DB imports allowed
└── tools/
└── etl/AGENTS.md # Python, pandas, different lint rules
Two rules keep this clean. Put defaults at the root, overrides at the leaf — stack and security boundaries go in the root file; per-package test commands and conventions go in the nested ones. And don't re-state inheritance — if the root says "pnpm 9," the leaf shouldn't repeat it. Keep nested files short, 30 to 80 lines each; the root can run to about 200.
AGENTS.md vs CLAUDE.md vs .cursorrules vs SKILL.md
Most repos end up with two or three instruction files. The right decomposition:
| File | Read by | Use for |
|---|---|---|
AGENTS.md |
20+ agents | Build/test/style/structure/boundaries that apply to every agent |
CLAUDE.md |
Claude Code only | Claude-specific workflow; import AGENTS.md at the top |
.cursorrules |
Cursor only (deprecated) | Nothing new — migrate to AGENTS.md + .cursor/rules/*.mdc |
SKILL.md |
Claude products | A reusable, packaged capability with bundled scripts and references |
The rule of thumb: if you would tell every new engineer this, it belongs in AGENTS.md. If you would tell only the engineer using Claude Code, it belongs in CLAUDE.md. If it is a packaged, reusable capability with code, it belongs in a SKILL.md. If it changes every task, it stays in the prompt.
A common confusion is whether AGENTS.md replaces MCP server config. It does not — they sit at different layers. AGENTS.md carries instructions ("run the test command before committing"); MCP servers expose tools (a .mcp.json endpoint the agent calls to query your database). A well-configured repo has both, and your AGENTS.md can reference MCP servers by name: "use the db-readonly MCP server for schema questions, never query prod directly."
Ten anti-patterns to avoid
The fastest way to a useless AGENTS.md is to fill it with noise. Don't write a persona ("you are a helpful AI assistant") — the agent already knows what it is. Don't paste your README; duplication doubles maintenance and signals nothing new. Don't include marketing copy or vague platitudes like "write clean, idiomatic code" — replace them with signal: "use Result<T, E> for fallible operations, never raise unchecked exceptions."
Two more matter most in practice. Don't ship a 2,000-line file — Codex caps input at 32 KiB and most agents start ignoring content after the first few thousand tokens, so keep the root under ~500 lines and push detail into nested files or docs/. And don't forget to update it — a stale AGENTS.md is worse than none, because the agent will confidently follow rules that no longer apply. Treat it like the README: update it in the same PR as the change it documents.
A rollout you can finish this week
You do not need a committee. On day one, write a 100-to-200-line root AGENTS.md covering the eight sections, then have one engineer per tool — Cursor, Claude Code, Codex, Copilot — run a real task against it and report where the agent drifted. Iterate from the failures. On day two, add the @AGENTS.md import to CLAUDE.md and migrate Cursor-specific path rules into .cursor/rules/*.mdc. Within the first week, add nested files for your top three packages and wire an "update AGENTS.md" line into your PR template so the file never goes stale.
The Bottom Line
AGENTS.md is the closest thing the industry has to a universal instruction format for AI coding agents, and the cost of adopting it is almost nothing — one Markdown file, no tooling, read by more than 20 tools out of the box. The teams getting real leverage from coding agents in 2026 are not the ones writing the most prompts. They are the ones who wrote the rules file once, scoped it well, and stopped re-explaining their repo on every task. Write the eight sections, set hard boundaries, keep it short, and update it in the same PR as the code. The agent will spend its context budget on your diff instead of guessing at your conventions.
