AGENTS.md is a plain markdown file that tells coding agents how to work in your repo. The agents.md site lists 23 compatible tools, including Codex, Cursor, Jules and GitHub Copilot. Antigravity reads it too, and so does Claude Code when there's no CLAUDE.md. Put one at the root. Add nested ones in folders that have their own rules.
In a generated repo, AGENTS.md is the hub: the one instruction file every agent reads. Below: which agents load it and how, a template to copy, and real root and nested files from a generated Next.js repo.
What is AGENTS.md?
The agents.md site calls it a README for agents. Your README is for humans. AGENTS.md holds what an agent needs: commands, conventions, tests, and what not to touch.
- It's plain markdown. No required fields. The spec says "Use any headings you like."
- It's one file for many tools. You stop keeping a separate config per agent.
- Agents act on it. List your test commands and the agent will try to run them and fix failures before it finishes. That's from the format's own FAQ.
- It's living documentation. Update it every time an agent gets something wrong twice.
Which tools read AGENTS.md
| Tool | Reads AGENTS.md? | How |
|---|---|---|
| OpenAI Codex | Yes | Global ~/.codex/AGENTS.md, then each folder from the git root down to where you launched it |
| Cursor | Yes | The root and any subfolder. Plain markdown, no metadata |
| GitHub Copilot | Yes | Root and nested, in the CLI, VS Code and the cloud agent |
| Antigravity | Yes | Root and nested. It also reads GEMINI.md |
| Claude Code | Yes, from v2.1.277 | Only when no CLAUDE.md exists in the project or a parent folder. A rule in .claude/rules/ can import it in any version |
| Gemini CLI | With config | List it in context.fileName in .gemini/settings.json |
| OpenCode | Yes | Nested files load lazily. CLAUDE.md is the fallback |
| Kiro | Yes | The root file. Nested files load on every turn |
| Windsurf (Devin Local) | Yes | It reads CLAUDE.md too |
| JetBrains AI | Junie: yes | AI Assistant chat doesn't. A rule in .aiassistant/rules/ points it at AGENTS.md |
| Aider | With config | read: AGENTS.md in .aider.conf.yml |
| Others | Yes | Amp, Factory Droid, Warp, Cline, Kilo Code, Goose, Augment Code, Qwen Code, Crush, Jules and more |
Zed is the odd one. It reads exactly one file: the first match from a list where AGENTS.md comes after .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md and AGENT.md. A leftover .cursorrules hides your AGENTS.md from Zed. Generated repos ship none of those names for that reason.
The details differ most for nested files. That's where people get burned.
How Codex reads AGENTS.md
Codex has the most precise loading rules. Know them or your nested files sit there unread.
Codex builds its instruction chain once, when it starts. In the TUI that usually means once per session.
- Global.
~/.codex/AGENTS.override.mdif it exists. Otherwise~/.codex/AGENTS.md. - Project. From the project root (usually the git root) down to your current directory. In each folder it takes
AGENTS.override.md, elseAGENTS.md, else a fallback name you configured. At most one file per folder. - Merge. Files are joined root first. Files closer to your current directory come later, so they win.
Two limits trip people up:
- It stops at your current directory. Launch Codex at the repo root and it reads the root AGENTS.md only.
src/lib/billing/AGENTS.mdloads only if you launch from that folder or below it. - 32 KiB per chain. Codex stops adding files once the combined size hits
project_doc_max_bytes, which is 32 KiB by default. Root files go in first, so a huge root file crowds out the nested ones.
To see what loaded, Codex's docs suggest codex --ask-for-approval never "Summarize the current instructions". More Codex detail: Codex setup for Next.js.
AGENTS.md template (copy this)
A starting template for a Next.js App Router repo. We wrote it as a skeleton for this page, not from a real project. Replace the commands and paths with yours.
# my-app
Next.js App Router on Vercel. TypeScript strict. Postgres through Drizzle.
## Setup
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Env: copy `.env.example` to `.env.local`. Never print or commit real values.
## Before you finish a task
- `pnpm typecheck`, `pnpm lint` and `pnpm test` pass.
- `git status` shows only the files you meant to change.
## Code style
- Server Components by default. Add "use client" only for state, effects or browser APIs.
- Named exports, except where Next.js needs a default (`page.tsx`, `layout.tsx`).
- Import with `@/`. Never `../../../`.
## Safety
- Never run `git push --force`, `git reset --hard` or `git clean -fd`.
- Parse every request body with Zod at the route boundary.
## Scoped rules
Some folders have their own AGENTS.md. Before you edit a file, read every
AGENTS.md on the path to it, from the root down.
Why it's shaped like that:
- Commands first, exact and copyable. Agents run what you list.
- "Before you finish" is a checklist. The agent runs it on every task.
- Every line is checkable. No "write clean code".
- The last section covers the Codex gap. Nested files below the launch folder don't load on their own, so the root file tells the agent to go read them.
Real AGENTS.md examples from a generated repo
The files below come from a real run of the generator on the Indie SaaS preset. That's Next.js with Better Auth, Neon, Drizzle, Stripe, Resend, PostHog, Sentry, an admin panel and an MDX blog. Every repo gets a root AGENTS.md, plus a nested one in every folder a scoped rule covers: 32 nested files in this one.
The root AGENTS.md
# my-app
Generated by [Agentic Boilerplate](https://github.com/agentic-studio/agentic-boilerplate) from [Agentic Studio](https://theagentic.studio). Same `agentic.config.json`, same repo: regenerate and diff any time.
- **Stack:** Next.js on Vercel (`nextjs-vercel`)
- **Services:** Drizzle ORM (`drizzle`), Neon (`neon`), Better Auth (`better-auth`), Stripe (`stripe`), Resend (`resend`), Sentry (`sentry`), PostHog (`posthog`), Admin panel (`admin-panel`), MDX blog (`blog-mdx`)
- **Design:** Daylight (`daylight`). Every UI change follows [DESIGN.md](DESIGN.md).
- **Package manager:** bun
- **Mode:** solo
## Start here
On a fresh clone, run the `setup` skill: `/setup` in most agents, `$setup` in Codex.
It reads [SETUP.md](SETUP.md), which lists every environment variable, where to get
it, and the order to set the services up.
```sh
bun install
bun run setup:env -- --check # what .env.local still needs
bun run verify
bun run dev
```
## How this repo is set up for agents
This file is the instruction file every agent reads. It holds the rules for the whole repo.
- A folder with its own `AGENTS.md` adds the rules for the files under it. Before you edit a file, read every `AGENTS.md` from the repo root down to its folder. Most agents load them for you.
- `.agents/rules/`: all 30 rules in full, one file each.
- `.agents/skills/`: 29 skills, listed below.
- `.agents/agents/`: 7 subagents, listed below. Agents with their own folder get a copy: `.claude/agents/`, `.codex/agents/`, `.cursor/agents/`, `.github/agents/`, `.gemini/agents/`, `.opencode/agents/`.
- `.agents/hooks/`: 7 guard hooks. They block destructive commands and keep secrets out of the chat. Wired for Claude Code, Codex, Cursor, GitHub Copilot, Antigravity, Gemini CLI and Windsurf. `bun run verify:hooks` proves they still block.
- MCP servers: `better-auth`, `neon`, `posthog`, `sentry`, `stripe`. [SETUP.md](SETUP.md) says how to connect them in each agent.
- `docs/solutions/`: 74 solved problems. Read the relevant one before you re-solve anything.
- `docs/plans/`: one plan per unit of work.
- The `system-manager` subagent owns this agent setup: `AGENTS.md`, `.agents/` and each agent's own folder.
## Workflow
The Compound Engineering plugin adds the loop: `/ce-brainstorm`, `/ce-plan`, `/ce-work`, `/ce-code-review`, `/ce-compound`.
In Codex they start with `$`. [SETUP.md](SETUP.md) has the install line for each agent.
First 42 of 335 lines of AGENTS.md.
The top does three jobs:
- It tells the agent where to start. Run the
setupskill (/setup, or$setupin Codex). It readsSETUP.md. - It maps the shared folder.
.agents/rules/holds every rule in full,.agents/skills/every skill,.agents/agents/every subagent prompt,.agents/hooks/every guard script. - It says what is enforced, and where. The guards are wired for 7 named agents, and
verify:hooksproves they still block. An instruction file that admits its limits is worth more than one that pretends.
The rest of the root file:
- Repo-wide rules, in full. Code style, git hygiene, security. They apply everywhere, so they sit at the root.
- A link for any rule too long to copy. It points at the full text in
.agents/rules/. - A "Scoped rules" index. Every nested AGENTS.md, with how many rules it holds.
- Rules for root files. A rule on
next.config.tsorpackage.jsonhas no subfolder to live in, so the root links to it. - Skills and subagents. All 29 skills and 7 subagents, by name.
The root file uses about half of Codex's 32 KiB budget. That leaves room for the nested files on the chain.
A nested AGENTS.md for the Stripe webhook
This one lives in src/app/api/webhooks/stripe/. It holds one rule: verify every Stripe webhook and keep every handler idempotent.
# src/app/api/webhooks/stripe
Rules for files under `src/app/api/webhooks/stripe`. The root `AGENTS.md` and every
`AGENTS.md` between it and this folder apply here too.
## Verify every Stripe webhook, keep every handler idempotent
Applies to: `src/app/api/webhooks/stripe/**`, `src/lib/billing/provider.ts`, `src/lib/billing/webhook.ts`
Source: `stripe`
The webhook route is an unauthenticated public endpoint. The signature is the
only thing between a Stripe event and a forged POST that grants a lifetime
plan.
The route is three lines: `processWebhook(billingProvider, request)`. The
pipeline in `src/lib/billing/webhook.ts` is shared by every provider, and the
Stripe parts are `verifyWebhook` and `translate` in `provider.ts`. Keep it that
way: nothing Stripe-specific in the route.
**Read the body as text.** `processWebhook` calls `request.text()` and hands
those exact bytes to `verifyWebhook`. `request.json()` reorders keys and every
signature check fails. Never add a body parser or middleware in front of it.
First 22 of 72 lines of src/app/api/webhooks/stripe/AGENTS.md.
Every nested file follows the same shape:
- A scope line. The root and every AGENTS.md in between apply here too.
- One section per rule. Each has
Applies to:(the globs it came from) andSource:(the battery that ships it). - The full rule text. Real functions, real files, and further down, the status codes that drive Stripe's retries. Nothing vague.
More on what the Stripe battery ships: /with/stripe.
A nested AGENTS.md that links instead of copying
Deep folders inherit a long chain: the root, src/, src/app/ and so on. The generator keeps every chain under 30 KiB, under Codex's limit. When a folder runs out of room, its AGENTS.md links each rule to its full text instead. This is src/app/AGENTS.md, in full:
# src/app
Rules for files under `src/app`. The root `AGENTS.md` and every
`AGENTS.md` between it and this folder apply here too.
## Rules
Too long to copy here. Read each one before you edit a file it applies to.
- `.agents/rules/event-naming.md`: Events are declared in the catalogue, named object_verb, past tense (`src/lib/analytics/**`, `src/app/**`, `src/components/**`)
- `.agents/rules/identify-timing.md`: Identify before the first event that matters, reset on sign-out (`src/lib/analytics/**`, `src/app/**`, `src/components/**`)
- `.agents/rules/landing-and-legal.md`: Landing page, legal pages and llms.txt (`src/lib/site.ts`, `src/lib/llms.ts`, `src/app/page.tsx`, `src/app/(legal)/**`, `src/app/llms.txt/**`, `src/components/marketing/**`, `src/components/site/**`)
- `.agents/rules/roles-are-server-side.md`: Roles are decided on the server, every time (`src/app/**`, `src/components/**`, `src/lib/auth/**`)
- `.agents/rules/server-truth-and-pii.md`: Server events for anything a client can lie about, and never PII in properties (`src/lib/analytics/**`, `src/app/**`, `src/components/**`)
- `.agents/rules/stripe-server-boundary.md`: Stripe objects are server-only (`src/lib/billing/**`, `src/app/api/webhooks/stripe/**`, `src/app/**`)
- `.agents/rules/tokens-only.md`: Daylight: tokens only, and both modes every time (`src/components/**`, `src/app/**`)
- `.agents/rules/ui-kit.md`: Build UI from the component kit (`src/components/**`, `src/app/**`)
src/app/AGENTS.md, as generated.
Each line names the rule, what it's about and the files it covers. An agent opens the full rule before it edits a matching file. Agents with their own glob-scoped rules (Cursor, Antigravity, Kiro) also get a native copy of a linked rule, scoped to exactly these folders.
A nested AGENTS.md for blog content
Rules don't have to be about code. This one sits in content/ and only matters to someone writing a post.
# content
Rules for files under `content`. The root `AGENTS.md` and every
`AGENTS.md` between it and this folder apply here too.
## Posts are validated content, not free-form files
Applies to: `content/**`
Source: `blog-mdx`
### Every post needs frontmatter, and it has to validate
`src/lib/blog/frontmatter.ts` is the contract. A file that does not satisfy it
fails the build, not the review:
- `title`: required, under 70 characters.
- `description`: required, 50 to 160 characters. It is the meta description,
the blog-index excerpt and the RSS `<description>`. "TODO" is not a
description, and neither is the first sentence of the post copied verbatim.
- `date`: required, quoted, ISO `YYYY-MM-DD`. Quote it or YAML turns it into a
`Date` and the type check fails.
- `tags`: optional, lowercase and hyphenated (`edge-runtime`, not `Edge
Runtime`). Reuse an existing tag before inventing one; check `allTags()`.
- `author`: optional string.
- `draft`: optional boolean. `true` hides the post from the index, the feed
and the sitemap in production, while leaving it visible on the dev server.
First 26 of 66 lines of content/AGENTS.md.
An agent editing a post reads the frontmatter contract. An agent fixing a webhook never needs to.
Which agents read nested AGENTS.md files
The spec's short version: the closest AGENTS.md to the edited file wins, and an explicit instruction in chat beats every file. How each tool applies that:
| Tool | Nested AGENTS.md behavior |
|---|---|
| Codex | Joins files from the root down to your launch folder. Closer files come later and win. Files below the launch folder don't load |
| Cursor | Combines nested files with their parent folders. The more specific instruction wins |
| GitHub Copilot | Reads the root, your working folder, the folders between, and folders on the path to a file |
| Antigravity | Walks the folder tree and loads each level's file |
| OpenCode | Loads nested files lazily |
| Kiro | Loads nested files on every turn, not only for their folder |
| Claude Code | When it reads AGENTS.md natively, a subfolder's file loads once Claude opens a file there with the Read tool, unless that folder has its own CLAUDE.md |
Generated repos give Claude Code the same folder rules as .claude/rules/*.md with paths:, and turn its nested AGENTS.md loading off with claudeMdExcludes, so Claude Code loads nothing twice. AGENTS.override.md is a Codex feature. Claude Code doesn't read AGENTS.override.md, AGENTS.local.md, or anything under .agents/.
AGENTS.md best practices
| Practice | Why |
|---|---|
| Lead with exact commands | Agents run the checks you list |
| Write checkable rules | "Named exports only" can be verified. "Keep it clean" can't |
| Repo-wide rules at the root, folder rules in nested files | The closest file wins, and agents load less noise |
| Tell the agent to read nested files on the path | Codex stops at the launch folder |
| Watch the size of every chain | Codex stops adding files at 32 KiB, root first |
| Link a rule when it doesn't fit | A path to the full text beats a rule Codex never sees |
| Say what isn't enforced | Name the agents your hooks run in |
| Keep one source for every agent | Hand-kept CLAUDE.md, AGENTS.md and Cursor rules drift apart |
| Update it when a correction repeats | The spec calls it living documentation |
Common AGENTS.md mistakes
- Assuming nested files load from the root. In Codex they don't, unless you launch inside that folder.
- A giant root file. Past 32 KiB, Codex adds nothing more. Nested files are the first to go.
- The wrong file name. Codex reads
AGENT.md,CLAUDE.mdor any other name only if you list it inproject_doc_fallback_filenames, and only in folders with no AGENTS.md. That list is empty by default. - Treating it as a guard. AGENTS.md is text. It can say "never force push". It can't stop one.
- Two files that disagree. Keep a CLAUDE.md next to AGENTS.md and Claude Code reads the CLAUDE.md, not AGENTS.md. Edit one, forget the other, and your agents follow different rules.
- Leftover legacy files. A
.cursorrulesor.github/copilot-instructions.mdwins over AGENTS.md in Zed. - Agent-only content in the shared file. Claude Code subagent tool lists and hook wiring mean nothing to Codex. Put them in
.claude/. - README copy. Badges, a project pitch, a directory tree. Agents can read the tree. Give them what they can't work out.
Generate AGENTS.md for your stack
Every generated repo ships AGENTS.md, whatever agents you pick. One rule source, every format, no drift. You get:
- A root AGENTS.md with the repo-wide rules, a scoped-rules index, the skills and the subagents.
- A nested AGENTS.md in every folder a scoped rule covers, every chain under Codex's limit.
.agents/with every rule, skill, subagent prompt and guard script, for the agents that read that folder.- Each agent's own files on top:
.claude/,.codex/,.cursor/,.github/,.gemini/and the rest.
Pick your agents at /build. All 10 are on by default. It's $99 once, with lifetime updates. How each agent differs: the agentic layer. What the auth battery adds to the rules: Better Auth. The problems those rules prevent are written up in the cookbook.
Keep going
- CLAUDE.md template: the Claude Code side, and how it imports AGENTS.md.
- CLAUDE.md vs AGENTS.md: which one you need, and how to run both.
- Codex setup for Next.js: skills, hooks, subagents and MCP in Codex.
- GitHub Copilot setup for Next.js: custom agents, hooks and MCP in Copilot.
- Cursor rules for Next.js:
.mdcrules with globs, and when you still need them.
FAQ
What is AGENTS.md?
AGENTS.md is a plain markdown file with instructions for AI coding agents: setup commands, tests, code style and rules. It has no required fields. Codex, Cursor, GitHub Copilot, Antigravity, Jules and many other tools read it.
Where do I put AGENTS.md?
At the root of your repo. Add a nested AGENTS.md inside any folder with its own rules, like src/app/api/webhooks/stripe/. In Codex, personal defaults for every repo go in ~/.codex/AGENTS.md.
Does Cursor read AGENTS.md?
Yes. Cursor reads AGENTS.md in the project root and in any subfolder, as plain markdown with no metadata. For rules scoped by file pattern, Cursor's .cursor/rules/*.mdc files give you globs and descriptions.
Does GitHub Copilot read AGENTS.md?
Yes. Copilot reads the root AGENTS.md and nested ones, in the CLI, VS Code and the cloud agent. A generated repo ships no .github/copilot-instructions.md, because AGENTS.md already covers it.
Does Claude Code read AGENTS.md?
Yes, from v2.1.277, when your repo has no CLAUDE.md or CLAUDE.local.md in the working directory or any folder above it. To load it in every case, import it: @AGENTS.md in a CLAUDE.md, or @../../AGENTS.md in a file in .claude/rules/.
Can I have more than one AGENTS.md?
Yes. Nested files in subfolders add rules for that part of the repo, and the closest one to the edited file wins. In Codex, only the files from the root down to your launch folder load.
How big can AGENTS.md be?
Codex stops adding instruction files once their combined size reaches 32 KiB, its default project_doc_max_bytes. You can raise the limit, but moving folder rules into nested files usually works better.
Sources
Tool behavior is from the official docs, checked on October 8, 2026. Tools change. The docs win.
Keep reading
- CLAUDE.md template for Next.js, with real examplesA CLAUDE.md template for Next.js you can copy, where the file goes, what belongs in it, and how a repo shared with other agents loads AGENTS.md instead.
- CLAUDE.md vs AGENTS.md: which one you needCLAUDE.md is Claude Code's file. AGENTS.md is the one Codex, Cursor, Copilot and most other agents read. Who reads what, and how to keep both in sync.
- Cursor rules for Next.js, with real .mdc examplesHow Cursor rules work: the .mdc format, globs, alwaysApply and the four rule types, when a nested AGENTS.md is enough, and real Next.js rules to copy.
- Claude Code skills, with 29 real examplesA Claude Code skill is a SKILL.md file that becomes a slash command Claude can also load on its own. How to write one, what to avoid, and 29 real examples.