AGENTS.md is a plain Markdown file at the repository root holding build commands, conventions, and constraints for coding agents. It is an open format used by more than 60,000 open-source projects and read by Codex, Gemini CLI, Cursor, Copilot, Aider, Zed, Windsurf and others. Agents read the nearest file up the directory tree, so nested files let each package in a monorepo ship its own rules.
- Plain Markdown at the repository root. No schema, no frontmatter, no build step.
- An open format used by 60,000+ open-source projects and read by 20+ agents.
- Agents read the nearest file up the tree, so nested files own their subtree.
- Keep it under about 100 lines. It is loaded as context on every session.
- Run
/initonce to get a draft, then delete most of it. - Claude Code still reads
CLAUDE.md. Symlink it rather than maintaining two.
What it is, and why it caught on
A README tells a human what a project is. AGENTS.md tells an agent how to work in it: the commands that are not discoverable, the conventions that contradict the ecosystem default, and the things it must not do.
The format has no schema. It is Markdown, it lives at the repository root, and every supporting tool simply reads it into context before the first turn. That absence of specification is the reason adoption happened at all: there was nothing to implement and nothing to agree on. As of August 2026 the format lists more than 60,000 open-source projects using it.
Where the agent instruction files stand, August 2026.
| File | Read by | Scope |
|---|---|---|
AGENTS.md | Codex, Gemini CLI, Cursor, Copilot coding agent, Aider, goose, opencode, Zed, Warp, Devin, Junie, Amp, Windsurf, Jules, Factory and more | Cross-tool convention |
CLAUDE.md | Claude Code | Anthropic-specific |
.cursorrules | Cursor | Legacy, superseded by Cursor rules and AGENTS.md |
.github/copilot-instructions.md | GitHub Copilot | Copilot-specific |
ln -s AGENTS.md CLAUDE.md
git add AGENTS.md CLAUDE.md
git commit -m "one instruction file for every agent"Getting a first one without writing it
Let Codex draft it
/initCodex reads the project and writes an AGENTS.md scaffold in the current directory. It is generic and too long, which is fine: editing down is a far easier task than starting from a blank file.
Delete everything the agent already knows
Cut the description of what the language is, the explanation of what tests are for, and any paragraph that could apply to any repository. If a competent new hire would not need to be told it, neither does the model.
Add the three things it cannot infer
The exact command to run one test. The conventions that contradict the ecosystem default. The traps that have already cost somebody a day.
Commit it, and treat it as code
It is documentation that improves with review. One person working out that the integration tests need Postgres 16 exactly should not have to tell everyone individually.
A complete example
# AGENTS.md
Go service, Postgres, deployed to GKE. Go 1.23.
## Commands
- `make dev` - run locally on :8080
- `make test` - full suite, needs docker compose up -d
- `go test ./internal/auth/...` - ONE package. Prefer this.
- `make lint` - golangci-lint. Run before proposing a diff.
- `make gen` - regenerate protobufs after any .proto change
## Conventions
- Errors wrap with `fmt.Errorf("context: %w", err)`. Never bare returns.
- No `panic` outside `main` and package init.
- Table-driven tests. Match the style in `internal/auth/token_test.go`.
- All timestamps are UTC `time.Time`. Never local, never a string.
## Traps
- `internal/legacy/` is generated. Edit the `.proto`, then `make gen`.
- The integration tests need Postgres 16 exactly. 15 fails oddly.
- `make test` takes 6 minutes. Run the single package while iterating.
## Never
- Never commit to `main`.
- Never add a dependency without asking.
- Never edit anything under `gen/`.Monorepos and the nearest-file rule
Agents read the nearest AGENTS.md up the directory tree from where they are working, so the closest one takes precedence and every subproject can ship tailored instructions.
AGENTS.md <- org-wide conventions, true everywhere
services/api/AGENTS.md <- Go service specifics
services/web/AGENTS.md <- Next.js specifics
packages/ui/AGENTS.md <- component library rulesWhat belongs at each level.
| Level | Put here | Do not put here |
|---|---|---|
| Root | Branch policy, review rules, release process | Language-specific style |
| Service or package | Build and test commands, local conventions, traps | Anything repeated from the root |
Running AGENTS.md and CLAUDE.md together
Most people who use Codex also use Claude Code, and Claude Code reads CLAUDE.md rather than AGENTS.md. That leaves three options, and only one of them survives contact with a team.
| Approach | What happens |
|---|---|
| Two separate files | They diverge within a month. Two agents then work from different rules on the same repository, and nobody notices until one of them does something odd. |
| One file, one agent ignored | Whichever tool you use less gets no instructions at all, which is exactly when you most need them. |
| One file, the other symlinked | One place to edit, one diff to review, identical instructions for every agent. |
ln -s AGENTS.md CLAUDE.md
git add AGENTS.md CLAUDE.md
git commit -m "single agent instruction file"
# confirm git recorded a link, not a copy
git ls-files -s CLAUDE.md # mode 120000 means symlinkIf a tool genuinely needs different content, keep the difference small and put it in the tool-specific file, with the shared substance still in AGENTS.md. Two files that differ in one paragraph stay honest. Two files that differ in twenty are two sources of truth.
What makes one work
| Do | Do not |
|---|---|
| Give the exact command to run one test | Explain what testing is |
| Name conventions that contradict the default | Restate the language style guide |
| Record traps that have cost someone a day | Document your architecture at length |
| State what must never happen | Write aspirational principles |
| Point at one exemplary file to copy | Describe the style in prose |
| Keep it under a page | Let it grow to 500 lines |
Refresh it when the agent gets something wrong
The most reliable way to write a good one is reactively. Every time an agent does something you have to correct, ask whether one line would have prevented it. If it would, that line is the next commit. Two months of that produces a file no amount of upfront writing would have.
Questions people ask
A plain Markdown file at your repository root holding build commands, conventions, and constraints for coding agents. It is an open format with no schema, used by more than 60,000 open-source projects as of August 2026.
Codex is the most prominent, alongside Gemini CLI, Cursor, the GitHub Copilot coding agent, Aider, goose, opencode, Zed, Warp, Devin, Junie, Amp, Windsurf, Jules and others. Claude Code reads CLAUDE.md, which is why symlinking one to the other is common practice.
The repository root. Agents read the nearest file up the directory tree, so nested files in subdirectories own their subtree, which is how monorepos give each package its own rules.
Write AGENTS.md and symlink CLAUDE.md to it. Maintaining two files means they will diverge, and then two agents on the same repository are working from different instructions and you will not notice until one of them does something odd.
Under about 100 lines. It is loaded as context on every session, so length is a recurring cost on every turn and a long file dilutes the instructions that actually matter.
Run /init inside a Codex session. It reads the project and drafts a scaffold. Then delete everything the model could have inferred and keep the commands, the conventions that contradict the default, and the traps.
Yes. It is documentation that improves with review, and a convention one person works out should benefit the whole team and every agent they run.
Well, and it is the main reason the nearest-file rule exists. Keep genuinely universal rules at the root and put build commands, test commands, and traps in each package, so an agent in one service never loads another service conventions.
Sources
Every figure above was read from these pages on August 2026. Vendors reprice without notice; if you find a stale number, tell us.