Does Claude Code Read AGENTS.md? Yes, Now It Does

Short answer: yes, Claude Code now reads AGENTS.md. Since v2.1.277 (September 18, 2026), a repo with an AGENTS.md and no CLAUDE.md works in Claude Code with zero setup. If a CLAUDE.md exists anywhere on the path, it still wins and AGENTS.md is ignored, unless you flip one setting.

That last clause is where most of the confusion lives. The rest of this post is the exact mechanism, the four modes you can pick, and the ways it quietly fails.

The Rule in One Table

The official memory docs reduce the default behavior to three cases:

So this is a fallback, not a merge. The changelog line for 2.1.277 says it plainly: "in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead."

Some coverage attributes the change to 2.1.278, which shipped the same day and switched auto mode to the server-side classifier. The AGENTS.md support landed one version earlier, in 2.1.277.

If you want the conceptual background on why two files exist at all, read AGENTS.md vs CLAUDE.md first. This post is about what changed and how the new loader behaves.

How the Check Actually Works

When a session starts, Claude Code walks from your working directory up to the filesystem root, looking for files that disqualify AGENTS.md.

These count (finding any one means Claude reads CLAUDE.md instead):

• CLAUDE.md in the working directory or any parent
• .claude/CLAUDE.md in the working directory or any parent
• CLAUDE.local.md in the working directory or any parent

These do not count (they keep loading alongside AGENTS.md):

• Your user-level ~/.claude/CLAUDE.md
• Your organization's managed CLAUDE.md
• Files under .claude/rules/

That split matters. Your personal global preferences in ~/.claude/CLAUDE.md do not switch a repo off AGENTS.md. But a stray CLAUDE.md in a parent folder does. The team at Classmethod confirmed this in testing: a CLAUDE.md higher in the tree blocked the AGENTS.md below it.

What loads once the check passes

If nothing counts, Claude Code reads:

1. At session start: every AGENTS.md and .claude/AGENTS.md in your working directory and the directories above it. In an interactive session you see a line like no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md.
2. As Claude works in subdirectories: a subdirectory's AGENTS.md loads lazily, when Claude opens a file there with the Read tool, and only if that subdirectory has none of the three CLAUDE.md variants of its own.
3. Inside each AGENTS.md: @path imports expand, claudeMdExcludes patterns apply, and subagents configured to skip project instructions skip these files too.

Never read: AGENTS.local.md, AGENTS.override.md, or anything under a .agents/ directory. If your team adopted Codex's override convention, Claude Code will not see those files.

This is the same lazy, directory-scoped model Claude Code already uses for CLAUDE.md. Ancestors load up front. Descendants load on demand. For a deeper look at that hierarchy, see CLAUDE.md mastery.

The Project Instructions Setting

The fallback is the default, not the only option. Type /config and find Project instructions. It takes four values:

You can also set it in a settings file. It lives under the built-in agents-md plugin's ID in pluginConfigs:

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

Two details that trip people up:

• Where it is honored: ~/.claude/settings.json, a --settings file, or managed settings. Claude Code ignores this key in project .claude/settings.json and local settings. You cannot commit a repo-level switch for your teammates. Each developer (or the org admin) sets it.
• When it applies: from the next message you send, and in every new session. No restart needed.

The fact that the whole feature ships as a built-in plugin also explains one failure mode below: disable the agents-md plugin in /plugin and the setting disappears from /config entirely.

Loading Both Files Without Doubling Context

claude-md-and-agents-md is the mode most mixed-tool teams actually want. Shared rules live in AGENTS.md. Claude-only rules (plan mode triggers, hook conventions, subagent routing) live in CLAUDE.md.

The ordering is per directory: CLAUDE.md content first, then AGENTS.md. And the loader deduplicates. If your CLAUDE.md already imports @AGENTS.md, or CLAUDE.md is a symlink to AGENTS.md, the file is not read a second time.

That dedup is why the old import pattern is safe to keep:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

With the import, Claude reads the imported file first, then the Claude-specific section. Keep this pattern in any repo where some sessions might run an older Claude Code version, because the import works on every version.

Where AGENTS.md Is Not Quite CLAUDE.md

An AGENTS.md loaded directly through the setting behaves a little differently from a CLAUDE.md:

If you run an InstructionsLoaded hook for auditing or logging, a direct-read AGENTS.md is invisible to it. If you rely on --add-dir to pull in a sibling repo's instructions, that sibling needs a CLAUDE.md, or an import.

The Bedrock, Vertex, and Foundry Gap

At launch, the 2.1.277 release carried a caveat: AGENTS.md support was not available on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry.

The current docs narrow that. Before v2.1.281, some sessions, including those on Bedrock and those with telemetry disabled, read CLAUDE.md files only. On v2.1.281 or later, that restriction is gone for those cases.

The practical rule: if your company routes Claude Code through a cloud provider, or your security team disables telemetry, run claude --version. Below 2.1.281, the AGENTS.md fallback silently does nothing, and Project instructions will not appear in /config at all. That missing row is the tell.

The fix on old versions is the same one that has always worked: a CLAUDE.md next to your AGENTS.md containing @AGENTS.md.

One File for Codex, Cursor, and Copilot

The point of the change is a single instruction file shared across agents. AGENTS.md is stewarded by the Agentic AI Foundation under the Linux Foundation, and the agents.md site lists OpenAI Codex, Cursor, GitHub Copilot's coding agent, Gemini CLI, Jules, Aider, Zed, Warp, Devin, and others as compatible.

"Compatible" does not mean "identical loader." The tools resolve the same file differently:

The agents.md spec's own guidance is "the closest one takes precedence." Claude Code's lazy subdirectory loading is compatible with that in spirit, but not byte-for-byte. Write your nested files so they add detail rather than contradict the root, and you avoid depending on any one tool's merge order.

What goes in the shared file

Content every agent can act on:

• Build, test, lint, and typecheck commands, exact and copy-pasteable
• Directory map and where new code goes
• Code style rules a linter does not already enforce
• "Never do X" constraints: generated files, migrations, secrets
• PR and commit conventions

What stays out, because only Claude Code understands it:

• Skill and subagent routing
• Hook behavior and plan mode triggers
• / command conventions

That second list goes in a CLAUDE.md that imports the first, with claude-md-and-agents-md or the import doing the combining. Keep the shared file short. Codex truncates past its byte cap, and every agent pays the token cost on every session.

Migration: Remove the Old Workarounds

Before 2.1.277, teams bridged the gap four common ways. Here is what to do with each, per the official guidance:

1. CLAUDE.md containing @AGENTS.md. Leave it. It never causes a double read. Delete the CLAUDE.md only if the import is its only line and no session runs an old version or an older Bedrock setup.

2. CLAUDE.md that says "read AGENTS.md" in words. Fix this one. Claude only sees AGENTS.md if it decides to open the file, which is not guaranteed. Delete the CLAUDE.md so the fallback kicks in, or replace the sentence with a real @AGENTS.md import.

3. CLAUDE.md symlinked to AGENTS.md. Nothing required. Content is read once either way. Delete it if you want a cleaner tree.

4. SessionStart hook that prints AGENTS.md. Remove it. Once Claude reads the file natively, the hook injects a second copy into context on every session.

Then verify. Run /memory and look for the AGENTS.md path in the list. On versions before v2.1.280, /memory and /context did not list a directly read AGENTS.md, so on those versions ask Claude what its project instructions say.

For a one-time copy instead of a live link, /import (v2.1.213+) appends instruction files such as AGENTS.md into the matching CLAUDE.md and carries over MCP servers, commands, subagents, and skills from a supported agent. That creates a fork you have to keep in sync, so prefer the fallback or the import for anything shared.

Failure Modes

Every one of these produces the same symptom: Claude acts like it never saw your instructions. Check them in this order.

A CLAUDE.md somewhere up the tree

The most common cause. Monorepos are the classic case: someone added a CLAUDE.md at the repo root years ago, and now every package's AGENTS.md is dead weight. The check walks all the way up, so a CLAUDE.md in a parent folder outside the repo counts too. Your ~/.claude/CLAUDE.md does not.

A personal CLAUDE.local.md

A developer adds CLAUDE.local.md for private notes. That file counts for the check, so the fallback flips off for that developer only. Teammates see Claude follow AGENTS.md, this person does not, and nobody can reproduce it. Fix: set Project instructions to claude-md-and-agents-md in user settings.

First session after upgrading

Upgrading from v2.1.276 or earlier can leave the very first session reading CLAUDE.md only. The next session picks up AGENTS.md. If your test was "upgrade, launch, check," launch again.

Old version on a cloud provider or with telemetry off

Covered above. Below v2.1.281, Bedrock sessions and telemetry-disabled sessions skip AGENTS.md. The missing Project instructions row in /config confirms it.

The plugin is disabled

Someone pruned plugins in /plugin and turned off the built-in agents-md. Same symptom, same missing /config row.

Setting put in the project settings file

pluginConfigs for agents-md@builtin in .claude/settings.json is ignored. It must be in user, --settings, or managed settings.

Duplicate context from a leftover hook

The opposite failure. A SessionStart hook still prints AGENTS.md, now alongside the native read. Nothing breaks, you just burn tokens on two copies every session.

Symlink edits and Windows clones

If you chose ln -s AGENTS.md CLAUDE.md, the Edit and Write tools refuse to write through the symlink and redirect Claude to AGENTS.md. On Windows, Git checks out a committed symlink as a plain text file unless core.symlinks is enabled, leaving a one-line CLAUDE.md that contains a path instead of your rules. For mixed-OS teams, use the @AGENTS.md import or the native fallback.

Codex-only conventions

Rules in AGENTS.override.md or under .agents/ are invisible to Claude Code. If Codex and Claude behave differently in the same repo, diff what each one actually loaded.

Which Setup to Pick

• Only Claude Code, no other agents: keep CLAUDE.md. Nothing changes for you.
• Mixed tools, no Claude-specific rules: one AGENTS.md, no CLAUDE.md. The default mode handles it on v2.1.277+.
• Mixed tools plus Claude-specific rules: AGENTS.md for shared rules, a CLAUDE.md with @AGENTS.md at the top for the rest. Works on every version and every provider.
• Personal notes on top of a shared AGENTS.md: claude-md-and-agents-md in your user settings, so your CLAUDE.local.md does not knock out the team file.

The change is small in code and large in practice. The default rule is "CLAUDE.md if it exists anywhere up the tree, otherwise AGENTS.md." Know that rule, check /memory once, and one file really can serve every agent in the repo.

Posted by @speedy_devv