TL;DR: Claude Code v2.1.277 (released September 18, 2026) reads a repo’s AGENTS.md as project instructions — but only when there is no CLAUDE.md or CLAUDE.local.md anywhere in or above your working directory. It’s a fallback by default, not a merge. For teams running Claude Code alongside Codex, Cursor, or Copilot, one AGENTS.md can now replace three or four per-tool files.

	Keep CLAUDE.md only	AGENTS.md only	Both (merged)
Best for	Claude Code is your only agent	Multi-tool repos, OSS projects	Shared base + Claude-specific rules
What Claude Code loads	CLAUDE.md (AGENTS.md ignored)	AGENTS.md, since v2.1.277	Both, with a one-line settings change
The catch	Every other tool needs its own file	Not listed in /memory; gaps on Bedrock/Vertex	A stray CLAUDE.local.md silently blocks AGENTS.md on defaults

Honest take: If your repo already has a working CLAUDE.md and Claude Code is your main agent, change nothing — the default won’t even look at AGENTS.md. For any repo where two or more agents operate, write AGENTS.md as the single source of truth and keep per-tool files only for genuinely tool-specific rules. The lone holdout is Gemini CLI, which still ignores AGENTS.md unless you reconfigure it.

What changed in Claude Code 2.1.277?

Claude Code v2.1.277, released September 18, 2026, added native AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead. The exact changelog wording: “Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under ‘Project instructions’ in /config (not yet on Bedrock, Vertex or Foundry).”

Two words in that sentence carry all the weight: instead and no. This is a fallback, not a merge. A repository that already has a CLAUDE.md behaves exactly as it did before — Claude Code will not silently start consuming a co-existing AGENTS.md unless you opt in (covered below).

Why it matters: AGENTS.md is the open instruction-file format stewarded by the Agentic AI Foundation under the Linux Foundation, and per the standard’s site it’s read by 30+ agents and used in more than 60,000 open-source repositories. OpenAI Codex, Cursor, GitHub Copilot’s coding agent, Zed, Windsurf, and Amp were already on board, which made Claude Code the most conspicuous absence on the standard’s compatibility list. As of September 18, that gap is closed. Check your version with:

$ claude --version
2.1.278 (Claude Code)

Anything at or above 2.1.277 has the feature (2.1.278 is current as of September 21, 2026).

When does Claude Code read AGENTS.md — and when does it silently skip it?

By default, Claude Code reads AGENTS.md only when none of these three files exist in your working directory or any directory above it: CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md. Files that do not block the fallback: your personal ~/.claude/CLAUDE.md, an organization-managed CLAUDE.md, and .claude/rules/ files — all of those keep loading alongside AGENTS.md.

When the fallback fires, Claude Code loads every AGENTS.md and .claude/AGENTS.md from your working directory up through its parents at session start, and you get an explicit confirmation line in the conversation:

no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md

Subdirectories work the way CLAUDE.md always has: when Claude reads a file in a subdirectory that has its own AGENTS.md (and none of the three CLAUDE.md variants), that file loads on demand. @path imports inside an AGENTS.md are expanded too. What Claude Code will not read: AGENTS.local.md, AGENTS.override.md, or anything under a .agents/ directory — those are Codex-ecosystem conventions, not part of what shipped.

Here’s the trap that will actually bite people. Say your team’s repo standardized on AGENTS.md, and it works. Then you add a personal, uncommitted CLAUDE.local.md with your own preferences. Because CLAUDE.local.md counts as a CLAUDE.md for the fallback check, Claude Code stops reading the team’s AGENTS.md entirely — no warning, and your agent quietly loses every project instruction the rest of the team relies on. The AGENTS.md loaded line disappearing from session start is your only visible signal. The fix is the merge mode below.

How do you make Claude Code read CLAUDE.md and AGENTS.md together?

Set Project instructions to claude-md-and-agents-md — either interactively in /config, or in ~/.claude/settings.json:

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

Three values exist as of 2.1.278:

• claude-md-or-agents-md — the default fallback behavior described above.
• claude-md-and-agents-md — loads both, each directory’s CLAUDE.md files first, its AGENTS.md after them. Claude Code deduplicates: an AGENTS.md your CLAUDE.md already imports or symlinks to isn’t read twice.
• managed-only — only your organization’s managed CLAUDE.md loads at launch; project, local, and user files are all skipped.

One sharp edge from the docs: Claude Code ignores this setting in project-level and local settings files. It has to live in your user settings, a --settings file, or managed settings — so a repo can’t force merge mode on its contributors. If you want the shared-base-plus-personal-overrides pattern (AGENTS.md for the team, CLAUDE.local.md for you), every teammate sets claude-md-and-agents-md themselves.

Which AI coding tools read AGENTS.md in September 2026?

The support matrix, verified September 21, 2026 (official docs and changelogs; see Sources):

Tool	Reads AGENTS.md?	Since	How it interacts with the tool’s own format
OpenAI Codex CLI	Yes — native format	2025	~/.codex/AGENTS.md global + root-to-cwd walk; AGENTS.override.md wins per directory; merged output capped at 32 KiB by default
Cursor	Yes, root and subdirectories	2025–26	Plain-markdown alternative to .cursor/rules; .cursorrules is documented as legacy/deprecated
GitHub Copilot coding agent	Yes	Aug 28, 2025	Read alongside .github/copilot-instructions.md and *.instructions.md; also reads CLAUDE.md and GEMINI.md
Claude Code	Yes — fallback by default	Sep 18, 2026 (v2.1.277)	Reads AGENTS.md only with no CLAUDE.md present; merge available via claude-md-and-agents-md
Cline	Partial	2026	Global ~/.agents/AGENTS.md cross-tool instructions supported; project rules still center on .clinerules
Gemini CLI	No, not by default	—	Default context file is GEMINI.md; context.fileName accepts ["AGENTS.md", "GEMINI.md"], but the request to add AGENTS.md as a default was closed “not planned”

The practical read: with Claude Code on board, every major agent except Gemini CLI now honors a root AGENTS.md either natively or as a fallback. If Gemini CLI is in your stack, add this to .gemini/settings.json and it joins the club:

{ "contextFileName": ["AGENTS.md", "GEMINI.md"] }

How does Codex’s AGENTS.md handling differ from Claude Code’s?

Codex treats AGENTS.md as its primary format with a layered merge; Claude Code treats it as a compatibility fallback. The differences matter once files nest:

• Global layer: Codex reads ~/.codex/AGENTS.md (or AGENTS.override.md if present) before any project file. Claude Code has no global AGENTS.md — your global instructions live in ~/.claude/CLAUDE.md, which loads alongside a project AGENTS.md.
• Merge direction: Codex walks from the project root down to your current directory, concatenating one file per directory, deeper files overriding earlier ones. Claude Code loads the files above your working directory at session start and pulls subdirectory files in on demand as it reads code there.
• Size cap: Codex truncates the combined instructions at 32 KiB by default (project_doc_max_bytes). Claude Code applies no equivalent cap — which cuts both ways. Nothing gets silently truncated, but a bloated AGENTS.md rides into every session’s context window at full length. We measured what an oversized preprompt does to context budgets (about 9,000 tokens for a 35 KB file) in the large-CLAUDE.md-on-Ollama gotchas piece — every rule there now applies verbatim to AGENTS.md. Codex’s 32 KiB ceiling is a reasonable size target for a shared file even where no tool enforces it.
• Override files: AGENTS.override.md and fallback filename lists are Codex features. Claude Code ignores override files entirely.

Should you migrate your CLAUDE.md to AGENTS.md?

For a single-agent repo, no. The default mode never reads AGENTS.md when a CLAUDE.md exists, so migrating buys you nothing today, and CLAUDE.md remains the only file that shows up in /memory and fires InstructionsLoaded hooks (more on those gaps below).

For a multi-tool repo — one where Claude Code, Codex, Cursor, or Copilot each touch the code — the maintenance math favors migrating. A team running three agents previously maintained CLAUDE.md + .cursor/rules/*.mdc + .github/copilot-instructions.md, three files that drift apart the week after someone updates only one of them. The same team now needs one AGENTS.md for shared facts and, at most, thin tool-specific files for the rest.

The split that works:

• Into AGENTS.md: everything true regardless of which agent reads it — tech stack, build and test commands, directory map, forbidden patterns, API conventions, deploy notes. If it would belong in a new engineer’s onboarding doc, it belongs here.
• Stays tool-specific: Claude Code hooks, subagent and skill references, and /memory-managed content (CLAUDE.md); path-scoped .mdc rules with globs (Cursor); excludeAgent-filtered *.instructions.md (Copilot).

Migration for an existing Claude Code repo is one commit: git mv CLAUDE.md AGENTS.md, confirm the AGENTS.md loaded line on the next session, and tell teammates about the CLAUDE.local.md trap. If some of your environments can’t read AGENTS.md directly (next section), keep a one-line CLAUDE.md containing @AGENTS.md — the docs confirm keeping that import never causes a double-read, whichever mode you’re in.

Older workarounds age fine, in other words. If you already had CLAUDE.md → @AGENTS.md imports or symlinks from before v2.1.277, nothing breaks; remove the shim only if it holds nothing else.

Where AGENTS.md support still has gaps

Four cases where Claude Code won’t read AGENTS.md directly, per the official docs:

1. Bedrock, Vertex, and Foundry sessions — enterprise routing through Amazon Bedrock, Google Vertex, or Azure Foundry doesn’t support it yet.
2. The first session after installing or upgrading to a version with support; it works from the next session on.
3. Hook restrictions: disableAllHooks or allowManagedHooksOnly settings, or telemetry disabled — AGENTS.md support ships as the built-in agents-md plugin, so anything that blocks plugins blocks it.
4. The plugin disabled in /plugin.

In all four, the @AGENTS.md import from a stub CLAUDE.md works as before — that’s the reason to keep the shim in enterprise repos.

Two observability quirks are worth knowing even where support works. An AGENTS.md read through the fallback is not listed in /memory or in /context’s Memory files list — the AGENTS.md loaded session line (or just asking Claude what its project instructions say) is how you confirm it. And InstructionsLoaded hooks don’t fire for it, so tooling that audits which instructions loaded sees nothing; both gaps close if you load the file through an import instead.

What to actually do

Your situation	Do this	Effort
Solo repo, Claude Code only, CLAUDE.md works	Nothing — the default ignores AGENTS.md when CLAUDE.md exists	0 min
Repo used by 2+ agents (Codex, Cursor, Copilot, Claude Code)	git mv CLAUDE.md AGENTS.md; keep per-tool files only for tool-specific rules	~15 min
Team AGENTS.md + your personal CLAUDE.local.md	Set claude-md-and-agents-md in user settings or your AGENTS.md silently stops loading	2 min
Bedrock / Vertex / Foundry environments	Keep a stub CLAUDE.md containing @AGENTS.md	1 min
OSS project you maintain	Publish AGENTS.md; contributors on any of 30+ agents get your instructions for free	~30 min
Gemini CLI in the stack	Add "contextFileName": ["AGENTS.md", "GEMINI.md"] to .gemini/settings.json	2 min

Keep the shared file lean regardless of tool — Codex hard-truncates at 32 KiB, and on every other agent the whole file occupies context in every session. Structure and size rules from our large-preprompt analysis apply directly, and they bite hardest on local-model backends where context is scarcest.

FAQ

Does Claude Code read AGENTS.md and CLAUDE.md at the same time? Not by default. Out of the box (claude-md-or-agents-md), AGENTS.md loads only when no CLAUDE.md or CLAUDE.local.md exists in or above your working directory. Set Project instructions to claude-md-and-agents-md in /config to load both, CLAUDE.md first.

Which Claude Code version added AGENTS.md support? v2.1.277, released September 18, 2026. Run claude --version to check. It’s not yet available on Bedrock, Vertex, or Foundry sessions.

Does Claude Code read nested AGENTS.md files in subdirectories? Yes. Files in and above your working directory load at session start; a subdirectory’s AGENTS.md loads when Claude reads a file there, provided that subdirectory has no CLAUDE.md of its own. AGENTS.local.md, AGENTS.override.md, and .agents/ directories are never read.

Is .cursorrules dead now? Cursor’s docs mark .cursorrules as legacy with deprecation planned. Cursor reads AGENTS.md natively in the root and subdirectories; keep .cursor/rules/*.mdc only for path-scoped rules AGENTS.md can’t express.

Should an open-source project use AGENTS.md or CLAUDE.md? AGENTS.md. It’s the vendor-neutral standard (Agentic AI Foundation / Linux Foundation), 30+ tools read it including Claude Code since v2.1.277, and contributors keep their own preferences in files that don’t touch your repo. Agent-tool choice is personal — see our 7-way agent comparison and the FOSS agent landscape on aifoss.dev for how varied contributor setups get.

Sources

• Claude Code CHANGELOG (v2.1.277 AGENTS.md entry) — Anthropic, GitHub
• How Claude remembers your project (AGENTS.md behavior, modes, gaps) — Claude Code docs
• Claude Code v2.1.277 release mirror (Sep 18, 2026 date) — claude-code-changelog
• AGENTS.md — the open standard’s official site
• Custom instructions with AGENTS.md — OpenAI Codex docs
• Rules (AGENTS.md support, .cursorrules legacy) — Cursor docs
• Copilot coding agent now supports AGENTS.md — GitHub Changelog, Aug 28, 2025
• Adding repository custom instructions — GitHub Docs
• Provide context with GEMINI.md files (contextFileName setting) — Gemini CLI docs
• Add AGENTS.md to the context filename list by default (closed: not planned) — google-gemini/gemini-cli #12345
• Support global ~/.agents/AGENTS.md instructions — cline/cline #11063

Last updated September 21, 2026. Tool behavior and version numbers change frequently; verify against the official docs before restructuring a team repo.

Know which coding tool is worth paying for

Hands-on comparisons of AI coding assistants and what each one costs to run — including the local-model path. Sent only when something changes. Unsubscribe anytime.

Email address Subscribe