← All reviews
Field guide · May 27, 2026 · 7 min read · Updated June 6, 2026

CLAUDE.md vs AGENTS.md — which one does Claude Code actually read?

If you’ve opened a popular repo lately, you’ve probably seen an AGENTS.md at the root where you expected a CLAUDE.md. In 2026 AGENTS.md went from “that file Codex wanted” to a genuine cross-vendor standard — stewarded by the Agentic AI Foundation under the Linux Foundation (formed December 2025, with OpenAI contributing AGENTS.md alongside Anthropic’s MCP), and used by over 60k open-source projects per the standard’s own count. The pitch is irresistible: write one file, every agent reads it, switching tools is a no-op.

So the question lands in every Claude Code team’s lap: do we throw out CLAUDE.md and standardize on AGENTS.md?

Short answer: not yet — and if you do it naively, Claude Code will silently read nothing. Here’s the actual state of play and the setup we recommend. (Updated June 6, 2026: Anthropic’s docs now address AGENTS.md head-on — quotes below are verbatim from the official memory docs.)

Quick answers

Does Claude Code read AGENTS.md? No. The official docs now say it in one sentence: “Claude Code reads CLAUDE.md, not AGENTS.md.” If your repo has only an AGENTS.md, Claude Code loads no project instructions at all — silently.

Does Claude Code recognize AGENTS.md at all? Indirectly, in two places: a CLAUDE.md can import it (@AGENTS.md), and running /init in a repo that already has an AGENTS.md reads it and incorporates the relevant parts into the generated CLAUDE.md (it also reads .cursorrules, .devin/rules/, and .windsurfrules).

How do I make Claude Code use my existing AGENTS.md? Create a one-line CLAUDE.md containing @AGENTS.md (officially recommended), or symlink it: ln -s AGENTS.md CLAUDE.md. On Windows, symlinks need Administrator privileges or Developer Mode — use the import.

AGENTS.md vs CLAUDE.md — which should be the source of truth? If more than one agent touches the repo: AGENTS.md is canonical and CLAUDE.md is a thin shim that imports it. If you’re Claude-only: just CLAUDE.md, and skip the ceremony.

What each file is

AGENTS.md is a vendor-neutral instructions file at the root of your repo: build commands, conventions, test rules, the constraints an agent can’t infer from the code. Its whole reason to exist is portability — Codex, Cursor, VS Code’s agent mode, Windsurf, Kilo and dozens more read it without translation.

CLAUDE.md is Claude Code’s native memory file. It predates the standard, it’s hierarchical (a project CLAUDE.md plus your personal ~/.claude/CLAUDE.md), and it supports @-imports of other files. It is not a synonym for AGENTS.md — it’s a different file that happens to do a similar job for one specific agent.

The catch nobody mentions

Here’s the part that bites teams who “standardized on AGENTS.md” over a weekend: as of June 2026, Claude Code does not read AGENTS.md natively. This used to be something you inferred from issue-tracker requests; it’s now stated verbatim in the official memory docs, which gained a dedicated AGENTS.md section: “Claude Code reads CLAUDE.md, not AGENTS.md. If your repository already uses AGENTS.md for other coding agents, create a CLAUDE.md that imports it so both tools read the same instructions without duplicating them.”

If your repository contains only an AGENTS.md, Claude Code loads zero project instructions — and you won’t get an error. You’ll just get worse output and wonder why. (We checked the full changelog through v2.1.167: no native AGENTS.md support has shipped; the long-watched request anthropics/claude-code#34235 remains open.)

How to run both without maintaining two files

The mistake is keeping two hand-edited files that drift apart within a week (see the CLAUDE.md problem in teams of 5+ for how fast that goes wrong). You want one source of truth and a thin bridge. Two ways:

Option A — import (recommended). Keep AGENTS.md as the shared file every tool reads, and make CLAUDE.md a short shim that pulls it in:

# CLAUDE.md
@AGENTS.md

# Claude-only notes (what differs from AGENTS.md)
- Use the ripgrep MCP server for search, not bash grep.

Claude Code expands the @AGENTS.md import at load time (“Claude loads the imported file at session start, then appends the rest”), so Claude reads the shared standard plus your handful of Claude-only lines. Every other tool reads AGENTS.md directly. One file to edit. This pattern is now the docs’ own first recommendation, which settles the “is this a hack?” question — it isn’t.

Option B — symlink. ln -s AGENTS.md CLAUDE.md. Dead simple, and Claude Code treats the linked file as its own. The trade-offs: you can’t add Claude-specific lines (it’s literally the same file), and the docs flag the platform catch directly — on Windows, creating a symlink requires Administrator privileges or Developer Mode, so use the @AGENTS.md import instead. Add the usual CI caveat (confirm git stored the link, not a copy) and it’s fine for a solo repo, shakier across a mixed team.

One more recent behavior worth knowing: /init now absorbs AGENTS.md. Run it in a repo that already has one and the generated CLAUDE.md incorporates the relevant parts — same for .cursorrules, .devin/rules/, and .windsurfrules. Handy for migrating; not a substitute for the import, since the absorbed copy won’t track future AGENTS.md edits.

Which wins when they disagree

With the import pattern the merge order is what you’d hope: the imported AGENTS.md is the baseline, the lines you write directly in CLAUDE.md layer on top, and your personal ~/.claude/CLAUDE.md layers on top of that for your own machine. So a Claude-specific override beats the shared standard, and your personal preferences beat both — for you, not your teammates.

That last distinction is exactly the one teams get wrong. Personal preferences in a shared file is mistake #3 in the five token-burning habits; promoting that shared file to AGENTS.md just spreads the mistake to every tool on the team.

The token math gets worse, not better

A bloated instructions file was already an invisible tax on every Claude session. Promote it to AGENTS.md and now it’s loaded by every agent on the team — Claude, Codex, Cursor, whatever — and paid for in every one of their sessions. The blast radius of a sloppy file multiplies by the number of tools you run.

The discipline doesn’t change, it just matters more: AGENTS.md should be tight, contrarian (only what a fresh model wouldn’t already do), and free of personal preferences. If it’s the file the whole stack reads, it’s the file most worth keeping lean. (If you’re starting one, our copy-paste AGENTS.md template is built around exactly this restraint.)

What we’d actually do

  • Solo, Claude Code only: just use CLAUDE.md. AGENTS.md buys you nothing until you add a second tool — don’t cargo-cult the standard.
  • One person, multiple agents: AGENTS.md as source of truth, CLAUDE.md as @AGENTS.md plus a few Claude-only lines. Personal prefs in ~/.claude/CLAUDE.md.
  • Team, multiple agents: same as above, plus one owner who edits AGENTS.md and a monthly read-through. What kills you isn’t the format — it’s two files drifting apart with nobody responsible for either.

The format war is mostly settled: AGENTS.md won the “shared baseline” slot — Cursor now reads it natively (nested subdirectory files included, per its rules docs), and Codex remains AGENTS.md-first and explicitly does not read CLAUDE.md. Claude Code hasn’t caught up natively, but it now documents the bridge officially. So the correct setup is unchanged and no longer improvised: AGENTS.md for the world, a thin CLAUDE.md shim for Claude. One file of truth, edited by one person, kept short.

Companion reading

Was this helpful?

Related reading

Reviews independently produced · Editorial policy

Read more reviews →