CLAUDE.md vs AGENTS.md in 2026 — 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 — now stewarded by the Linux Foundation, adopted by 30+ tools, sitting in 60,000+ repositories. 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.

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 mid-2026, Claude Code does not read AGENTS.md natively. It reads CLAUDE.md. 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.

This isn’t hypothetical. “Support AGENTS.md as a native context file” is one of the most-watched open requests on the Claude Code issue tracker (anthropics/claude-code#34235). Until it ships, “AGENTS.md only” means “Claude Code flies blind.”

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, so Claude reads the shared standard plus your handful of Claude-only lines. Every other tool reads AGENTS.md directly. One file to edit.

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), some Windows checkouts and CI runners don’t preserve symlinks, and you have to confirm git stored the link rather than a copy. Fine for a solo repo, shakier across a mixed team.

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.

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. But Claude Code hasn’t caught up to it natively, so for now the correct setup is AGENTS.md for the world and a thin CLAUDE.md shim for Claude. One file of truth, edited by one person, kept short.

If your instructions files have already sprawled across two or three tools and nobody’s sure which one Claude is actually reading, that’s the knot the CLAUDE.md audit untangles — $299 solo, $799 for a team of 2–10.

Companion reading

How to write a great CLAUDE.md — file craftsmanship, whichever name it lives under.
The CLAUDE.md problem in teams of 5+ — what happens when two files drift across a team.
Five habits in your CLAUDE.md that are quietly burning tokens — the same discipline, now multiplied across every tool that reads AGENTS.md.
What AI coding agents write to your disk — where all these files actually live.