Skip to content

CLAUDE.md vs AGENTS.md: which one you need

CLAUDE.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.

Updated · 10 min read

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 usesUse
Claude Code onlyCLAUDE.md, plus .claude/rules/ for scoped rules
Codex onlyAGENTS.md, with nested files per folder
Cursor onlyAGENTS.md, root and nested. .cursor/rules/*.mdc when you need globs
GitHub Copilot onlyAGENTS.md, root and nested
A mixAGENTS.md as the one shared file, imported by Claude Code. Or generate every format from one source

Which agent reads which file

AgentInstruction files it reads
Claude CodeCLAUDE.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
CodexAGENTS.md, from the root down to the folder you work in. Other names only through project_doc_fallback_filenames
CursorAGENTS.md (root and nested), a root CLAUDE.md (always on), .cursor/rules/*.mdc
GitHub CopilotAGENTS.md (root and nested), CLAUDE.md, .github/copilot-instructions.md, .github/instructions/, .claude/rules/
AntigravityAGENTS.md and GEMINI.md (root and nested), .agents/rules/
Gemini CLIGEMINI.md. AGENTS.md once context.fileName in .gemini/settings.json lists it
OpenCodeAGENTS.md (nested files lazily), CLAUDE.md as a fallback
KiroRoot AGENTS.md (nested files load on every turn), .kiro/steering/
Windsurf (Devin Local)AGENTS.md and CLAUDE.md
JetBrains AIJunie reads AGENTS.md. AI Assistant chat needs a rule in .aiassistant/rules/ that points at it
ZedOne 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.md or AGENTS.md in each folder. It reads other names only if you list them in project_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 .cursorrules or .github/copilot-instructions.md wins over AGENTS.md. That's why generated repos ship none of those names.

CLAUDE.md vs AGENTS.md, side by side

CLAUDE.mdAGENTS.md
Read byClaude Code first. Cursor, Copilot and Windsurf read it tooCodex, Cursor, GitHub Copilot, Antigravity, Jules and many more. Claude Code when there's no CLAUDE.md
FormatMarkdown, any headingsMarkdown, any headings
Imports@path/to/file, up to four hops deepNone 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 fileCLAUDE.local.md, gitignoredNo equivalent in the spec
Nested filesLoad when Claude reads a file in that folderCodex: 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 guidanceUnder 200 lines per file32 KiB per chain in Codex, by default
Enforced?No. Context onlyNo. 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 hasClaude reads
AGENTS.md, and no CLAUDE.md or CLAUDE.local.md in your folder or above itAGENTS.md
AGENTS.md and a CLAUDE.md (or CLAUDE.local.md) in your folder or above itCLAUDE.md only
A CLAUDE.md that imports @AGENTS.mdBoth, through the import
A file in .claude/rules/ that imports AGENTS.mdAGENTS.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.md counts 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 is claude-md-and-agents-md.
  • So does a CLAUDE.md in any parent folder, even outside the repo. bun init can 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.symlinks is 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.md imports 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
FormatPlain markdown, no metadataMarkdown with description, globs and alwaysApply frontmatter
When it loadsRoot always. Nested files for work in that folderAlways, by glob, when the agent decides it's relevant, or on @-mention
Read by other agentsYesNo. Cursor only
Use it forRules every agent needsGlobs, 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, /context lists memory files and /memory shows 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.

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.