Two years into the coding-agent era, a plain Markdown file has quietly become standard infrastructure. AGENTS.md is the place where a repository tells AI coding agents how to work in it: build commands, test commands, code style, architectural rules, the things a senior teammate would whisper to a new pair-programming partner on day one. It complements the README rather than replacing it — READMEs stay focused on human contributors, while AGENTS.md holds the precise, sometimes tedious context that helps an agent be productive without forcing you to re-explain your conventions in every chat session.
The format’s momentum is now hard to ignore. It works across a long and growing list of agents — Codex from OpenAI, Cursor, GitHub Copilot’s coding agent, Gemini CLI, Jules, Amp, goose, Aider, Zed, Windsurf, and many more — and it is stewarded by the Agentic AI Foundation under the Linux Foundation, which gives it the neutral governance a cross-vendor format needs. The ecosystem it standardizes was previously a pile of per-tool files (.cursorrules, CLAUDE.md, .aider.conf.yml conventions), and consolidation around one name means the instructions you write once actually travel with the repo.
What Goes In It
There is no schema. AGENTS.md is standard Markdown, parsed as plain text by the agent; use whatever headings make sense for your project. In practice, four sections carry most of the value:
- Commands — how to build, run, test, and lint. If you list programmatic checks, most agents will run them and attempt to fix failures before finishing the task, which turns “it looked fine” into “the suite passed.”
- Architecture — a short map of the codebase: where the entry points are, where mutations live, which directories are generated, what is off-limits.
- Code style — the conventions a linter cannot enforce: named exports only, server components by default, no new dependencies without discussion.
- Rules — the hard constraints. Never commit .env files. Typecheck before committing. All database access goes through the repository layer.
Here is a compact template that works for a typical web service:
# orders-api
Go 1.26 service using chi, sqlc, and PostgreSQL 19.
## Commands
- go build ./...
- go test ./... # full suite
- go test ./pkg/orders/ -run TestCalculateTotals # single test
- sqlc generate # regenerate DB code after schema edits
- golangci-lint run # lint
## Architecture
- /cmd/orders-api/ entry point and wiring
- /internal/orders/ domain logic (no imports from /internal/httpapi)
- /internal/httpapi/ handlers; thin, no business logic
- /db/queries/ sqlc definitions — the ONLY place raw SQL lives
## Rules
- All DB access through generated sqlc types in /db/.
- Run go test ./... before committing.
- Never edit generated files; change the query definitions instead.Precedence and Nesting
AGENTS.md files nest. An agent working in a monorepo reads the root file, then the closest one to the file it is editing, and the closest file wins on conflicts — explicit instructions in your chat prompt override everything. That design supports the pattern most teams converge on: a root file with org-wide conventions (security rules, commit message format, escalation contacts) plus per-directory files with local context (the frontend’s component conventions, the ML repo’s environment quirks). The nesting rule keeps them from fighting.
Migration from an existing per-tool file is intentionally painless. Rename the old file and leave a symlink behind for backward compatibility:
mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.mdSome tools read the file by default; others need a line of configuration. Aider picks it up via a read-file setting in its config, and Gemini CLI points at it with a context fileName setting — both documented on the format’s site. If your team uses several agents, the symlink-plus-config approach means one source of truth and zero duplicated instructions.
Write It Like an Onboarding Doc, Not a Manifesto
The files that pay off share habits with good onboarding docs. They are short — the useful signal for an agent is dense and specific, not lyrical. They state commands exactly as run from the repo root, because an agent will execute them verbatim. They describe constraints as rules, not suggestions, since agents weight imperative guidance more reliably than prose preferences. And they are updated as part of normal development: when the test command changes or a directory becomes generated, the file changes in the same commit.
Three anti-patterns are worth naming. First, the dump: pasting your entire architecture wiki into the file. Every unnecessary token dilutes the instructions that matter and eats context that could hold your actual task. Second, the stale file: an AGENTS.md that says to run a test command which was renamed two quarters ago actively teaches every agent the wrong thing — and agents follow it faithfully. Third, the manifesto: pages of philosophy with no commands. Agents need the build command, not your team’s values statement.
An API for Your Repository
The mental model that makes AGENTS.md click is that your repository now has two interfaces. One is the code itself, for humans and compilers. The other is the agent context: an interface consumed by every tool that reads the repo — the ones you use today and the ones you will swap in next year. Keeping that second interface deliberate, tested, and current is cheap. The alternative is explaining your build system from scratch in every session, forever.
If you have not written one yet, start with three lines: the build command, the test command, and the one rule you find yourself repeating to both new hires and AI assistants. That minimal file already outperforms most documentation in the repo — and unlike the README, it gets read by the teammate that never skips a word.