AGENTS.md is a plain-Markdown file you put at the root of your repository to tell AI coding agents how to work in your project — what the codebase is, how to build and test it, the conventions to follow, and which files they should ignore. Think of it as the README you write for the agent instead of for a human teammate.
Why AGENTS.md exists
When a coding agent opens your repo, it has no idea how your project is set up. Left to guess, it reads files it doesn't need, runs the wrong build command, or writes code that ignores your conventions. AGENTS.md gives it the context up front. You write the instructions once, in one predictable place, and every agent that supports the convention picks them up — instead of re-explaining your project in every chat.
The name is deliberately tool-agnostic. AGENTS.md is emerging as a shared standard that a growing number of coding agents look for, so a single file can brief them all rather than maintaining a different file per tool.
Where it goes
Put AGENTS.md in your repository root. That covers the whole project. In a monorepo you can also drop an AGENTS.mdinside a subdirectory to add package-specific instructions; agents use the nearest one to the file they're working on, so the closer file wins for that folder.
What goes in it
There is no required schema — it's just Markdown, and agents read it the way they read any prose. The sections that earn their keep are:
- A short project overview — the stack, where the real source lives, anything non-obvious about the architecture.
- Build, run, and test commands— the exact commands, so the agent doesn't guess between
npm,pnpm, andyarnor skip your tests. - Conventions — formatting, naming, patterns to follow or avoid. This is where you stop the agent reinventing your house style.
- What to ignore — the files and folders that carry no signal (lockfiles, build output, vendored dependencies). This is the single highest-leverage section, and the one most people leave out.
A working example
Here's a compact AGENTS.md for a typical web app:
# AGENTS.md
## Project
Next.js 16 app (App Router) + TypeScript. Payments via Stripe,
data in Supabase. Source lives in app/, lib/, and components/.
## Setup & test
- Install: `npm install`
- Dev server: `npm run dev`
- Tests: `npm test` (Vitest) — run before every commit
- Lint: `npm run lint`
## Conventions
- Use the semantic color tokens in globals.css; never hard-code hex.
- Server Components by default; add "use client" only when needed.
## Don't read these
- package-lock.json, dist/, .next/, **/*.min.js — generated files
with no signal. Skip them to keep context focused on real code.One thing to know about that last section: an AGENTS.md ignore list is advisory— the agent reads it and usually complies, but nothing stops it from opening a listed file anyway. Some agents also support ignore files their own harness applies as a best-effort block, so the skip doesn't depend on the model's cooperation — how enforcement works.
AGENTS.md vs CLAUDE.md, GEMINI.md, and Cursor rules
Several tools shipped their own version of this idea before a shared name settled: Claude Code reads CLAUDE.md, Gemini reads GEMINI.md, Cursor reads rules under .cursor/rules/, and Copilot reads .github/copilot-instructions.md. They all do the same job — AGENTS.md is just the cross-agent name for it. If you work across multiple tools, the practical move is to keep the content identical everywhere. We break down exactly which tool reads which file, and whether you need more than one, in CLAUDE.md vs AGENTS.md.
The fastest way to write one
The hardest part of a good AGENTS.md is the “what to ignore” list — you have to know which files in your tree are junk. ContextPruner does that part for you: paste your file tree and it classifies every file as keep, prune, or summarize, then writes AGENTS.md with the ignore list filled in — plus CLAUDE.md, GEMINI.md, Cursor rules, Copilot instructions, and the four enforced ignore files, all nine in one pass. It's free and runs entirely in your browser.