AGENTS.md vs CLAUDE.md: What Claude Code Reads

AGENTS.md is the cross-tool instruction file: 60,000+ open-source repos use it, it came out of a collaboration between OpenAI Codex, Amp, Google Jules, Cursor and Factory, and it's now stewarded by the Agentic AI Foundation under the Linux Foundation. Two dozen tools read it. Claude Code was the conspicuous holdout, and issue #6235 collected something like 5,200 reactions about it before Anthropic shipped support. Here's what you get:

The check is per-path, not per-repository.Claude walks from your working directory up through every parent. One CLAUDE.md three levels above your monorepo package, and the AGENTS.md sitting right next to the code you're editing never loads. That's the failure mode people describe as "it worked in the demo repo and not in mine."

This is the one worth the price of admission, and it's the reason your teammate's setup works and yours doesn't. Not every CLAUDE.md counts toward the check:

• Counts, and blocks AGENTS.md: a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any directory above it.
• Doesn't count, and keeps loading alongside AGENTS.md: your ~/.claude/CLAUDE.md, your organization's managed CLAUDE.md, and your .claude/rules/ files.

See the problem? CLAUDE.local.md is gitignored by design.It's the file you create for your own uncommitted preferences. So you join a repo that standardizes on AGENTS.md, drop three lines into a CLAUDE.local.md because you want Claude to use a different test command locally, and you have just switched off the team's shared instructions — for you, invisibly, in a file nobody else can see. Everyone else's Claude knows the conventions. Yours doesn't, and the diff reviews start going sideways.

The fix is the setting, not deleting your local file: set Project instructions to claude-md-and-agents-md and both load, CLAUDE.md files first, AGENTS.md after.

Type /config and find Project instructions. Four values:

• claude-md-or-agents-md— the default. CLAUDE.md files, or AGENTS.md when none of the three counting files exist at or above your working directory.
• claude-md-and-agents-md— both, per directory, CLAUDE.md first. Claude Code skips an AGENTS.md it already loaded, so an import or symlink won't give you two copies.
• claude-md— CLAUDE.md only. The pre-2.1.277 behavior.
• managed-only— only your organization's managed CLAUDE.md and auto memory at launch. Project, local and user CLAUDE.md files, .claude/rules/, and every AGENTS.md are left out.

You can set it in JSON instead, under the built-in plugin's ID:

// ~/.claude/settings.json
{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

Claude Code ignores this key in project and local settings files. It only reads it from ~/.claude/settings.json, a --settingsfile, or managed settings. So you cannot commit "read both files" to the repo and have it apply to your team — it's per-machine or per-organization. If you're standardizing across a company, managed settings is the lever.

In these sessions Claude reads CLAUDE.md files only, and Project instructions doesn't even appear in the /config panel— which is your tell:

• You're below v2.1.277. Check with claude --version.
• Your session can't fetch feature flags from Anthropic.Amazon Bedrock, Vertex, another third-party provider, or telemetry disabled. This catches a lot of enterprise setups, and it's the one nobody predicts.
• It's your first session after installing or upgrading. Claude reads AGENTS.md from your next session on. Restart before you file a bug.
• disableAllHooks or allowManagedHooksOnly is set, or you disabled the built-in agents-md plugin in /plugin. AGENTS.md support ships as a built-in Claude Code Mod, so the hooks kill switches reach it. If your security team turned off hooks org-wide, they turned this off too and nobody connected the two.

In every one of those cases the workaround is the same as it was before September: put an @AGENTS.md import in a CLAUDE.md. More on that below.

Here's where I lost my hour. An AGENTS.md read through the setting is not listed in /memory, and not listed under Memory files in /context. I checked /context, saw nothing, concluded the feature hadn't shipped to my build, and went off to write a symlink I didn't need. It had loaded fine the whole time.

Two ways to actually confirm it:

• At session start, look for a line like no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md in the conversation.
• Or just ask Claude what its project instructions say. Cheapest test there is, and it works in every session type.

Three more behavioral differences worth knowing before you rely on one:

• InstructionsLoaded hooks don't fire for a directly read AGENTS.md. They fire normally for one a CLAUDE.md imports or symlinks to. If you built tooling on that hook, the import route keeps it working.
• Directories you add with --add-dir contribute their CLAUDE.md (with CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD set) but never their AGENTS.md.
• External @path imports behave differently. From a CLAUDE.md, an import resolving outside your working directory triggers an approval dialog. From an AGENTS.md read through the setting, it loads with no prompt — but only if you already approved external imports for that project.

What is the same: @path imports expand with the same four-hop depth limit, claudeMdExcludespatterns apply, and subagents that skip project instructions skip AGENTS.md too — the same scoping gotcha that bites people with output styles versus CLAUDE.md. And for the record: AGENTS.local.md, AGENTS.override.md and anything under a .agents/ directory are never read. Those are conventions from other tools that Claude Code does not implement.

When Claude isn't reading your AGENTS.md directly — because you also have a CLAUDE.md, or you're on Bedrock, or you deliberately run claude-md — keep AGENTS.md as the single shared file and point at it:

<!-- CLAUDE.md -->
@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.
Run `pnpm test:unit` before every commit; the e2e suite needs a seeded DB.

Claude reads the imported file first, then whatever you put below it. That layout is genuinely nice: the shared, tool-neutral contract lives in AGENTS.md where Codex and Cursor pick it up, and the Claude-specific stuff sits underneath without polluting it.

The symlink alternative works too, and I'd still skip it:

ln -s AGENTS.md CLAUDE.md   # prints nothing on success

• Editing breaks. Claude reads through the link fine, but the Edit and Write tools refuse to write through a symlink and redirect Claude to edit AGENTS.md instead. Workable, just noisy.
• Windows is worse. Creating a symlink needs Administrator privileges or Developer Mode, and Git checks a committed symlink out as a plain text file unless core.symlinks is enabled. That clone ends up with a one-line CLAUDE.md containing the string AGENTS.md where your instructions should be, and Claude reads it as gospel. One contributor on Windows is enough to poison the repo.

One cleanup item if you worked around this before September: if you had a SessionStarthook that printed AGENTS.md into context, delete it. Now that Claude reads the file directly, the hook adds a second copy of your entire instruction file to every session. That's wasted input tokens on every turn, and prompt caching will happily cache the duplicate for you. A CLAUDE.md containing only @AGENTS.md, on the other hand, is safe to leave — Claude never double-reads it, whichever setting value you're on.

I run Claude Code across a dozen-odd repos — client Next.js sites, n8n automation stacks, a pile of Python agent tooling — and I moved every one of them to AGENTS.md as the primary file inside a week of this shipping. Not because AGENTS.md is a better format. It's the same Markdown. It's because I stopped maintaining two files that drifted.

The pattern: AGENTS.md holds the contract— stack, commands, conventions, what not to touch. If a repo needs Claude-specific behavior, a two-line CLAUDE.md sits next to it with @AGENTS.mdon the first line and the Claude-only rules below. No symlinks anywhere. Project instructions left on the default, because with that CLAUDE.md present the import handles it and I get identical behavior on Bedrock sessions where the direct read doesn't work.

The thing that surprised me is how much this cleaned up portability across agents. I test the same repo with Claude Code and Codex fairly often. Before, they behaved differently and I'd assume the models disagreed. Half the time they were reading different files. Two of my repos had a CLAUDE.md eleven months out of date next to a current AGENTS.md. Nobody noticed because nobody reads the file that isn't failing.

Keep the same discipline you'd apply to CLAUDE.md, though. Specific and concise beats long, and none of this is enforcement — it's context. If Claude absolutely must not run a command, that belongs in a PreToolUse hook, not a bullet in a Markdown file. Same principle as everything else in this stack: instructions steer, tooling and permissions enforce.

Two commands do most of the work:

• /initreads other tools' instruction files and folds the relevant parts into a generated CLAUDE.md. Out of the box that covers Cursor rules in .cursor/rules/ or .cursorrules and Copilot rules in .github/copilot-instructions.md. Set CLAUDE_CODE_NEW_INIT=1 and it also reads AGENTS.md, .devin/rules/, .windsurf/rules/ and .clinerules.
• /import(v2.1.213+) brings a supported agent's whole configuration over — a one-time copy of instruction files appended to the matching CLAUDE.md, plus MCP servers, commands, subagents and skills.

For a monorepo, follow the AGENTS.md convention rather than inventing one: nested files, closest to the edited file wins. OpenAI's own main repo runs 88 of them. Claude Code matches this — it loads a subdirectory's AGENTS.md when it opens a file there with the Read tool, provided that subdirectory has none of the three CLAUDE.md files of its own. Worth pairing with a deliberate memory strategy if your agents run long enough to accumulate their own notes.

One last honesty check before you migrate:read your CLAUDE.md first. If it's a wall of stale advice, renaming it to AGENTS.md just makes three more tools read the stale advice. The file being cross-compatible was never the hard part.