CLAUDE.md vs AGENTS.md: Which Files Claude Code, Codex & Cursor Actually Read (2026)

Short answer: put your shared project rules in AGENTS.md. Give Claude Code a thin CLAUDE.md that starts with @AGENTS.md plus any Claude-only notes. Codex and Cursor already read AGENTS.md natively (see how Claude Code, Codex and Cursor compare). Claude Code (v2.1.277+) only falls back to AGENTS.md when no CLAUDE.md / .claude/CLAUDE.md / CLAUDE.local.md exists on the path, unless you change Project instructions in /config.

Last updated: October 14, 2026. Checked against Claude Code’s official memory docs and the AGENTS.md open format site.

What each file is for

AGENTS.md is the open, cross-tool instruction file (now stewarded under the Linux Foundation’s Agentic AI Foundation). Treat it like a README for agents: build commands, test commands, conventions, and the pitfalls a new teammate would need.

CLAUDE.md is Claude Code’s native memory file. It supports @path imports (up to four hops), CLAUDE.local.md for private notes, and .claude/rules/ for path-scoped rules. Anthropic still recommends keeping each CLAUDE.md under about 200 lines.

They are not rivals. The messy part is which tool loads which file by default, and that map changed in September 2026 when Claude Code started reading AGENTS.md.

What reads what (as of October 2026)

Tool	Native file	Reads AGENTS.md?	Reads CLAUDE.md?	Notes that bite people
Claude Code	CLAUDE.md / .claude/CLAUDE.md	Yes, but only as a fallback by default (v2.1.277+)	Always	If any project CLAUDE.md or CLAUDE.local.md exists on the path, default mode ignores AGENTS.md unless Project instructions = claude-md-and-agents-md
OpenAI Codex	AGENTS.md (+ AGENTS.override.md)	Always	Only if you add it to project_doc_fallback_filenames	Walks root → cwd; closer file wins; combined instructions have a hard size cap (~32 KiB)
Cursor	.cursor/rules/*.mdc + AGENTS.md	Yes (root and nested)	CLI may load root CLAUDE.md; IDE rules are still .mdc	Nested AGENTS.md applies by directory; Team > Project > User when rules conflict
GitHub Copilot coding agent	.github/copilot-instructions.md	Yes	Yes	Can load several instruction files at once, so conflicting CLAUDE.md + AGENTS.md content is a real risk
OpenCode	AGENTS.md	Preferentially	Fallback when no AGENTS.md	Good default for the shared-file plan
Gemini CLI	GEMINI.md	If you set context.fileName	Only if configured	Not automatic
Aider	none by default	With read: AGENTS.md in config	Only what you pass	Explicit is safer

Claude-specific gotchas from the official docs:

1. Your personal ~/.claude/CLAUDE.md does not block AGENTS.md. A project CLAUDE.local.md does.
2. Claude never reads AGENTS.local.md, AGENTS.override.md, or .agents/ through the Project instructions path.
3. Some sessions (older versions, disabled agents-md plugin, first session after an upgrade) still cannot load AGENTS.md directly. The @AGENTS.md import in a CLAUDE.md is the reliable bridge.

Load order inside Claude Code

When Claude Code loads CLAUDE.md files, it concatenates them from the filesystem root down to your working directory. Closer instructions are read last. CLAUDE.local.md is appended after CLAUDE.md in the same directory. Subfolder CLAUDE.md files load on demand when Claude touches files there.

For AGENTS.md in the default claude-md-or-agents-md mode:

• At launch: every AGENTS.md / .claude/AGENTS.md from cwd upward, only if no project CLAUDE.md / CLAUDE.local.md counts on that path.
• In subdirectories: a nested AGENTS.md can load when Claude opens a file there and that subdirectory has none of the three CLAUDE.md filenames.

If instructions seem “ignored,” run /context and look under Memory files, or run /memory. Missing from that list means Claude never saw the file.

The one setup that works across tools

Use one shared source of truth, then give each tool the smallest native shim it needs.

your-repo/
├── AGENTS.md              # shared rules (commit this)
├── CLAUDE.md              # @AGENTS.md + Claude-only notes (commit this)
├── CLAUDE.local.md        # optional, gitignored personal notes
├── .cursor/rules/         # optional Cursor-only scoped rules
└── .github/
    └── copilot-instructions.md   # optional Copilot-only notes

1. Put the real content in AGENTS.md

# <ProductName> — agent instructions

## Snapshot
<One sentence product + stack.>
Out of scope: <teams, i18n, mobile, …>.

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Typecheck / lint / test: `pnpm typecheck && pnpm lint && pnpm test`
- DB: `supabase db reset` locally; never edit a committed migration

## Hard rules
- Supabase service-role key: server-only. Never in `NEXT_PUBLIC_*`.
- Stripe prices and plan IDs: look up server-side, never trust the browser.
- Auth checks: verified user on the server, not client-only session reads.

## Definition of done
1. Typecheck, lint and tests pass (show the output).
2. No new secrets in client bundles.
3. Summarize what changed and what you verified.

Keep it short. Codex in particular will stop reading after a hard combined size limit, so a 2,000-line AGENTS.md is actively harmful.

2. Make Claude Code import it

@AGENTS.md

## Claude Code only
- Prefer plan mode for anything under `src/billing/` or `supabase/migrations/`.
- Use `/compact` before long refactors; keep CLAUDE.md under ~200 lines including imports' cost.
- Path-scoped details live in `.claude/rules/`, not here.

Why this instead of “AGENTS.md only”? Because many Claude sessions still cannot load AGENTS.md directly, and a project that already has CLAUDE.md will skip AGENTS.md under the default setting. The @ import works in both worlds and never double-loads the same file when you set Project instructions to claude-md-and-agents-md.

3. Optional: read both files always

In Claude Code, open /config and set Project instructions to claude-md-and-agents-md. Or put this in ~/.claude/settings.json (user/managed settings; project/local settings ignore it):

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

On Claude Code before v2.1.285 the plugin id was agents-md@builtin. Current versions accept either id.

4. Avoid the Windows symlink trap

ln -s AGENTS.md CLAUDE.md looks elegant and fails on many Windows clones (symlink privileges, core.symlinks). Prefer the @AGENTS.md import.

Migrating an existing repo (copy-paste)

Run this once from the repo root:

# 1) If you only have CLAUDE.md today, promote the shared parts
cp CLAUDE.md AGENTS.md

# 2) Replace CLAUDE.md with an import + Claude-only notes
cat > CLAUDE.md <<'EOF'
@AGENTS.md

## Claude Code only
- Plan first for auth, billing and migrations.
EOF

# 3) Keep personal notes out of git
echo 'CLAUDE.local.md' >> .gitignore
touch CLAUDE.local.md

# 4) Verify in Claude Code
#    /context  → Memory files should list CLAUDE.md (and AGENTS.md if mode loads it)
#    /memory   → open both files and skim for contradictions

Migration checklist:

1. Move shared commands, hard rules and definition-of-done into AGENTS.md.
2. Leave Claude-only items (@ imports of local docs, plan-mode preferences, .claude/rules pointers) in CLAUDE.md.
3. Delete duplicate paragraphs. Conflicting lines make agents pick arbitrarily.
4. If you use Codex overrides, remember Claude does not read AGENTS.override.md.
5. Ask Cursor/Copilot users on the team whether .cursor/rules or copilot-instructions.md still need tool-specific extras.

Common mistakes

Two sources of truth that disagree. CLAUDE.md says “pnpm only” and AGENTS.md still says npm install. Codex and Claude will behave differently and you will blame the model.

**A gitignored CLAUDE.local.md that silently disables AGENTS.md.** Under the default Project instructions mode, that local file counts as a CLAUDE.md and Claude stops reading AGENTS.md. Fix: import with @AGENTS.md, or set claude-md-and-agents-md.

Giant instruction files. Claude adherence drops past ~200 lines. Codex has a hard combined cap. Put rare procedures in skills or path-scoped rules, not in the always-on file.

Prompt text instead of an import. “Please read AGENTS.md” in CLAUDE.md only works if Claude decides to open the file. @AGENTS.md always expands at launch.

Assuming Windsurf/Devin Desktop, Gemini CLI or Aider match Cursor. Check the table. Several tools need an explicit config key before they touch AGENTS.md.

FAQ

Do I still need CLAUDE.md if Claude Code can read AGENTS.md now? Yes, if you want Claude-specific behavior, @ imports, local notes, or reliability in sessions that cannot load AGENTS.md. For a brand-new repo with zero Claude-only needs, AGENTS.md alone can work on Claude Code v2.1.277+ in default mode.

Will Claude read both files and double my context? Not if you only import once. With claude-md-and-agents-md, Claude skips an AGENTS.md it already loaded through an import or symlink. If context is still bloated, see how to cut Claude Code token usage.

Where should monorepo package rules go? Nested AGENTS.md / CLAUDE.md next to the package. Claude loads subdirectory files on demand; Codex walks root → cwd; Cursor applies nested AGENTS.md by directory. Keep the root file global and short.

How do I confirm a change worked? In Claude Code: /context (Memory files) and a one-line probe like “What is the install command for this repo?” In Codex/Cursor: start a fresh agent turn and ask the same question after editing the file.

Further reading

• CLAUDE.md templates for Next.js, Supabase and Stripe
• Full indie AI workflow hub
• 15 ways to reduce Claude Code token usage
• Official Claude Code memory docs: https://code.claude.com/docs/en/memory
• AGENTS.md format: https://agents.md/