← All reviews
Field guide · May 27, 2026 · 7 min read · Updated September 26, 2026

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

Update — September 26, 2026: Claude Code now reads AGENTS.md on its own — as a fallback. Since v2.1.277 (September 18), a project with an AGENTS.md and no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above gets its AGENTS.md loaded automatically. With both files present, only CLAUDE.md loads. The quick answers below are updated. The one-line @AGENTS.md import this page recommends is still the setup that loads everywhere — we tested 30 setups, including five ordinary ones that leave AGENTS.md unread.

Update — August 26, 2026: Anthropic closed the request, and Shopify’s CEO noticed. On August 17 Anthropic closed issue #6235 — the most-upvoted issue in the Claude Code repo, open 361 days with 5,026 thumbs-up — as completed, pointing at the same bridge this page recommends rather than shipping native support. Eight days later Tobi Lütke posted that he was thinking about banning Claude Code at Shopify over it. Everything below still stands; we also tested every bridge Anthropic documents and found one hole worth knowing about on Windows.

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: standardize on AGENTS.md, but keep a one-line CLAUDE.md that imports it. Claude Code 2.1.277 and later read a bare AGENTS.md on their own, but only when no CLAUDE.md-type file exists in the working directory or above — and older versions, including the stable release channel on September 26, read nothing from it. Here’s the actual state of play and the setup we recommend.

Quick answers

Does Claude Code read AGENTS.md? Yes, since v2.1.277 (September 18, 2026) — as a fallback, not a merge. It reads AGENTS.md only when there’s no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any folder above it; if there is one, it reads that instead. Earlier versions don’t read AGENTS.md at all. Five ordinary setups leave it unread without a warning.

Does Claude Code recognize AGENTS.md at all? Yes. Besides the native fallback, a CLAUDE.md can import it (@AGENTS.md), and running /init with CLAUDE_CODE_NEW_INIT=1 set reads an existing AGENTS.md and incorporates the relevant parts into the generated CLAUDE.md (by default /init reads Cursor and Copilot rules instead).

How do I make Claude Code use my existing AGENTS.md? On v2.1.277 or later, with no CLAUDE.md anywhere on the path, you don’t have to do anything. To make it load on every version and in every setup, create a one-line CLAUDE.md containing @AGENTS.md, 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. Until September 2026, Claude Code didn’t read AGENTS.md at all — the official memory docs said so in one line: “Claude Code reads CLAUDE.md, not AGENTS.md.” Version 2.1.277 (September 18) changed that, but only as a fallback: Claude Code reads AGENTS.md when there’s no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any folder above it. Add any of those — a teammate’s personal CLAUDE.local.md, a CLAUDE.md at a monorepo root — and AGENTS.md quietly stops loading.

You won’t get an error either way. You’ll just get worse output and wonder why. Versions before 2.1.277 — including the stable release channel on September 26 — still load nothing from a bare AGENTS.md. We tested 30 setups on the current release to map exactly when it loads.

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 reads the imported file first, then 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. Anthropic still documents this pattern for exactly the cases where native reading doesn’t apply, which settles the “is this a hack?” question — it isn’t. It also never loads AGENTS.md twice, whichever setting you use.

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 behavior worth knowing: /init can absorb AGENTS.md. With CLAUDE_CODE_NEW_INIT=1 set, running it in a repo that already has one incorporates the relevant parts into the generated CLAUDE.md — same for .devin/rules/, .windsurfrules and .clinerules; by default it reads Cursor and Copilot rules. 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 now reads it natively too, but only as a fallback — so the correct setup is unchanged: 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 →