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

> CLAUDE.md is for Claude Code. AGENTS.md is the shared file Codex, Cursor and others read. Which tool reads what, and how to run both without them drifting.

*Updated 2026-10-04.*

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](/guides/claude-code-hooks).

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

```markdown
@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](/stack/indie-saas), in all three formats. All three come from a real generate run.

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

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

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

```markdown
---
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](/guides/claude-md-template) and [AGENTS.md examples](/guides/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](/guides/cursor-rules-nextjs).

## 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](/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](/docs/the-agentic-layer). Rules by battery: [Better Auth](/with/better-auth), [Stripe](/with/stripe). The bugs those rules prevent: [the cookbook](/cookbook).

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

More guides: [Claude Code skills](/guides/claude-code-skills), [Claude Code subagents](/guides/claude-code-subagents), [Claude Code setup for Next.js](/guides/claude-code-setup-nextjs).

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


## Sources

- [Claude Code docs: AGENTS.md](https://code.claude.com/docs/en/memory#agents-md)
- [Codex docs: Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md)
- [Cursor docs: Rules](https://cursor.com/docs/context/rules)
- [AGENTS.md: the open format](https://agents.md)

## Generate it

[Build your repo](https://agenticboilerplate.com/build)

---

Agentic Boilerplate: A Next.js repo your agent already knows. Free during launch, then $99 once.

- Site map for agents: https://agenticboilerplate.com/llms.txt
- Public API: https://agenticboilerplate.com/openapi.json
- Contact: agenticstudio@gmail.com