Glossary
What is AGENTS.md?
The instructions file coding agents read before they touch your repo.
Updated 2026-09-09
AGENTS.md is a markdown file in your repository that tells coding agents how to work in it: which commands to run, which conventions to follow, and what to leave alone.
Your README sells the project to humans. AGENTS.md is the version you write for machines. It says tests run with pnpm test, migrations are generated rather than hand written, and dist is off limits. Agents that support the convention read it before they start editing, so you stop repeating the same three corrections every session.
The convention spread out of OpenAI's Codex work and got picked up quickly because everyone hit the same wall: agents guess your build steps and your house style, and they guess wrong. Most agent tools now read AGENTS.md. Some also read their own file, like CLAUDE.md for Claude Code or rules files in editors. Pick AGENTS.md as the source of truth and have the others point at it instead of maintaining three copies that drift.
Placement decides scope. A file at the repo root covers everything. In a monorepo you can put one in each package, and agents generally use the closest file to the code they are editing, which is how you keep backend rules out of the frontend package.
AGENTS.md at repo root
# AGENTS.md
## Commands
- install: pnpm install
- dev: pnpm dev
- test: pnpm test (must pass before you finish)
- typecheck: pnpm tsc --noEmit
## Conventions
- Server components by default. Add 'use client' only when you need state.
- Prisma schema changes need a migration, never edit the DB by hand.
- No new dependencies without asking.
## Do not touch
- .env files
- generated/ and dist/Where people get this wrong
- Long files get skimmed. Every line is context the model pays for on every turn, so keep it to about a page of rules that actually change behaviour.
- Do not paste your whole style guide. Write the five things people get wrong in review.
- Commands have to be copy paste correct. A wrong script name is worse than no file, because the agent trusts it and burns a turn failing.
- Vague instructions do nothing. Write good code is noise. Run pnpm test before finishing is a rule.