AGENTS.md generator
AGENTS.md is the one agent-instructions file that a growing list of tools read from the same
place — a plain Markdown file at your repo root. Instead of maintaining a .cursorrules, a
CLAUDE.md and a Copilot file that drift apart, you write one. This page explains what belongs
in it, how it differs from the tool-specific files, and gives you a template to copy.
What AGENTS.md is — and why it exists
AGENTS.md is a convention, not a proprietary format: a Markdown file at the root of your
repository that coding agents read for build commands, conventions and constraints. It was introduced in
2025 as a shared standard so a project stops needing a separate instructions file per tool. The pitch is
simple — one file, many agents, plain Markdown with no required schema.
It does not replace your README. The README is for humans: what the project is, how to install it, how to
contribute. AGENTS.md is for the agent: the exact test command, the lint gate that must pass,
the directory it must never touch, the convention that is not obvious from the code. Keeping them separate
keeps the README readable and lets you put agent-only instructions (like "run pnpm typecheck
before you claim done") somewhere they will actually be read.
AGENTS.md is the missing third — the
cross-tool one. If you generate all three, keep the body identical and let each file be a thin wrapper;
the whole point is to stop them drifting.
AGENTS.md vs CLAUDE.md vs .cursorrules — which to use
They overlap almost entirely in content. The difference is which tool reads which file, and how tightly it is coupled to one vendor.
| File | Read by | Scope | Use it when |
|---|---|---|---|
AGENTS.md |
Any tool that adopted the convention (see list below) | Cross-tool, whole repo | Your team uses more than one agent, or you want one file to maintain |
CLAUDE.md |
Claude Code | Loaded into memory at session start (root + nested) | You want Claude-specific memory, @import of other files, or per-directory nesting |
.cursorrules / .cursor/rules/*.mdc |
Cursor | Prepended to completions; .mdc supports glob scoping |
You need rules that apply only to certain paths (globs: in .mdc) |
AGENTS.md as the source of truth. If you also use
Claude Code and want its memory features, add a one-line CLAUDE.md that just says
See @AGENTS.md. Keep .cursorrules only if you need Cursor's path-scoped
.mdc rules — otherwise let Cursor read AGENTS.md too. One canonical file, thin
wrappers pointing at it. That is the whole discipline.
Recommended sections
An AGENTS.md earns its keep when every line tells the agent something it could not infer from
the code. Keep these sections; drop anything generic.
- Project overview. Two sentences: what this is and the one architectural fact that shapes everything (monorepo? event-driven? multi-tenant?).
- Build & test commands. The exact commands —
pnpm dev,pnpm test,pnpm typecheck— including any that must pass before the agent claims it is done. This is the highest-value section; agents check "done" against it. - Code style & conventions. Only the non-obvious ones: "money is stored in cents", "dates are UTC ISO strings", "all API responses go through
toDTO()". Skip "use meaningful names". - Project structure. Where things live and the boundary rules: "domain logic in
core/, never importcorefromui/". - Do-nots. The constraints from a bug you already hit: a banned import, "never edit generated files in
*/__generated__/*", "do not run migrations against prod". These are the lines that actually change behaviour.
package.json or the
code. Every wasted line dilutes the two rules that matter. Have a bloated file? The free
rules-file audit scores it and marks the lines to cut — it reads
AGENTS.md, CLAUDE.md and .cursorrules alike.
Which tools read AGENTS.md today
Adoption is what makes the convention worth using. As of 2026 the file is picked up by a broad set of agents, including:
- OpenAI Codex — the agent the convention was first shipped with.
- Cursor — reads
AGENTS.mdalongside its own.cursor/rules. - Claude Code — supported via
AGENTS.mdin addition toCLAUDE.md. - GitHub Copilot coding agent, Jules (Google), Aider, Zed, RooCode and others in the agentic-coding space.
The list keeps growing precisely because the format is trivial — plain Markdown, agreed filename, root of
the repo. There is nothing to parse and nothing to lock into. If a tool you use does not read it yet, a
two-line wrapper file that points at AGENTS.md bridges the gap without duplicating content.
Copy-paste AGENTS.md template
Start from this and delete every line that does not apply. If a line would not change what the agent does, it does not belong.
# AGENTS.md
## Project overview
Multi-tenant billing dashboard. Next.js App Router + Postgres (Prisma).
Tenancy is enforced at the query layer — every query is scoped by tenantId.
## Build & test
- Install: pnpm install
- Dev: pnpm dev
- Test: pnpm test # must pass before done
- Types: pnpm typecheck # must pass before done
- Lint: pnpm lint --fix
## Code style
- Money is stored and computed in integer cents. Never use floats for money.
- Dates cross boundaries as UTC ISO strings; convert at the edge only.
- All API responses go through toDTO(); never return a Prisma model raw.
## Structure
- Domain logic in src/core (framework-free)
- UI in src/app; never import from src/core/internal
- Generated Prisma client in src/generated — do not edit by hand
## Do not
- Do not run migrations against the DATABASE_URL in .env.production
- Do not add a query that is not scoped by tenantId
- Do not import from src/legacy/* — it is being deletedCLAUDE.md containing one line — See @AGENTS.md — and let Cursor and Codex read
AGENTS.md directly. One file to update, every agent in sync.
Frequently asked questions
What is AGENTS.md?
A plain Markdown file at the root of your repository that coding agents read for build commands, conventions and constraints. It is a shared convention introduced in 2025 so a project needs one instructions file instead of a separate one per tool. There is no required schema — it is just Markdown.
How is AGENTS.md different from CLAUDE.md and .cursorrules?
The content overlaps almost entirely; the difference is which tool reads which file. AGENTS.md is cross-tool. CLAUDE.md is Claude Code specific and adds memory features like @imports and per-directory nesting. .cursorrules (now .cursor/rules/*.mdc) is Cursor specific and supports path-scoped rules via globs. Use AGENTS.md as the source of truth and let the others be thin wrappers pointing at it.
Do I still need a CLAUDE.md if I have AGENTS.md?
Only if you want Claude Code's memory features. A common pattern is a one-line CLAUDE.md that says "See @AGENTS.md" so you maintain a single canonical file and Claude still loads it. Cursor and Codex can read AGENTS.md directly.
Which tools read AGENTS.md today?
As of 2026 it is picked up by OpenAI Codex (which shipped the convention), Cursor, Claude Code, GitHub Copilot's coding agent, Google Jules, Aider, Zed, RooCode and others. Adoption keeps growing because the format is trivial: agreed filename, plain Markdown, repo root.
What should I put in AGENTS.md?
A two-sentence project overview, the exact build and test commands (including any that must pass before the agent claims done), the non-obvious code conventions, the project structure with import boundaries, and a "do not" list of constraints from bugs you already hit. Leave out role-play preambles and generic best practices — they only dilute the rules that matter.
Is my input uploaded anywhere?
The template on this page is static — you copy it and fill it in locally, nothing is sent. If you already have a bloated rules file, the free CLAUDE.md audit tool scores it in your browser and marks lines to cut, and it reads AGENTS.md too.
A rules file points the agent. A spec tells it what to build.
AGENTS.md assumes the agent already knows the project. The paid generator asks 117 questions
and writes the specification behind it — schema, auth, payments, security, file layout — with the config
files generated alongside. 2 free prompts with an account, no card.