← All guides

CLAUDE.mdConfigurationSetup

CLAUDE.md vs AGENTS.md: Which One Should You Actually Use

By Neo Zino - builder of ClockedCode·Updated August 20, 2026·10 min read

CLAUDE.md vs AGENTS.md compared on what each format is, whether Claude Code reads AGENTS.md by default, and how to migrate without losing a rule.

Made with DispatchSEO

Claude Code reads CLAUDE.md. It does not read AGENTS.md on its own, and the two files come from different places entirely: one is Anthropic's own memory format, the other is an open spec now stewarded by the Linux Foundation and read natively by more than two dozen other agents. I pulled this straight from Claude Code's current official docs rather than the usual "just add both files and hope" advice - here's what each format actually does, whether you need one or both, and how to move between them without losing a single rule.

TL;DR: Claude Code reads CLAUDE.md exclusively - its own docs put it in one sentence: "Claude Code reads CLAUDE.md, not AGENTS.md." AGENTS.md is the open, vendor-neutral format backed by OpenAI, Google, Cursor, Sourcegraph, and others, read natively by 25+ agents. You don't have to pick one: create a CLAUDE.md whose first line is @AGENTS.md and Claude Code loads the shared file plus whatever Claude-specific rules you add underneath. Solo Claude Code users can skip AGENTS.md entirely; anyone whose repo also gets touched by Codex, Cursor, or another agent should keep AGENTS.md as the source of truth and bridge it in.

CLAUDE.md and AGENTS.md aren't rival specs

They read like competitors because they solve the same problem - giving a coding agent persistent, versioned project context instead of re-explaining your build commands every session - but they were built for different audiences. CLAUDE.md is Anthropic's own format: markdown files Claude Code loads at the start of every session, with four separate scope tiers (managed policy, user, project, and a gitignored local tier) so a company-wide security rule, your personal formatting preference, and a team convention can all live at the right altitude without colliding.

AGENTS.md, by its own description, is "a simple, open format for guiding coding agents" - "a README for agents." It wasn't built by one vendor trying to lock you in; per the spec site, it "emerged from collaborative efforts across the AI software development ecosystem, including OpenAI Codex, Amp, Jules from Google, Cursor, and Factory," and is now stewarded by the Agentic AI Foundation under the Linux Foundation. That's why the AGENTS.md compatible-tools list runs past 25 entries - Aider, Zed, VS Code, GitHub Copilot's coding agent, Devin, and more all read the same one file.

The practical split: CLAUDE.md gets you scope tiers and native Claude-specific hooks (skills, .claude/rules/, org-managed policy files) at the cost of being read by exactly one vendor's tool. AGENTS.md gets you one file every agent in your stack can read, at the cost of none of those per-tool extras.

Does Claude Code read AGENTS.md by default?

No. This is the exact wording from Claude Code's current memory documentation, in a section titled "AGENTS.md": "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." A repo with only an AGENTS.md and no CLAUDE.md gets zero project instructions loaded into a Claude Code session - not a partial read, not a fallback, nothing.

That asymmetry runs one direction. Codex, Cursor, Devin, GitHub Copilot's coding agent, and Amp all read AGENTS.md because it's the format they were built around; none of them read CLAUDE.md, because it isn't part of the spec they implement. Claude Code is the outlier on both sides - the only agent in this list with its own separate format, and the only one that needs an explicit bridge to read what everyone else already reads.

Running both files without duplicating rules

You don't have to choose. Claude Code's docs give two supported ways to bridge the files, and this site's own repository uses the first one: a CLAUDE.md whose entire first line is @AGENTS.md, with any Claude-specific instructions written below the import.

The @path import syntax works anywhere in a CLAUDE.md, not just line one - "See @README for project overview and @package.json for available npm commands" is the docs' own example - but putting the AGENTS.md import first means Claude Code loads the shared rules before anything Claude-specific, so project-wide conventions take priority and Claude-only additions read as refinements on top. If you don't need any Claude-specific instructions at all, a symlink does the same job with one command: ln -s AGENTS.md CLAUDE.md prints nothing on success (I ran it in an empty scratch directory to confirm - it does exactly what the docs say, and cat-ing the resulting CLAUDE.md returns the AGENTS.md content verbatim). Skip the symlink on Windows unless you're running as Administrator or have Developer Mode on; the import stays cross-platform.

Solo developer vs a team on three different agents

If Claude Code is the only agent that ever touches your repo, an AGENTS.md buys you nothing - write a plain CLAUDE.md and skip the import entirely. The four scope tiers, .claude/rules/ path-scoped instructions, and skills are all CLAUDE.md-native, and none of them have an AGENTS.md equivalent, so a Claude-only setup is strictly simpler without the bridge.

The moment a second agent enters the picture, that calculus flips. A team where one developer runs Claude Code and another runs Codex or Cursor on the same repo needs one shared file both agents actually read - and since Codex and Cursor only read AGENTS.md, that file has to be AGENTS.md, with CLAUDE.md importing it rather than the other way around. Writing the rules once in AGENTS.md and importing them into CLAUDE.md means a new build command or a changed convention only needs updating in one place; write it in CLAUDE.md alone and every agent except Claude Code just doesn't see it.

Migrating an existing AGENTS.md into Claude Code

Two paths cover this, both already shown above: import it or replace it. For most repos, importing is the safer default - it keeps AGENTS.md as the single edited file, which matters if teammates use other agents, and it lets you layer Claude-specific instructions (a ## Claude Code section for permission-mode guidance, for instance) without touching the shared file at all.

There's also a faster one-time path if you'd rather start from a generated CLAUDE.md than a bare import: /import (Claude Code v2.1.213 or later) reads a supported agent's configuration - AGENTS.md included - and appends a one-time copy of it into CLAUDE.md, carrying over MCP servers, commands, subagents, and skills in the same pass. And if you're running /init to bootstrap a CLAUDE.md from scratch, note that it doesn't read AGENTS.md by default; setting CLAUDE_CODE_NEW_INIT=1 first makes /init also pull in AGENTS.md, .devin/rules/, .windsurf/rules/ or .windsurfrules, and .clinerules, so a repo with several agents' rule files already in place gets them merged into one starting CLAUDE.md instead of written by hand.

When neither file format is enough

Both formats are context, not enforcement - Claude Code's own docs are explicit that CLAUDE.md instructions "shape Claude's behavior but are not a hard enforcement layer," and the same is true of AGENTS.md for every agent that reads it. If you need a rule that always fires regardless of what the model decides - blocking a command outright, running a linter before every commit - neither file is the right tool. Claude Code's hooks run as shell commands at fixed lifecycle events and enforce regardless of the model's judgment; that's the layer for anything you can't afford the agent to talk itself out of. And past roughly 200 lines, either file starts costing more context than it earns in adherence - split large instruction sets into path-scoped rules or skills rather than growing one file indefinitely.

FAQ

Does Claude Code read AGENTS.md?

No, not by default. Per Claude Code's own documentation: "Claude Code reads CLAUDE.md, not AGENTS.md." If a repository already has an AGENTS.md, Claude Code only sees it once you create a CLAUDE.md that imports it - either with a one-line @AGENTS.md import, or by symlinking CLAUDE.md to AGENTS.md so they're the same file on disk.

Can I use CLAUDE.md and AGENTS.md in the same repo?

Yes, and it's the setup this site's own repo uses. Create a CLAUDE.md whose first line is @AGENTS.md, then add any Claude-specific instructions below that import. Claude Code loads the imported AGENTS.md content at session start and appends whatever you wrote after it, so you maintain one file for the shared rules and a short second file for Claude-only additions.

Should I delete AGENTS.md and switch to only CLAUDE.md?

Only if Claude Code is the sole agent touching the repo. AGENTS.md is read natively by 25+ tools - Codex, Cursor, Devin, GitHub Copilot, and Amp among them - so deleting it in favor of a Claude-only file breaks every other agent's setup. If your team is Claude Code exclusively, a plain CLAUDE.md with no import is simpler; if anyone touches the repo with a different agent, keep AGENTS.md as the shared file and layer CLAUDE.md on top.

Do Codex, Cursor, or other agents read CLAUDE.md?

No. CLAUDE.md is Claude Code's own format and isn't part of the AGENTS.md spec's compatible-tools list. Codex, Cursor, Devin, GitHub Copilot's coding agent, and Amp all read AGENTS.md natively; none of them read CLAUDE.md. That asymmetry - one open format most agents share, one closed format only Claude Code reads - is the whole reason this comparison exists.

Does Claude Code's /init command pick up an existing AGENTS.md?

Only with a flag set. Running /init normally reads Cursor rules and GitHub Copilot instructions into the generated CLAUDE.md, but not AGENTS.md. Set CLAUDE_CODE_NEW_INIT=1 first, and /init also reads AGENTS.md, .devin/rules/, .windsurf/rules/, and .clinerules. Separately, the /import command (Claude Code v2.1.213+) appends a one-time copy of AGENTS.md into CLAUDE.md and carries over MCP servers, commands, subagents, and skills too.

Pick the file the way your team actually works

Whether you need AGENTS.md at all comes down to one thing: is Claude Code the only agent touching this repo, or not? Alone, skip the import and keep a plain CLAUDE.md; alongside Codex, Cursor, or anything else that only speaks the open spec, AGENTS.md becomes the file you actually maintain, with a one-line @AGENTS.md import making Claude Code fluent in it too. This site's own CLAUDE.md generator writes a plain project CLAUDE.md in about 30 seconds if you're starting from nothing, and the CLAUDE.md examples worth copying are equally valid content to put on either side of that import. If Codex is the other agent in your stack specifically, Codex vs Claude Code covers where the two tools actually diverge beyond just the config file.