AGENTS.md template for a repository
Open in the editor Opens as AGENTS.md, ready to edit. Nothing is uploaded.
The shape of it — edit here, or open the full template
Result
Runs entirely in this tab. Open the full editor to work on a real document.
AGENTS.md is the day-one briefing, written once and committed, instead of a
paragraph of context re-pasted into every prompt. This template is the sections
that briefing needs.
The test for what goes in
Would you say it to a competent new contributor on their first morning? Setup steps, the command that must pass before committing, the conventions that come up in review, the two directories not to touch. That is the file.
What fails the test: anything the code already states, anything true of software in general (“write clean code”), and anything that describes the project’s history rather than its rules.
Commands in a table
| Command | What it does |
|---|---|
npm run dev | Dev server on port 3000 with hot reload |
npm test | Full test suite — must pass before committing |
npm run lint | Lint and format check |
A table forces a description next to every command, which is the part that actually gets used. A bare list of commands makes the reader guess which one is the gate.
Style rules, then the escape hatch
List the conventions that come up in review — indentation, quoting, export style — and then add the line that keeps them from doing damage:
- Match the surrounding file's idiom over any rule in this list.
Without it, a style list becomes a mandate to reformat files that were fine, and the diff fills with churn nobody asked for.
Boundaries are the highest-value section
State the limits explicitly, with the reason attached:
- Do not modify db/migrations/ without asking — migrations are
irreversible in production.
- Do not add dependencies without asking.
- src/vendor/ is generated. Edit the generator, not the output.
The reason matters as much as the rule. A boundary with an explanation generalises to the situation you did not think of; a bare prohibition does not.
One file, or one file and a pointer
If the project also has a CLAUDE.md, keep the content in one place and make
the other a two-line pointer. Two maintained copies diverge quickly, and the
failure is silent: both files look authoritative, and nothing indicates which
one was updated last.
Common questions
- What is AGENTS.md?
- A Markdown file at the root of a repository holding the instructions a coding agent needs — setup, commands, conventions and limits. It is an emerging convention aimed at being tool-neutral, so one file can serve whichever assistant a contributor happens to use.
- How is it different from CLAUDE.md?
- Mostly the intended audience. CLAUDE.md is the file Claude Code reads; AGENTS.md is written as a shared convention across tools. The content overlaps almost entirely, which is why plenty of repositories keep one file and have the other reference it.
- Can I have both?
- Yes, and the maintainable arrangement is one real file plus a short pointer — a two-line CLAUDE.md saying "see AGENTS.md" costs nothing and cannot drift. Two full copies will disagree within a month, and nobody will notice which one is stale.
- What belongs in it?
- What you would tell a new contributor on their first day: how to get the project running, which command must pass before committing, the conventions that will come up in review, and the things not to touch. Anything readable from the code itself is filler.
- Should the boundaries section be phrased as prohibitions?
- Yes, and specifically. "Be careful with the database" is not actionable; "do not modify db/migrations/ without asking — migrations are irreversible in production" is. Give the reason alongside the rule, so the boundary survives a situation you did not anticipate.
- Does it need to be Markdown?
- That is the whole point of the convention: plain text with enough structure to scan, readable in a terminal, diffable in review, and parseable by anything. A YAML config could not carry the explanations that make the rules usable.