CLAUDE.md vs AGENTS.md: When to Use Each (And Why You Need Both)

A developer searches CLAUDE.md vs AGENTS.md, expecting a verdict. Pick one. Most pages on the topic oblige with a comparison. The setup is wrong: both files load at session start when both exist, and the agents.md spec says so explicitly. The right question is which rule lives in which file, and what happens when the two files disagree.

This article exists because the search query is mis-framed. The answer is layering. Once you know how the layering works, the operational question becomes simple: an instruction belongs in AGENTS.md if Cursor or Codex would need to read it, and in CLAUDE.md if it changes Claude Code's behavior in a way the other agents would ignore. Everything below operationalizes that test.

For the deeper file mechanics on either side, see our companion explainers on AGENTS.md and CLAUDE.md. For the full taxonomy with SKILL.md included, see our existing piece on SKILL.md vs AGENTS.md vs CLAUDE.md. This piece focuses on the layering decision specifically.

Why the comparison is the wrong question

The phrase vs implies an either-or. The agents.md spec implies a stack. The spec is the authority on this question, and the spec says: "The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything". That sentence describes a precedence chain, which is a thing that exists only when more than one file is in play. The framing of vs presupposes a choice the spec leaves to your operating model.

The Anthropic-recommended interop pattern reinforces the layering view. Claude Code's memory documentation describes the canonical setup as a one-line @AGENTS.md import at the top of CLAUDE.md, with Claude-specific instructions below the import. The two files are designed to load together as one coherent prompt. The mechanics of the import are covered in the CLAUDE.md sibling explainer; this piece treats the import as the operating assumption.

For a GitHub Copilot user, the framing collapses for a different reason. As of GitHub's 2025-08-28 changelog, Copilot's coding agent reads AGENTS.md, CLAUDE.md, copilot-instructions.md, and GEMINI.md, all of them. Copilot users get both files for free. Both files load.

The real question, the one the search intent is reaching for, is which rule belongs in which file. That question has an operational answer.

The precedence rule, spelled out

Three precedence layers run at the same time when both files exist on a multi-agent repo. The agents.md spec covers the cross-tool layer; Codex's docs spell out the in-AGENTS.md chain in the most detail of any vendor; Claude Code applies its own four-scope hierarchy on top.

The agents.md cross-tool rule is the one to lead with: the closest AGENTS.md to the edited file wins for any agent reading it, and an explicit chat prompt overrides everything. That rule applies the same way to Codex, Cursor, Copilot, and the other supporting agents listed at agents.md.

The Codex chain is the most documented worked example. Codex builds an instruction chain when it starts. Discovery follows three steps: a global file in ~/.codex/AGENTS.md (or its AGENTS.override.md companion); a project chain that walks from the Git root down to the current working directory, picking at most one file per directory; and a merge step that concatenates from the root down. Files closer to the working directory appear later in the combined prompt and override earlier guidance. Codex stops adding files once the chain reaches project_doc_max_bytes (32 KiB by default).

The Claude Code overlay runs on top. Claude Code walks up the directory tree from the working directory, gathering every CLAUDE.md and CLAUDE.local.md along the way, with the most local file appearing last in the combined prompt. The four-scope hierarchy (managed policy, project, user, local) is covered in the CLAUDE.md sibling explainer.

The shared mechanic across all three layers: every level concatenates, and recency wins. An LLM biases toward instructions at the prompt periphery, so the rule that loads last carries more weight on the next turn.

Vendor support map (May 2026)

Who reads which file natively. Verify before each refresh; vendor support shifts.

The practical read: Claude Code is the only widely used agent that treats CLAUDE.md as primary and reads AGENTS.md only through an explicit import. For every other supporting agent, AGENTS.md is the file. The fresh fact worth flagging is the Copilot 2025-08-28 changelog, which puts Copilot in the same camp as Claude Code on CLAUDE.md adoption: both files load.

The layering rule in one sentence

Apply the test to a few common cases:

• Build commands, test commands, package manager. Every agent runs them. AGENTS.md.
• Coding standards, naming conventions. Every agent applies them when generating code. AGENTS.md.
• Plan mode preference, sub-agent delegation, Claude permission overrides, slash command behavior. Claude-specific. CLAUDE.md.
• Sandbox URLs, personal env vars, individual tooling shortcuts. Personal-overrides file. CLAUDE.local.md (gitignored) for Claude Code; tool-specific personal config for the others.
• Secrets. Out of both files. Use a secrets manager.

A pair of worked examples shows the layering pattern in practice. Same project, two files, with content split cleanly between them.

# AGENTS.md

## Setup commands
- Install deps: `pnpm install`
- Run tests: `pnpm test`
- Run lint: `pnpm lint`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing

@AGENTS.md

## Claude Code

- Use plan mode for changes under `src/billing/`
- Skip the deep-thinking budget for changes under `src/marketing/`
- When invoking the deploy skill, prefer the staging-first variant

The @AGENTS.md line at the top of CLAUDE.md pulls the cross-platform layer in at session start; the four lines below it carry only the rules that change Claude Code's behavior. Cursor and Codex read the same AGENTS.md directly; Copilot reads both since the 2025-08-28 changelog. One source of truth for the cross-platform rules; one thin overlay for the Claude-specific rules. Drift gets removed because the cross-platform rules live in one place.

Common mistakes when running both

Four failure modes show up across multi-agent repos.

• Duplicating cross-platform rules across both files. A copy of AGENTS.md survives in CLAUDE.md because someone wanted Claude to keep working when AGENTS.md got renamed. Drift sets in the moment one file is edited alone. The fix is the @AGENTS.md import: one source of truth, one overlay.
• Putting Claude-only flags in AGENTS.md. Plan-mode preferences and sub-agent delegation rules end up in the cross-platform file. Codex and Cursor read them and behave in ways their authors missed at write time. The fix: any rule that uses Claude Code-specific syntax or names a Claude Code feature belongs in CLAUDE.md.
• Putting cross-agent rules only in CLAUDE.md. Build commands, code style, naming conventions sit in CLAUDE.md. Claude Code follows them. Cursor and Codex skip them because they overlook CLAUDE.md entirely. The team notices when the agents disagree on output style. The fix: lift cross-agent rules into AGENTS.md and import them.
• Auto-generating both files via /init and shipping as written. Generated files prioritize comprehensiveness over restraint and grow into a ball-of-mud over time. Hand-write both. Keep each file under the size where the agent stops following the rules (Anthropic targets under 200 lines for CLAUDE.md; Codex enforces a 32 KiB cap on the combined AGENTS.md chain).

The pattern across all four mistakes: the failure is silent. The agent does something subtly off, the team writes it off as model drift, and the rule that caused it sits unread in a file the team has stopped editing.

When one file is enough

Three shapes of repo. Each has a different answer.

CLAUDE.md only is fine if the project is genuinely solo and stays that way. The day a second agent enters the repo, restructure to AGENTS.md + thin CLAUDE.md overlay.

AGENTS.md only is the right starting point for any multi-agent team. Add tool-specific overlays only where a feature requires them.

The third shape, two or more agents on the same repo with at least one of them being Claude Code, is the case the rest of this article is written for. Both files, layered correctly, with the @AGENTS.md import as the bridge.

Migration path

Two migrations cover most repos.

From CLAUDE.md-only to layered. Audit the existing CLAUDE.md. Pull every rule that would still apply to Cursor or Codex into a new AGENTS.md at the repo root: build commands, test commands, code style, PR conventions, architectural constraints. Keep Claude-specific behavior in CLAUDE.md: plan mode, sub-agent delegation, slash command overrides, anything that names a Claude Code feature. Add @AGENTS.md as the first line of CLAUDE.md. Test by running the same task across two agents and comparing the outputs.

From AGENTS.md-only adding Claude Code. Create a thin CLAUDE.md with @AGENTS.md at the top and Claude-specific overlays below. The overlay file should sit at 20 to 50 lines if your AGENTS.md already covers the cross-platform contract. The HumanLayer reference target is under 60 lines for the root file.

The symlink workaround (ln -s AGENTS.md CLAUDE.md) still works and continues to be cited by practitioners. The @AGENTS.md import is the newer Anthropic-recommended pattern and preserves the ability to add Claude-specific rules below the import, which the symlink does at the cost of treating the two files as identical.

Does it even help?

A paper from ETH Zurich and LogicStar.ai ("Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?", arxiv 2602.11988) tested four agents (Claude Code on Sonnet 4.5, Codex on GPT-5.2 and GPT-5.1 Mini, Qwen Code on Qwen3-30B) across three conditions: no context file, LLM-generated, human-written. Headline result: LLM-generated files dropped success rates by ~3% on average; human-written files lifted them by ~4% on average, with the lift uneven across models (Sonnet 4.5 dropped by over 2%, Qwen3 benefited most).

The top-rated practitioner counter-take on the Hacker News thread (deaux, paraphrased): a 4% improvement from a hand-written markdown file is the entire point. A second practitioner (vidarh) pushed harder: the metric the paper measures (single-task success rate) misses the value most operators use these files for, which is to keep the agent out of the corrections the team has already made twice.

The operator read: write the file by hand. Keep it small. Treat it as the rules a new hire would read on day one. The file pays back across sessions, where a single benchmarked task underrates it. For the live AS coverage of the same paper's predecessor study, see SKILL.md vs AGENTS.md vs CLAUDE.md. For the visual map of where this layering decision sits in the broader agent-config landscape, see the Agent Skills Landscape infographic.

Pick the file by who reads it

If you are running Claude Code with any other coding agent on the same repo, you have probably already touched both files. Maybe you generated CLAUDE.md with /init and a teammate dropped an AGENTS.md next to it. Maybe Cursor read your AGENTS.md and Claude Code read your CLAUDE.md and you assumed they were doing the same thing. The two files are already in your workflow; the question is whether you have layered them on purpose.

The high-leverage move is the @AGENTS.md import line at the top of CLAUDE.md. One file with the cross-platform contract, one thin overlay with the Claude-specific rules. Cursor and Codex read the contract directly; Copilot reads both since 2025-08-28; Claude Code reads the overlay and pulls in the contract through the import. Duplication leaves the system; drift gets stripped out; every agent operates on the same source of truth.

The layering rule that decides where each new instruction goes is one sentence. If Cursor or Codex would need it to do its job, it belongs in AGENTS.md. If it changes Claude Code's behavior in a way the other agents would ignore, it belongs in CLAUDE.md. Apply the test before each new line. The repo with one tight AGENTS.md and a 30-line CLAUDE.md outperforms the repo with two 200-line files in conflict.

Two files. One contract. The layering rule decides the rest.