What is AGENTS.md? The one file that makes your repo agent-ready
One file the agent reads every session — your conventions, commands, and guardrails. It's the highest-leverage thing you can add to a codebase you build with AI.
AGENTS.md is a Markdown file at the root of your repository that tells an AI coding agent how your project works before it writes a line of code. Think of it as the README you'd write for a new senior engineer who joins, works one session, and forgets everything by tomorrow — except the agent reads it every single session. Claude Code, Cursor, and most agent runtimes look for it automatically.
Why coding agents need one
An agent with no AGENTS.md has to guess: which package manager, how to run the tests, what your conventions are, which files are dangerous to touch. It guesses wrong, and you spend the session correcting it. A good AGENTS.md front-loads those answers once, so the agent starts every task already oriented. In practice it's the difference between an agent that helps and one that quietly accrues debt.
What to put in it
- Commands: how to install, run the dev server, run tests, and — most importantly — a single verify command (typecheck + tests + a smoke check).
- Conventions: language/framework, folder layout, naming, and any patterns you always follow.
- Guardrails: what NOT to touch (generated files, migrations, secrets) and any action that needs a human.
- Definition of done: the agent must run verify and not call a task complete if it fails.
- Where things live: a one-line map so the agent doesn't grep the whole tree to find the auth code.
A minimal template
# AGENTS.md
## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Verify (run before you're done): `pnpm verify` # typecheck + test + build
## Conventions
- Next.js (App Router) + TypeScript strict. Server components by default.
- Match the style of the file you're editing.
## Guardrails
- Never edit files in `db/migrations/` or anything in `.env*`.
- Ask before deleting files or changing auth.
## Done means
- `pnpm verify` passes. If it doesn't, it's not done.Common mistakes
- Writing an essay. Keep it scannable — the agent re-reads it constantly, so bullets beat prose.
- No verify command. Without one, the agent can't check its own work and 'looks done' ships broken.
- Letting it rot. Update it when your commands or structure change, or it starts actively misleading the agent.
Not sure how agent-ready your repo already is? Paste it into the free Agent-Ready Score at /score — it grades your AGENTS.md, verify command, guardrails and structure 0–100 and lists the exact gaps to fix. And if you'd rather start from a codebase that already has all of this done right, that's what AgentShip is for.