What Is AGENTS.md?
AGENTS.md is a persistent instruction file at a repository's root that tells AI agents how to work in that project: setup and test commands, conventions, a directory map, and constraints. It is effectively a README written for agents instead of humans, and multiple agent runtimes read it.
Key takeaways
- AGENTS.md is identity-layer infrastructure: context the agent would otherwise re-derive or wrongly guess every session.
- The highest-value section is exact commands, verified by running them. A wrong test command breaks every agent session.
- A do-not-touch list is the cheapest governance you can buy.
- It is the closest thing to a cross-vendor standard among instruction files: Codex, Claude-family tools, and others read it.
- AGENTS.md answers who-and-where; skills answer how. Keep procedures out of it.
A README for agents
Human READMEs explain a project to a person deciding whether to use it. AGENTS.md explains a project to an agent that is about to change it. The audiences want different things: the agent needs exact commands, hard constraints, and a map, and it needs them in imperatives, not prose.
AGENTS.md sits in the identity layer of the execution stack: persistent context loaded every session, so the agent never re-derives (or wrongly guesses) the basics.
What belongs in it
| Section | What goes there | Why it earns its lines |
|---|---|---|
| Project overview | Two sentences: what this is, what must not break | Orients every downstream decision |
| Commands | Exact install, build, test, lint, run commands | The highest-value section; a wrong test command breaks every session |
| Conventions | Rules a linter does not already enforce | Linters handle the rest; don't duplicate them |
| Directory map | Where things live, where new things go | Prevents structure drift |
| Do-not-touch list | Generated files, vendored code, other teams' territory | The cheapest governance you can buy |
| Environment facts | Ports, env vars, service dependencies | Guesses here are where sessions go sideways |
| PR rules | Branching, review, CI gates | Makes the agent's output land-able |
Two disciplines matter more than any section. Verify every command by running it before committing the file; agents trust these commands completely, so an untested command is a planted bug. Keep procedures out: a multi-step workflow with verification belongs in a skill, not in the identity file. AGENTS.md answers who-and-where; skills answer how.
Relationship to CLAUDE.md and Cursor rules
AGENTS.md is runtime-agnostic: Codex reads it, Claude-family tooling reads it, and most newer runtimes at least respect it. CLAUDE.md is Claude Code's own file, functionally the same layer. If both exist, keep one canonical: the common pattern is AGENTS.md as the source of truth with CLAUDE.md carrying only Claude-specific additions or a pointer. Divergent twins are worse than either alone, because nobody knows which one lied.
Cursor rules cover the same identity ground for Cursor, with one addition: glob-scoped rules that attach only when matching files are touched, which pushes them partway into skill territory.
The craft standard
The quality bar for an AGENTS.md is the cold-start test: could an agent with zero project history land a small change using only this file and the codebase? If it would guess a port, miss a convention, or touch a generated file, the file has a gap. Write the gap down, verify it, and the next hundred sessions inherit the fix.
Start from the AGENTS.md template, which encodes all of the above with annotated fields.
Frequently asked questions
What is AGENTS.md?
A repository-root instruction file for AI agents: setup commands, conventions, directory map, and constraints. A README for agents rather than humans.
What should be in AGENTS.md?
Project overview, exact build/test/lint commands, conventions a linter doesn't enforce, a directory map, a do-not-touch list, environment facts, and PR rules.
AGENTS.md or CLAUDE.md?
AGENTS.md is runtime-agnostic; CLAUDE.md is Claude Code's file. Many repos keep AGENTS.md canonical and have CLAUDE.md point at it or carry Claude-specific additions.
Summary
- Topic
- AGENTS.md: the cross-runtime agent instruction file
- Definition
- A repo-root file giving agents persistent project context: commands, conventions, map, constraints
- Best used for
- Stopping agents from re-learning or wrongly guessing project basics every session
- Related concepts
- instruction file, CLAUDE.md, identity layer
- Common mistakes
- Unverified commands, prose instead of imperatives, stuffing procedures that belong in skills
- Recommendation
- Write it from the Agentiquette template; verify every command by running it before committing