Docs
What is AGENTS.md?
The instruction file coding agents read before touching your repo — what goes in it, where it lives, and a working example.
AGENTS.md is a plain markdown file, checked into the root of your repository, that coding agents read before they start working. Claude Code, OpenAI Codex, Cursor, Zed, and a growing list of tools look for it automatically. Think of it as onboarding documentation for a very fast, very literal new teammate — one who joins your project fresh every single session.
Why it exists
An agent dropped into your repo can read code, but code doesn't say why. It doesn't say that the payments module is frozen pending an audit, that you use pnpm and a stray npm install corrupts the lockfile, or that the failing test on main is known and being fixed by someone else. Every fact like that lives in your head — until you write it down. AGENTS.md is where it goes.
Without one, agents guess. With a good one, they follow your conventions, run your commands, and stop at the lines you drew.
What belongs in it
The files that work in practice cover seven kinds of content:
- Identity — who the agent is in this repo. A senior pair? A cautious reviewer? One sentence changes tone and risk appetite.
- Knowledge — facts the code can't reveal: what the project is, architecture boundaries, known traps, environment quirks.
- Conventions — the style contract: TypeScript strictness, naming, commit format, framework idioms.
- Workflow — how work happens: plan before coding, test-first, verify before declaring done.
- Tools — the blessed commands: dev server, tests, lint, package manager. Agents guess script names otherwise.
- Constraints — the hard lines: never commit secrets, never edit migrations, never add dependencies unasked.
- Examples — one good commit message or component skeleton pins a format better than a page of rules.
Where it lives
Repo root, named AGENTS.md. Monorepos can add per-package files — most tools read the nearest one up the tree from wherever they're working. Keep one source of truth: if you also maintain a CLAUDE.md or .cursor/rules, generate them from the same content instead of hand-syncing three copies.
A minimal example
# Agent Instructions
You are a senior engineer pair-programming with the maintainer.
## Project Knowledge
Acme is a subscription analytics dashboard. Next.js 16 + Postgres.
The billing/ module is frozen pending an audit — do not modify it.
## Tools
- Dev: `pnpm dev` · Tests: `pnpm test` · Lint: `pnpm lint`
- This repo uses pnpm exclusively. Never run npm or yarn.
## Constraints
- Never read or print values from .env files.
- Schema changes go through migrations, never direct SQL.Twenty lines. It already prevents the four most expensive mistakes an agent could make in that repo.
What to leave out
Everything an agent can discover by reading code: file listings, restated function docs, framework tutorials. Every unnecessary line costs tokens and attention on every request. The test for each line: would the agent plausibly get this wrong without being told? If not, cut it.
Skip the blank page.
Groundrules assembles files like this from curated blocks — pick a starter pack, fill in your project facts, export.