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

Same job, different readers. CLAUDE.md is Claude Code's instruction file. AGENTS.md is an open format that Codex, Cursor and 20+ other tools read. Claude Code reads AGENTS.md too, but by default only when there's no CLAUDE.md. 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	.cursor/rules/*.mdc for scoped rules, AGENTS.md for the basics
A mix	AGENTS.md as the shared file, and a CLAUDE.md that imports it with @AGENTS.md. Or generate every format from one source

Which tool reads which file

	CLAUDE.md	AGENTS.md	.claude/rules/	.cursor/rules/
Claude Code	Yes	When there's no CLAUDE.md, or through @AGENTS.md	Yes	No. /init reads them when it writes a CLAUDE.md
Codex	Only as a fallback name you configure	Yes	No	No
Cursor	Not in its rules docs	Yes, root and nested	Not in its rules docs	Yes

Two cells in that table catch people out.

• Claude Code plus both files. 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.

CLAUDE.md vs AGENTS.md, side by side

	CLAUDE.md	AGENTS.md
Read by	Claude Code	Codex, Cursor, Jules, Copilot's coding agent and many more. Claude Code as a fallback
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: combined with parents
Scoped rules	.claude/rules/*.md with paths:	Folder placement is the only scope
Size guidance	Under 200 lines per file	32 KiB combined 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. In Claude Code, that's a hook's job. See the hooks guide.

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	AGENTS.md
AGENTS.md and a CLAUDE.md (or CLAUDE.local.md)	CLAUDE.md only
A CLAUDE.md that imports @AGENTS.md	Both, through the import

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

One trap 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.

Option 1: one AGENTS.md, imported by CLAUDE.md

Best when several agents touch the repo and they all need the same instructions.

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

That's the pattern from Anthropic's own docs. 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.

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 the import.

Option 2: generate every format from one source

Best when you want scoped rules in every tool, 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 in a neutral format and compiles it per target. Here's one rule, the Stripe webhook rule from the Indie SaaS preset, in all three formats. All three come from a real generate run.

Claude Code: a file in .claude/rules/ with paths: frontmatter.

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

Codex: a nested AGENTS.md in the folder the rule covers.

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

Cursor: an .mdc file in .cursor/rules/ with globs.

---
alwaysApply: false
description: Verify every Stripe webhook, keep every handler idempotent
globs: src/app/api/webhooks/stripe/**,src/lib/billing/provider.ts,src/lib/billing/webhook.ts
---

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 9 of 68 lines of .cursor/rules/stripe-webhook-integrity.mdc.

Same text. Three loading mechanisms. Each tool gets the scoping it understands. Edit the rule once, regenerate, and all three change together.

The top-level files differ on purpose:

• CLAUDE.md is an index of Claude Code features: rules, skills, subagents, hooks and MCP servers, each one linked.
• AGENTS.md puts the repo-wide rules in full, then tells Codex to read every nested AGENTS.md on the path before it edits a file. It also warns that the guard hooks in .claude/hooks/ don't run under Codex.

See both in full: 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
Used as rules by other agents	Yes	No. Cursor only
Use it for	Basics every agent needs	Scoped rules, procedures and anything Cursor-specific

Two things to know. 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.
• Tool-specific lines go in the tool's file. Claude-only notes sit below @AGENTS.md in CLAUDE.md.
• 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.
• Say what isn't shared. Claude Code hooks live in .claude/settings.json. If Codex doesn't run them, write that in AGENTS.md.
• Keep both short. Under 200 lines per CLAUDE.md. Under 32 KiB combined for Codex.
• 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 @AGENTS.md.
• Adding CLAUDE.local.md to an AGENTS.md repo. 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 the guards run everywhere. A hook wired for Claude Code does nothing in Codex. The generated AGENTS.md says so near the top.
• Claude-only features in the shared file. Subagents and hook setup mean nothing to Codex or Cursor. Keep them in .claude/.

Get all of them for a Next.js repo

If you're starting fresh, don't hand-write three formats. Pick Claude Code, Codex and Cursor as targets at /build. You get CLAUDE.md, root and nested AGENTS.md, and .cursor/rules/, all compiled from the same 30 rules in the Indie SaaS preset. Free during launch, then $99 once. What each target gets: the agentic layer. Rules by battery: Better Auth, Stripe. The bugs those rules prevent: the cookbook.

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

More guides: Claude Code skills, Claude Code subagents, 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 add a CLAUDE.md that imports it with @AGENTS.md for Claude Code. 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 above it. Otherwise it reads CLAUDE.md only, unless your CLAUDE.md 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.

Can I use CLAUDE.md, AGENTS.md and Cursor rules in one repo?

Yes. Each tool reads its own files, so they coexist. The risk is drift, so import one into another or generate all three from one source.