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

AGENTS.md is a plain markdown file that tells coding agents how to work in your repo. More than 20 tools support it, including Codex, Cursor, Jules and GitHub Copilot's coding agent. Claude Code reads it too when there's no CLAUDE.md. Put one at the root. Add nested ones in folders that have their own rules.

Below: how each tool loads it, a template to copy, and real root and nested AGENTS.md 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
Claude Code	Yes, from v2.1.277	By default only when there's no CLAUDE.md. A CLAUDE.md can import it with @AGENTS.md
Aider	With config	read: AGENTS.md in .aider.conf.yml
Gemini CLI	With config	"context": { "fileName": "AGENTS.md" } in .gemini/settings.json
Others	Listed as compatible	Jules, Factory, goose, opencode, Zed, Warp, VS Code, Devin, Junie, Amp, Windsurf and more

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 total. 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".

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 with Codex as a target. That's Next.js with Better Auth, Neon, Drizzle, Stripe, Resend, PostHog, Sentry, an admin panel and an MDX blog. You get a root AGENTS.md, plus a nested one in every folder a scoped rule covers. That's more than 30 files in this repo.

The root AGENTS.md

# my-app

Instructions for Codex and any other agent that reads `AGENTS.md`.

Repo-wide rules are below. Path-scoped rules live in a nested `AGENTS.md` in
each directory listed under Scoped rules. Before you edit a file, read every
nested `AGENTS.md` on the path to it, from the top down.

The guard hooks in `.claude/hooks/` are wired for Claude Code only. They do
not run under Codex, so these rules are the only guard against a destructive
command.

First 11 of 306 lines of AGENTS.md.

The top does two jobs. It tells the agent to read every nested AGENTS.md on the path before it edits a file. And it says plainly that the guard hooks don't run under Codex, so these rules are the only guard against a destructive command. 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 "Scoped rules" index. Every nested AGENTS.md, with how many rules each one 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 its source in .claude/rules/.
• Skills. All 28 skills in .agents/skills/, listed by $name.
• More context. docs/onboard.md, docs/solutions/, docs/plans/ and DESIGN.md.

The root file is about 14 KB. That's under half of Codex's 32 KiB budget, which leaves room for the nested files on the path.

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.

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.

How nested AGENTS.md files take precedence

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
Claude Code	When it's reading AGENTS.md (no CLAUDE.md), it loads a subfolder's AGENTS.md once it opens a file there with the Read tool, unless that folder has its own CLAUDE.md

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	Codex stops adding files at 32 KiB combined
Say what isn't enforced	If your hooks only run under Claude Code, say so in the file
Keep one source for every tool	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 combined, 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.
• Claude-only content in the shared file. Claude Code subagents and its hook setup mean nothing to Codex. Put them in CLAUDE.md.
• 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

The generator writes AGENTS.md from the same source as Claude Code's .claude/rules/ and Cursor's .cursor/rules/. One rule, three formats, no drift. With Codex as a target you get:

• A root AGENTS.md with the repo-wide rules, a scoped-rules index and the skills list.
• A nested AGENTS.md in every folder a scoped rule covers.
• 28 skills in .agents/skills/. Codex scans that folder, and you run a skill with $name.

Pick Codex as a target at /build. It's free during launch, then $99 once. How each target 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.

From a terminal: npm create agentic-boilerplate@latest my-app.

Keep going

• CLAUDE.md template: the Claude Code side, with a real example.
• CLAUDE.md vs AGENTS.md: which one you need, and how to run both.
• Cursor rules for Next.js: scoped .mdc rules with globs.
• Claude Code skills: the same skills Codex gets in .agents/skills/.
• Claude Code hooks: the guards AGENTS.md can't enforce.

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, Jules, GitHub Copilot's coding agent 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 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 above it. With both present it reads CLAUDE.md only, so add @AGENTS.md to your CLAUDE.md to load both.

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.