CLAUDE.md vs AGENTS.md: what's actually different, and which one you need

Claude Code reads CLAUDE.md. It does not read AGENTS.md - not automatically, not as a fallback, not with a nudge in your prompt. If you already keep an AGENTS.md for other coding agents, Claude Code needs one line pointing at it. Which setup you actually want depends on how many different tools touch this repo, not on which file format wins the argument.

What CLAUDE.md and AGENTS.md actually are

CLAUDE.md is Claude Code's own memory format, with its own load hierarchy: managed policy files at the OS level, ~/.claude/CLAUDE.md for your personal preferences across every project, ./CLAUDE.md or ./.claude/CLAUDE.md for the team-shared project file, and a gitignored CLAUDE.local.md for your own machine-specific notes. All of them get read at the start of every session and concatenated into context together, broadest scope first.

AGENTS.md is a different thing wearing a similar shape: an open, tool-agnostic spec, described on its own site as "a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project" - a README written for agents instead of humans. It was never built around one product's session lifecycle; it was built so any agent that adopts the spec can read the same file without a vendor-specific format.

That difference in origin produces a real behavioral difference, not just a naming one. Claude Code's own docs are explicit that ancestor CLAUDE.md files don't override each other - "all discovered files are concatenated into context," root-first, working directory last. AGENTS.md's nested-file model works the opposite way: "the closest AGENTS.md to the edited file wins," so a subdirectory's file replaces the parent's rather than adding to it. If you're used to one system's nesting rules, assuming the other file works the same way will get your instructions silently ignored or silently duplicated.

Does Claude Code read AGENTS.md

No. I checked two independent sources rather than trust either alone, because a claim like "tool X doesn't support format Y" ages badly if you don't verify it fresh: Anthropic's own memory documentation, and the agents.md project's own list of tools that officially support its format.

Anthropic's docs state it in one sentence: "Claude Code reads CLAUDE.md, not AGENTS.md." Not a workaround, not a partial fallback - a flat no, with the fix immediately below it (the import or symlink covered next).

The agents.md project's adopter list is the second check, and it's a useful one precisely because it has every incentive to list Claude Code if it qualified - broader adoption is the entire point of an open-format project publishing a "who supports this" page. It doesn't appear. Codex, Cursor, Gemini CLI, GitHub Copilot's coding agent, and roughly 20 others do.

Which coding agents read which file

The practical read: if your repo is Claude Code only, CLAUDE.md alone covers it. The moment a second agent joins - Codex for a specific task, Cursor for another teammate, Copilot's coding agent in CI - AGENTS.md is the one file all of them share, and Claude Code is the one exception that needs its own pointer.

Making both files work in the same repo

Anthropic's docs name three ways to bridge the two, and the right one depends on whether you want Claude-specific instructions layered on top:

Import - add one line to CLAUDE.md:

@AGENTS.md

## Claude Code

Use plan mode for changes under src/billing/.

Claude loads the imported file first, then appends whatever you write below it. This is the one to use when Claude needs extra instructions the other agents don't.

Symlink - when you don't need anything Claude-specific:

ln -s AGENTS.md CLAUDE.md

One file on disk, two names pointing at it. No drift is possible because there's only one copy to edit. It doesn't work on Windows without Administrator rights or Developer Mode, where the @AGENTS.md import is the fallback.

The /import command - a one-time copy instead of a standing link, available from Claude Code v2.1.213 onward. It pulls a supported agent's configuration - AGENTS.md included - into the matching CLAUDE.md, and carries over more than just instructions: MCP servers, custom commands, subagents, and skills come with it. Use this when you're migrating off another agent's setup rather than maintaining both long-term.

This repo runs the import in production, not as a hypothetical: its root CLAUDE.md is a single line, @AGENTS.md, followed by product-specific sections underneath - the exact shape Anthropic's docs describe. AGENTS.md carries the framework gotchas (Next.js version quirks, the ESLint config format, the package manager) that any agent touching this codebase needs regardless of which one it is; CLAUDE.md adds the parts that are Claude-specific, like which build-plan doc to read first. One file to update when a command changes, read by every tool that opens this repo.

The recommendation matrix

| Who's touching this repo | Use | | --- | --- | | Claude Code only, solo | CLAUDE.md alone | | A non-Claude agent only (Codex, Cursor, etc.), solo or team | AGENTS.md alone | | Claude Code plus at least one other agent | AGENTS.md + a one-line @AGENTS.md import in CLAUDE.md | | Several different agents, no Claude Code | AGENTS.md alone - it's the one format all of them already read |

The pattern underneath every row: pick the file the widest set of your actual tools reads, and bridge in whatever's left with one line rather than a second maintained copy.

When you don't need either file

Neither file is free, and neither is enforced. Both load as a user message Claude (or whichever agent) reads and tries to follow - not a rule the client blocks against. If you need something that runs every time no matter what, no exceptions, that's a hook or a settings-level permission rule, not a CLAUDE.md line.

A handful of cases don't need a file at all:

• A single throwaway script or one-off experiment. There's no second session to carry instructions into, so writing them down first costs tokens for a session that never comes back to read them.
• A repo only one person ever touches, briefly. Auto memory - Claude Code's own separate system for notes it writes about your corrections - picks up real patterns after a session or two without you authoring anything, and costs nothing until it actually has something to say.
• Instructions that are actually mandatory, not preferences. "Never commit directly to main" belongs in a hook or branch protection, not a markdown file an agent can read and still get wrong under ambiguity.

None of that is an argument against the file when a repo genuinely has standing conventions worth stating once instead of re-explaining every session - it's a reason not to create one out of habit for a repo that doesn't have any yet.

FAQ

• Does Claude Code read AGENTS.md automatically? No. Confirmed directly in Anthropic's docs: "Claude Code reads CLAUDE.md, not AGENTS.md." You need an explicit @AGENTS.md import, a symlink, or the /import command to bridge them.
• Can I just symlink CLAUDE.md to AGENTS.md instead of importing it? Yes, with ln -s AGENTS.md CLAUDE.md, as long as you don't need any Claude-specific instructions on top. It fails on Windows without Administrator rights or Developer Mode; use the @AGENTS.md import there instead.
• Does importing AGENTS.md into CLAUDE.md cost extra tokens versus writing everything directly in CLAUDE.md? No more than the content would cost either way. An import is expanded and loaded in full at launch, same as if you'd pasted it directly - splitting files changes organization, not what loads.
• Which coding agents support AGENTS.md? Over 20 as of this writing, including Codex, Cursor, Gemini CLI, GitHub Copilot's coding agent, Aider, Zed, Windsurf, and Devin. Claude Code is a deliberate exception - it keeps its own CLAUDE.md format instead.
• What happens if CLAUDE.md and an imported AGENTS.md give conflicting instructions? They resolve the same way any two conflicting CLAUDE.md lines do: Claude may pick one arbitrarily, since neither is enforced configuration. Keep the imported file and whatever you add below it consistent rather than relying on load order to settle a contradiction.

Whichever file this repo ends up with, it's still context that loads and gets billed on every session regardless of which agent reads it. The free scan measures what your own CLAUDE.md (import included) actually costs, and the token counter breaks a pasted CLAUDE.md or AGENTS.md down section by section if you just want the number for one file. See CLAUDE.md best practices for what belongs in the file once you know which one you're keeping.

Made by Neo

UsageCut by ClockedCode - not affiliated with Anthropic. The figures on this page are measured on real Claude Code sessions and labeled measured or estimated where it matters.