What is AGENTS.md?
A plain markdown file at the root of a repository that tells an AI coding agent how to work in it. The README is written for a person deciding whether to use your project. AGENTS.md is written for whoever has to change it.
Claude Code, Cursor, Codex, and Copilot all read it. Nothing validates it and there is no schema to follow, which is why so many of them are useless: a file with no commands in it gives an agent nothing to act on.
What belongs in it
The test that matters is whether a capable stranger could make a small change and verify it using only this file. Commands first, conventions second, none of the persuasion a README carries.
# AGENTS.md
## Setup
pnpm install
## Commands
pnpm dev # local server on :3000
pnpm test # full suite, must pass before any commit
pnpm typecheck # tsc --noEmit
## Conventions
- Server code in src/server, client in src/app.
Never import across that line.
- Database changes go through a migration
in db/migrations.
- Tests sit next to the file they cover.
## Gotchas
- The dev server needs Postgres.
Run docker compose up -d db first.
- Anything under src/generated is built from
the schema. Edit the schema.Measured across the 864 most-starred repositories on GitHub, 25 August 2026
The full method is on the findings page, and every check is listed on the marking scheme.
The format
There is nothing to conform to. Headings are conventional rather than required, and the four below are the ones agents cope with best because they map to the order the work happens in.
Setup. The exact install command, the runtime version, and anything that has to be running before the project will start. Write the version as a number. "Recent Node" is not something an agent can check.
Commands. How to run it, how to test it, how to lint and typecheck it. This is the part agents use most and the part most files leave out.
Conventions. The rules that are real but invisible from the code. Where things live, what must never import what, how migrations are made.
Gotchas. Everything a new person gets wrong in their first week. Generated directories, services that have to be up, tests that only pass in a certain order.
Keep it under about 120 lines. The file is loaded on every turn, so length is paid for out of the same budget as the code the agent needs to read.
A complete example
A real one for a Python service, with the version pinned, the commands named, and the two things that would otherwise cost an afternoon written down. Copy the shape, not the contents.
# AGENTS.md
Billing API. FastAPI service, Postgres, deployed on Fly.
## Setup
Python 3.12 exactly. 3.13 breaks the psycopg build.
uv sync
cp .env.example .env
docker compose up -d db
uv run alembic upgrade head
## Commands
uv run uvicorn app.main:app --reload # local, port 8000
uv run pytest # full suite, ~40s
uv run pytest tests/unit # fast subset
uv run ruff check . && uv run mypy app # must be clean before commit
## Conventions
- Routes in app/api, business logic in app/services, database
access in app/repos. Routes never touch the database directly.
- Every schema change needs an Alembic migration. Never edit a
migration that is already on main.
- Money is an integer number of cents. There are no floats in
this codebase and there should not be.
## Gotchas
- Tests need the database running. Without it pytest fails at
import with an error that does not mention Postgres.
- app/generated/ is built from the OpenAPI spec by
scripts/codegen.sh. Editing it does nothing.
- The Stripe tests hit a sandbox and need STRIPE_TEST_KEY set.
They skip without it, so a green run does not mean they passed.The same thing for your language, with the gaps that are specific to each one measured across the crawl.
What makes one bad
Too short. Three lines saying "this is a TypeScript project, write clean code" changes nothing about what an agent does.
Too long. Twenty thousand characters of philosophy loads on every turn and crowds out the code the agent needs to read.
No commands. The most common failure by a wide margin. If the file never says how to run the tests, the agent guesses, guesses wrong, and reports success anyway.
The wrong filename. AGENTS.md is vendor-neutral and the most widely read. CLAUDE.md, .cursorrules, and .github/copilot-instructions.md are tool-specific. Keeping one alongside is fine, but AGENTS.md is the one that works everywhere.
Copied from the README. Marketing prose about what the project is for tells an agent nothing about how to change it safely.
Stale commands. A file naming a script that was renamed two years ago is worse than no file, because the agent trusts it and fails in a way it cannot explain.
Common questions
What is an AGENTS.md file?
A markdown file at the root of a repository that tells an AI coding agent how to work in it. Setup commands, test commands, conventions, and the traps that are not visible from the code. Agents read it before they touch anything, the same way a new colleague reads the onboarding doc first.
Is it AGENTS.md or agent.md?
AGENTS.md. Plural, all capitals, with the .md extension, sitting at the repository root. Nothing enforces this, but tools look for that exact name, so agent.md or Agents.md will often be skipped. If you already have one under a different name, rename it and keep a one-line pointer where the old one was.
Is there an official AGENTS.md spec?
No. There is no schema, no required headings, and no validator. It is ordinary markdown, and every tool reads it as plain text. What the convention settles is the filename and the location, which is all it needs to settle for an agent to find the file.
Where does AGENTS.md go?
The repository root, next to the README. In a monorepo you can add one per package as well, and most agents read the nearest one to the file they are editing. Keep the root file short and let the package-level files carry the specifics.
How is AGENTS.md different from README.md?
Audience. A README argues that someone should use your project, so it leads with what the thing is and why it is good. AGENTS.md assumes that decision is made and answers the next question, which is how to change the code and prove the change works. The overlap is small enough that duplicating the README into AGENTS.md scores badly.
Do I still need CLAUDE.md or .cursorrules?
Usually not. AGENTS.md is the vendor-neutral name and the one most tools read, including Claude Code, Cursor, Codex, and Copilot. Keeping a tool-specific file alongside is fine, but the common pattern now is one AGENTS.md with a CLAUDE.md that is a single line pointing at it, so the two cannot drift apart.
How long should an AGENTS.md be?
Long enough to name the commands, short enough that nobody skims it. Most good ones land between 30 and 120 lines. It loads on every turn an agent takes, so anything that is not instruction is crowding out the code the agent came to read.
Does AGENTS.md actually change what an agent does?
On the parts it names, yes, because the agent stops guessing them. Repositories that ship one have a median agent-readiness score of 78 against 54 for repositories without. That gap is not all caused by the file, since teams that write one usually had a lockfile and working tests already, but naming the test command is the single change that most often stops an agent from reporting success it never verified.
See how yours scores.
Instructions are worth 27 of the 100 marks, and the median repository gets 39% of them.