Skip to content

AGENTS.md examples, from a real Next.js repo

What AGENTS.md is, a template to copy, real root and nested files from a generated Next.js repo, and how Codex, Cursor, Copilot and Claude Code load them.

Updated · 11 min read

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

ToolReads AGENTS.md?How
OpenAI CodexYesGlobal ~/.codex/AGENTS.md, then each folder from the git root down to where you launched it
CursorYesThe root and any subfolder. Plain markdown, no metadata
GitHub CopilotYesRoot and nested, in the CLI, VS Code and the cloud agent
AntigravityYesRoot and nested. It also reads GEMINI.md
Claude CodeYes, from v2.1.277Only when no CLAUDE.md exists in the project or a parent folder. A rule in .claude/rules/ can import it in any version
Gemini CLIWith configList it in context.fileName in .gemini/settings.json
OpenCodeYesNested files load lazily. CLAUDE.md is the fallback
KiroYesThe root file. Nested files load on every turn
Windsurf (Devin Local)YesIt reads CLAUDE.md too
JetBrains AIJunie: yesAI Assistant chat doesn't. A rule in .aiassistant/rules/ points it at AGENTS.md
AiderWith configread: AGENTS.md in .aider.conf.yml
OthersYesAmp, 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.

  1. Global. ~/.codex/AGENTS.override.md if it exists. Otherwise ~/.codex/AGENTS.md.
  2. Project. From the project root (usually the git root) down to your current directory. In each folder it takes AGENTS.override.md, else AGENTS.md, else a fallback name you configured. At most one file per folder.
  3. 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.md loads 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 setup skill (/setup, or $setup in Codex). It reads SETUP.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:hooks proves 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.ts or package.json has 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) and Source: (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.

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:

ToolNested AGENTS.md behavior
CodexJoins files from the root down to your launch folder. Closer files come later and win. Files below the launch folder don't load
CursorCombines nested files with their parent folders. The more specific instruction wins
GitHub CopilotReads the root, your working folder, the folders between, and folders on the path to a file
AntigravityWalks the folder tree and loads each level's file
OpenCodeLoads nested files lazily
KiroLoads nested files on every turn, not only for their folder
Claude CodeWhen 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

PracticeWhy
Lead with exact commandsAgents 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 filesThe closest file wins, and agents load less noise
Tell the agent to read nested files on the pathCodex stops at the launch folder
Watch the size of every chainCodex stops adding files at 32 KiB, root first
Link a rule when it doesn't fitA path to the full text beats a rule Codex never sees
Say what isn't enforcedName the agents your hooks run in
Keep one source for every agentHand-kept CLAUDE.md, AGENTS.md and Cursor rules drift apart
Update it when a correction repeatsThe 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.md or any other name only if you list it in project_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 .cursorrules or .github/copilot-instructions.md wins 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

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.