Same job, different readers. CLAUDE.md is Claude Code's instruction file. AGENTS.md is an open format. The agents.md site lists 23 tools that read it, including Codex, Cursor, Jules and GitHub Copilot. Claude Code reads AGENTS.md too, but by default only when no CLAUDE.md exists in the project or any folder above it. Pick based on the agents your team runs, and never keep two hand-edited copies.
The short answer
| Your team uses | Use |
|---|---|
| Claude Code only | CLAUDE.md, plus .claude/rules/ for scoped rules |
| Codex only | AGENTS.md, with nested files per folder |
| Cursor only | AGENTS.md, root and nested. .cursor/rules/*.mdc when you need globs |
| GitHub Copilot only | AGENTS.md, root and nested |
| A mix | AGENTS.md as the one shared file, imported by Claude Code. Or generate every format from one source |
Which agent reads which file
| Agent | Instruction files it reads |
|---|---|
| Claude Code | CLAUDE.md and .claude/rules/. AGENTS.md (root and nested) since v2.1.277, but only when no CLAUDE.md exists in the project or a parent folder |
| Codex | AGENTS.md, from the root down to the folder you work in. Other names only through project_doc_fallback_filenames |
| Cursor | AGENTS.md (root and nested), a root CLAUDE.md (always on), .cursor/rules/*.mdc |
| GitHub Copilot | AGENTS.md (root and nested), CLAUDE.md, .github/copilot-instructions.md, .github/instructions/, .claude/rules/ |
| Antigravity | AGENTS.md and GEMINI.md (root and nested), .agents/rules/ |
| Gemini CLI | GEMINI.md. AGENTS.md once context.fileName in .gemini/settings.json lists it |
| OpenCode | AGENTS.md (nested files lazily), CLAUDE.md as a fallback |
| Kiro | Root AGENTS.md (nested files load on every turn), .kiro/steering/ |
| Windsurf (Devin Local) | AGENTS.md and CLAUDE.md |
| JetBrains AI | Junie reads AGENTS.md. AI Assistant chat needs a rule in .aiassistant/rules/ that points at it |
| Zed | One file: the first match of .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md, GEMINI.md |
Three rows catch people out.
- Claude Code plus both files. With a CLAUDE.md present, it reads CLAUDE.md and skips AGENTS.md. Whatever you put only in AGENTS.md, Claude never sees.
- Codex plus CLAUDE.md. Codex reads
AGENTS.override.mdorAGENTS.mdin each folder. It reads other names only if you list them inproject_doc_fallback_filenames, and that list is empty by default. - Zed plus an old file. Zed reads the first match in its list. A leftover
.cursorrulesor.github/copilot-instructions.mdwins over AGENTS.md. That's why generated repos ship none of those names.
CLAUDE.md vs AGENTS.md, side by side
| CLAUDE.md | AGENTS.md | |
|---|---|---|
| Read by | Claude Code first. Cursor, Copilot and Windsurf read it too | Codex, Cursor, GitHub Copilot, Antigravity, Jules and many more. Claude Code when there's no CLAUDE.md |
| Format | Markdown, any headings | Markdown, any headings |
| Imports | @path/to/file, up to four hops deep | None in the spec. Claude Code expands @path imports inside an AGENTS.md it reads |
| Global file | ~/.claude/CLAUDE.md | ~/.codex/AGENTS.md in Codex |
| Personal per-repo file | CLAUDE.local.md, gitignored | No equivalent in the spec |
| Nested files | Load when Claude reads a file in that folder | Codex: root down to your launch folder. Cursor, Copilot, Antigravity: root and nested |
| Scoped rules | .claude/rules/*.md with paths: | Folder placement is the only scope |
| Size guidance | Under 200 lines per file | 32 KiB per chain in Codex, by default |
| Enforced? | No. Context only | No. Context only |
The last row is the one that matters most. Neither file can stop a command. That's a hook's job, and every agent keeps its hooks in its own config. See guard hooks in every agent.
How Claude Code handles both files
Claude Code reads AGENTS.md directly from v2.1.277. By default:
| Your repo has | Claude reads |
|---|---|
| AGENTS.md, and no CLAUDE.md or CLAUDE.local.md in your folder or above it | AGENTS.md |
| AGENTS.md and a CLAUDE.md (or CLAUDE.local.md) in your folder or above it | CLAUDE.md only |
A CLAUDE.md that imports @AGENTS.md | Both, through the import |
A file in .claude/rules/ that imports AGENTS.md | AGENTS.md through the import, in every case |
You can change that in /config, under Project instructions:
claude-md-or-agents-md: the default above.claude-md-and-agents-md: both, with each folder's CLAUDE.md first. It never reads the same AGENTS.md twice.claude-md: CLAUDE.md only.managed-only: only your organization's managed CLAUDE.md and auto memory at launch.
Claude Code never reads AGENTS.local.md, AGENTS.override.md, or anything under .agents/.
Two traps worth knowing:
CLAUDE.local.mdcounts as a CLAUDE.md. Add one for your private notes in an AGENTS.md-only repo, and Claude stops reading AGENTS.md for you. The fix isclaude-md-and-agents-md.- So does a CLAUDE.md in any parent folder, even outside the repo.
bun initcan write one. We measured it on Claude Code 2.1.285: one CLAUDE.md in a parent folder, and the repo's AGENTS.md stopped loading.
Option 1: one AGENTS.md, imported by Claude Code
Best when several agents touch the repo and they all need the same instructions. There are two places to put the import.
In a root CLAUDE.md. This is the pattern from Anthropic's docs:
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.
Claude reads the imported AGENTS.md first, then the Claude-only lines below it. Keeping the import never makes Claude read AGENTS.md twice, whatever the setting. It also works in sessions that can't read AGENTS.md directly. Two costs:
- Other agents read a root CLAUDE.md too. Cursor loads it as an always-on rule. Copilot CLI expands the import, so it sees AGENTS.md twice.
- The CLAUDE.md switches off Claude's own AGENTS.md loading, nested files included. Claude gets the root file through the import and nothing below it.
In a rule file. This is what generated repos do. No root CLAUDE.md. One file in .claude/rules/ imports AGENTS.md, and the Claude-only notes sit under the import:
@../../AGENTS.md
# Claude Code
- `AGENTS.md` at the repo root holds this repo's instructions. The line above imports it.
- Scoped rules load from `.claude/rules/` when you read a file they cover. The nested `AGENTS.md` files hold the same rules for other agents, so `.claude/settings.json` keeps Claude Code from loading them twice.
- Skills are in `.claude/skills/`: run one as `/name`. Subagents are in `.claude/agents/`.
- `.claude/settings.json` runs the guards in `.agents/hooks/` and turns on the Compound Engineering plugin once you trust this folder. If its commands are missing, run `/plugin install compound-engineering@compound-engineering-plugin`.
- Claude-only notes go in this file.
- MCP servers are in `.mcp.json`. Run `/mcp` to sign in to a remote one.
.claude/rules/agents-md.md, as generated.
A rule with no paths loads at launch, and the path resolves from the rule's own folder. We measured it: AGENTS.md loads once, in every version, even with a CLAUDE.md somewhere above the project.
Or skip the import and symlink: ln -s AGENTS.md CLAUDE.md. Two catches:
- Claude's Edit and Write tools refuse to write through a symlink. Claude gets pointed at AGENTS.md instead.
- On Windows, creating a symlink needs admin rights or Developer Mode. Git checks a committed symlink out as a plain text file unless
core.symlinksis on. That clone gets a one-line CLAUDE.md.
If anyone on the team uses Windows, use an import.
Option 2: generate every format from one source
Best when you want scoped rules in every agent, not one flat file.
An import shares one flat file. It can't give Claude Code paths: scoping, and it can't give Cursor globs. Generation can. Agentic Boilerplate writes each rule once and compiles it for each agent. Here's one rule, the Stripe webhook rule from the Indie SaaS preset, as each agent gets it. All of it comes from a real generate run.
Every agent: a nested AGENTS.md in the folder the rule covers. Codex, Cursor, Copilot, Antigravity and the rest read it.
# 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.
First 13 of 72 lines of src/app/api/webhooks/stripe/AGENTS.md.
Claude Code: a file in .claude/rules/ with paths:. .claude/settings.json lists every nested AGENTS.md under claudeMdExcludes, so Claude reads this rule once, not twice.
---
paths:
- src/app/api/webhooks/stripe/**
- src/lib/billing/provider.ts
- src/lib/billing/webhook.ts
---
# Verify every Stripe webhook, keep every handler idempotent
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.
First 12 of 71 lines of .claude/rules/stripe-webhook-integrity.md.
Cursor: an .mdc file, only where AGENTS.md ran out of room. The same rule also covers two files in src/lib/billing/. Codex reads at most 32 KiB per chain of AGENTS.md files, and the generator keeps every chain under 30 KiB. The chain down to src/lib/billing/ was full, so that folder's AGENTS.md links to .agents/rules/stripe-webhook-integrity.md instead of copying the text. Cursor gets a native rule for exactly those two files:
---
alwaysApply: false
description: Verify every Stripe webhook, keep every handler idempotent
globs: src/lib/billing/provider.ts,src/lib/billing/webhook.ts
---
# Verify every Stripe webhook, keep every handler idempotent
The webhook route is an unauthenticated public endpoint. The signature is the
First 9 of 70 lines of .cursor/rules/stripe-webhook-integrity.mdc.
Same text. Each agent gets the scoping it understands. Edit the rule once, regenerate, and every copy changes together. One known cost: Copilot reads .claude/rules/ too, so with Claude Code picked it sees a scoped rule twice. That costs tokens, not correctness.
The top-level files differ on purpose:
- AGENTS.md is the hub. The repo-wide rules in full, an index of the nested files, the skills and the subagents.
.claude/rules/agents-md.mdimports AGENTS.md and adds a few Claude-only notes.
See both: CLAUDE.md template and AGENTS.md examples.
Cursor rules vs AGENTS.md
Cursor reads both. They do different jobs.
| AGENTS.md | .cursor/rules/*.mdc | |
|---|---|---|
| Format | Plain markdown, no metadata | Markdown with description, globs and alwaysApply frontmatter |
| When it loads | Root always. Nested files for work in that folder | Always, by glob, when the agent decides it's relevant, or on @-mention |
| Read by other agents | Yes | No. Cursor only |
| Use it for | Rules every agent needs | Globs, manual rules, anything Cursor-only |
Three things to know. A rule in both places loads twice in Cursor, so pick one home per rule. A plain .md file inside .cursor/rules/ is ignored, because it has no frontmatter. And the old root .cursorrules file is legacy. The full format, with Next.js globs: Cursor rules for Next.js.
Best practices for running both
- One source of truth. Import it or generate it. Never two hand-edited copies.
- Agent-only lines go in that agent's file. Claude-only notes sit under the import.
- Check what loaded. In Claude Code,
/contextlists memory files and/memoryshows AGENTS.md too. In Codex, ask it to summarize its current instructions. - Keep hooks out of both. Instruction files can't enforce anything. The generated repo wires one set of guard scripts into 7 agents' own hook configs.
- Keep both short. Under 200 lines per CLAUDE.md. Under 32 KiB per Codex chain.
- Write checkable rules in both. "Read the webhook body with
request.text()" works in any tool. "Be careful with webhooks" works in none.
Common mistakes
- Both files, different content. Claude reads CLAUDE.md. Codex reads AGENTS.md. Your agents now follow different rules, and nobody notices until a review.
- "See AGENTS.md" written in words. Claude opens it only if it decides to. Use an
@import. - A CLAUDE.md in a parent folder. Claude Code stops reading the repo's AGENTS.md, nested files included.
- Adding CLAUDE.local.md to an AGENTS.md repo. Same effect. Claude stops reading AGENTS.md.
- A committed symlink on a team with Windows users. Someone ends up with a one-line CLAUDE.md.
- Expecting Codex to read CLAUDE.md. Not unless you add it to
project_doc_fallback_filenames, and even then only in folders without an AGENTS.md. - Assuming hooks travel with AGENTS.md. They don't. Each agent reads hooks from its own config file.
- Agent config in the shared file. Subagent tool lists and hook wiring don't belong in an instruction file. Each agent reads them from its own config. Keep Claude Code's in
.claude/.
Get all of them for a Next.js repo
If you're starting fresh, don't hand-write every format. Pick your agents at /build: all 10 are on by default. You get root and nested AGENTS.md, .claude/rules/ for Claude Code, .mdc files where Cursor needs them, and each agent's own hooks, subagents and MCP config, all compiled from the same 30 rules in the Indie SaaS preset. $99 once, with lifetime updates. What each agent gets: the agentic layer. Rules by battery: Better Auth, Stripe. The bugs those rules prevent: the cookbook.
More guides: Codex setup, GitHub Copilot setup, Gemini CLI and Antigravity, Claude Code setup for Next.js.
FAQ
Should I use CLAUDE.md or AGENTS.md?
Use AGENTS.md if more than one agent works in the repo, and have Claude Code import it: @AGENTS.md in a CLAUDE.md, or @../../AGENTS.md in a file in .claude/rules/. Use CLAUDE.md alone if your team only runs Claude Code and wants .claude/rules/ scoping.
Does Claude Code read AGENTS.md?
Yes, from v2.1.277, when there's no CLAUDE.md or CLAUDE.local.md in the working directory or any folder above it. Otherwise it reads CLAUDE.md only, unless something imports AGENTS.md or you set Project instructions to claude-md-and-agents-md.
Can I symlink CLAUDE.md to AGENTS.md?
Yes, with ln -s AGENTS.md CLAUDE.md. Skip it if anyone clones on Windows, where Git can check the link out as a one-line text file. An @AGENTS.md import has no such problem.
Does Codex read CLAUDE.md?
Not by default. Codex reads AGENTS.override.md or AGENTS.md in each folder, and reads other names only if you list them in project_doc_fallback_filenames.
Is AGENTS.md better than Cursor rules?
They do different jobs. AGENTS.md is plain markdown that many agents read. Cursor's .mdc rules add globs, descriptions and manual rules, but only Cursor uses them.
What about GEMINI.md?
Gemini CLI reads GEMINI.md by default. List AGENTS.md in context.fileName in .gemini/settings.json and the same file serves Gemini CLI too. Antigravity reads both names. More in Gemini CLI and Antigravity setup.
Can I use CLAUDE.md, AGENTS.md and Cursor rules in one repo?
Yes, but give each rule one home. Cursor reads a root CLAUDE.md, AGENTS.md and .mdc files, so a rule copied into all three loads more than once. Import one file into another, or generate every format from one source.
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.
- AGENTS.md examples, from a real Next.js repoWhat 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.
- 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.