AGENTS.md vs CLAUDE.md: Precedence, Modes, When to Switch

Claude Code 2.1.277 reads AGENTS.md, but CLAUDE.md still wins by default. See the four modes, the CLAUDE.local.md gotcha, and when to keep both files.

By Muhammad Moeed ·September 24, 2026 ·19 min read

On September 18, 2026, Claude Code v2.1.277 quietly added AGENTS.md as a fallback for CLAUDE.md. The changelog bullet is one sentence long and easy to miss:

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).

Reddit and Hacker News threads have not stopped arguing about it since. Because 60,000+ open-source repos already ship AGENTS.md, and 30+ AI coding tools (Codex, Cursor, Copilot, Amp, Gemini CLI, and now Claude Code) read it natively. So the real question every team is asking is:

If we already have a CLAUDE.md, should we also add AGENTS.md? What happens if we have both? Do they merge or does one win?

This guide answers all of it: the exact precedence rule, the four modes Claude Code supports, the CLAUDE.local.md gotcha that silently breaks AGENTS.md loading, the still-open feature-flag issue that can make AGENTS.md invisible in specific environments, and a scenario-by-scenario decision matrix for picking one, the other, or both.

Written for developers new to either format. Every technical term has a plain definition below.

Quick answer

Precedence (default mode): CLAUDE.md wins. If any CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists in the current directory or any directory above it, Claude Code loads only those and skips AGENTS.md entirely.
Only AGENTS.md exists in the tree: Claude Code loads AGENTS.md.
To load BOTH: opt in to the claude-md-and-agents-md mode via /config > Project instructions, or set pluginConfigs['agents-md@builtin'].options.instructionFiles in ~/.claude/settings.json.
Four modes total: claude-md-or-agents-md (default), claude-md-and-agents-md (load both), claude-md (ignore AGENTS.md), managed-only (org policy only).
Bedrock, Vertex, Foundry: AGENTS.md fallback does NOT work at v2.1.277 launch. Enterprise Claude Code users on these platforms still need CLAUDE.md.
Version requirement: Claude Code v2.1.277 or newer. Known issue #95690 (still open as of Sept 24, 2026): AGENTS.md may fail to load when CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 is set or when running through third-party gateways, Bedrock, or Vertex, because the loader depends on a remote feature-flag fetch.

Beginner glossary (skip if you know these)

AGENTS.md: a plain Markdown file at the root of a code repo that tells any AI coding agent how to build, test, and contribute. Open standard maintained by the Agentic AI Foundation (under the Linux Foundation), read natively by 30+ tools.
CLAUDE.md: Anthropic’s project-instructions file for Claude Code. Same idea as AGENTS.md but Claude-specific, with extras: @-imports, hierarchical loading across managed/user/project/local scopes, HTML comment stripping, and a companion CLAUDE.local.md for personal gitignored overrides.
Fallback behavior: how Claude Code decides which file to read. Default: if any CLAUDE.md exists at or above the current directory, only CLAUDE.md loads. If none exists, Claude falls back to AGENTS.md. Never both unless you opt in.
Project instructions toggle: a setting in /config (four values, see below) that controls which files load. Equivalent settings.json key: pluginConfigs['agents-md@builtin'].options.instructionFiles.
@-import: a line like @path/to/file inside a CLAUDE.md that pulls another file’s contents inline at load time. Recursive up to 4 levels. Handy for splitting long instructions or pointing CLAUDE.md at a shared AGENTS.md.
Managed policy CLAUDE.md: a CLAUDE.md placed at an OS-level policy path (/Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux) that IT teams use to ship org-wide rules. Loads first and cannot be overridden in managed-only mode.
Nested lookup: how each format handles subdirectories. Nearest file wins per directory. At launch every file at or above cwd loads; subdirectory files load on demand when Claude opens files there.

Where AGENTS.md came from (short history)

AGENTS.md is not an Anthropic invention. It was launched by OpenAI in August 2025 alongside Google, Cursor, Factory, and Sourcegraph as an open convention for cross-agent project instructions. On December 9, 2025, the standard was donated to the Linux Foundation and is now stewarded by the Agentic AI Foundation under MIT license.

The idea is simple: one file per repo, plain Markdown, no proprietary format, readable by any agent. As of September 2026, agents.md lists 23 tools on its homepage grid as native supporters, and community counts put adoption at 60,000+ open-source repos.

Anthropic added AGENTS.md support to Claude Code on September 18, 2026 (v2.1.277) as the last major agent to adopt the standard. The delay was long enough that the community had already built workarounds (@AGENTS.md imports inside a CLAUDE.md, ln -s AGENTS.md CLAUDE.md symlinks) that still work fine.

The precedence rule (four modes)

Claude Code v2.1.277+ supports four precedence modes. Set them in /config > Project instructions, or in ~/.claude/settings.json, --settings <file>, or managed settings under:

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

(Project and local settings files ignore this key. It has to be user, managed, or --settings.)

The four modes:

1. `claude-md-or-agents-md` (default)

Behavior: winner-takes-all. If any CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists at or above the current directory, only those files load. AGENTS.md is skipped entirely. If NO CLAUDE.md variant is found in the tree, AGENTS.md loads instead.

Interactive indicator: when AGENTS.md is used, Claude Code prints a line like no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md.

Notes: ~/.claude/CLAUDE.md, managed CLAUDE.md, and .claude/rules/ do NOT count for the precedence check, so those always coexist with AGENTS.md.

2. `claude-md-and-agents-md`

Behavior: both files load together. Per directory, CLAUDE.md files load first, then AGENTS.md. Claude Code deduplicates so an AGENTS.md already imported or symlinked from a CLAUDE.md is not read twice.

Use case: mixed teams where some contributors use Claude Code and others use Codex or Cursor, and both files must stay in sync automatically. Also the only mode that prevents a rogue CLAUDE.local.md from suppressing AGENTS.md.

3. `claude-md`

Behavior: CLAUDE.md files only. AGENTS.md is fully ignored even if no CLAUDE.md exists.

Use case: teams who want to guarantee Claude Code never picks up an AGENTS.md that other tools committed, and prefer a hard “if no CLAUDE.md, no instructions” behavior.

4. `managed-only`

Behavior: only the organization’s managed CLAUDE.md and auto memory load at launch. Project CLAUDE.md, user CLAUDE.md, CLAUDE.local.md, .claude/rules/, and all AGENTS.md files are excluded. Subdirectory CLAUDE.md and .claude/rules/ files still load on demand when Claude reads files there.

Use case: compliance-heavy organizations shipping one security-team-approved instruction set and blocking per-project overrides.

The `CLAUDE.local.md` gotcha (Issue #96117)

This is the single biggest footgun of the new precedence system:

CLAUDE.local.md counts as a CLAUDE.md for the precedence check.

Meaning: if you have a team AGENTS.md committed at repo root, and one developer adds a personal CLAUDE.local.md for private preferences (which is gitignored and never leaves their machine), that single developer’s Claude Code silently stops reading the team’s AGENTS.md.

They will not see a warning. Their AI just misses the team context. Bug reports labeled “Claude ignores our team rules” started rolling in on GitHub within days.

Fixes:

Recommended: switch the whole team to claude-md-and-agents-md mode via managed settings. Personal CLAUDE.local.md files then coexist with AGENTS.md instead of suppressing it.
Alternative: put personal preferences in ~/.claude/CLAUDE.md (user scope). User-scope CLAUDE.md does NOT count for the precedence check.
Nuclear: rename CLAUDE.local.md to something that does not match the pattern (some teams use NOTES.local.md).

The feature-flag gate issue (Issue #95690, still open)

There is one known issue with the AGENTS.md fallback you should know about before you rely on it.

The bug: Claude Code’s AGENTS.md loader is implemented as a built-in Mod (plugin) that is off-by-default and gated behind a remote Anthropic feature flag (tengu_agents_md_mod, a Statsig gate). Reading the local AGENTS.md file requires no network, but the plugin waits on the server-side flag. When the flag fetch is blocked, the plugin stays unavailable, and the local AGENTS.md is silently ignored with no warning.

Documented failure conditions (from the community bug report):

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 set in the environment
Sessions routed through third-party gateways where the Statsig endpoint is not reachable
Bedrock and Vertex deployments (already excluded from AGENTS.md fallback in the launch changelog)

Note: the bug is that a blocked flag fetch loses the feature. It is NOT that AGENTS.md loading sends extra or unexpected telemetry. Some Reddit summaries got this backward.

Status: GitHub Issue #95690 is still open as of September 24, 2026. Anthropic has not yet responded on the issue thread, and no fix version appears in the changelog through v2.1.281. Treat the AGENTS.md fallback as best-effort until Anthropic ships an explicit fix or moves the loader out of the feature-flag gate.

Workaround (works today): put a one-line CLAUDE.md at repo root containing @AGENTS.md. This routes around the feature flag entirely because the CLAUDE.md loader has always worked without a network call, and the @-import expansion pulls AGENTS.md in on load.

File format side-by-side

Dimension	CLAUDE.md	AGENTS.md
Owner	Anthropic (Claude Code-specific)	Open standard, Agentic AI Foundation
Location	Managed, user (`~/.claude/`), project root, `.claude/`, `CLAUDE.local.md`	Project root, `.claude/AGENTS.md`, nested subdirectories
Nested lookup	Concatenates all at launch (root-down, nearest last); subdirectory files on demand	Concatenates all at launch; subdirectory files on demand; nearest wins
`@` import syntax	Yes (`@path/to/file`, relative or absolute, recursive to depth 4, imports outside cwd need approval)	Not in the open spec. Claude Code applies the same `@`-import expansion locally, but imports are NOT portable to other agents
YAML frontmatter	No	Not required; some tools (Amp) support scoped glob patterns
Recommended max size	Under 200 lines (soft target for adherence)	Under 150-200 lines (community consensus; Codex caps the combined AGENTS.md chain at 32 KiB via the `project_doc_max_bytes` setting, dropping later files in the chain when the total is reached)
Hard parser cap	4 MiB per file	Same 4 MiB when read by Claude Code
Hierarchy scopes	Managed > user > project > local (loaded in that order)	Nearest file wins per directory
Ignored variants	(none)	`AGENTS.local.md`, `AGENTS.override.md`, anything under `.agents/`

Practical takeaway: CLAUDE.md’s format is richer (scopes, imports, HTML comment stripping) but locked to Claude Code. AGENTS.md is simpler but portable across 30+ tools.

Which tools read which file (ecosystem adoption)

Tool	AGENTS.md	CLAUDE.md	Notes
Claude Code	Fallback only (v2.1.277+)	Native primary, always wins in default mode	Not yet on Bedrock, Vertex, Foundry
OpenAI Codex	Native primary	Not read	AGENTS.md was originally designed for Codex. Truncates at 32 KiB
Cursor	Native (since Cursor 0.48)	Not read	Also supports `.cursor/rules/*.mdc`, User Rules, Team Rules, legacy `.cursorrules`
Amp (Sourcegraph)	Native, supports YAML glob patterns	Not read	AGENTS.md-only for project-level rules
Gemini CLI	Opt-in via `settings.json context.fileName`	Not read	Native `GEMINI.md` still supported
Aider	Opt-in via `--conventions-file`	Not read	Aider defaults to `CONVENTIONS.md`
Cline	Native, alongside `.clinerules/` and `.cline/rules/`	Not read	Global cross-tool from `~/.agents/AGENTS.md`
DeepSeek Harness	Native	Native	Reads both files
Continue.dev	Not officially confirmed (Issue #6716 open)	Not read	Native rules under `.continue/rules/`
GitHub Copilot Coding Agent	Native (on agents.md grid)	Not read	Also supports `.github/copilot-instructions.md`
Windsurf, Devin, Jules, Factory, goose, Zed, Warp, JetBrains Junie, Semgrep, VS Code, UiPath Autopilot, opencode, RooCode, Kilo Code, Phoenix, Ona, Augment Code	Listed on agents.md homepage grid	Varies (usually not)	23 total on agents.md grid as of Sept 24, 2026

Decision matrix: which should you use?

Your situation	Pick	Why
Solo dev, only Claude Code, wants imports and hierarchy	CLAUDE.md only	You lose nothing by staying native. Extras (imports, scopes) are Claude-specific and gone with AGENTS.md
Team using Cursor + Codex + Claude Code + Gemini CLI on the same repo	AGENTS.md as source of truth; one-line `CLAUDE.md` with `@AGENTS.md` OR symlink `ln -s AGENTS.md CLAUDE.md` on unix	Standards outlive tools. Symlink prevents drift entirely (Windows caveat: Git checks out symlinks as text without developer mode)
Enterprise on Bedrock, Vertex, or Foundry	CLAUDE.md required (with `@AGENTS.md` if you also serve other agents)	AGENTS.md fallback is not supported on these platforms at v2.1.277
Team wants BOTH files with zero risk of `CLAUDE.local.md` breakage	Set Project instructions to `claude-md-and-agents-md`	Only mode where a stray `CLAUDE.local.md` does not suppress AGENTS.md; auto-dedupes symlinks/imports
New open-source project targeting any AI agent user	AGENTS.md at repo root	60,000+ repos already ship AGENTS.md; contributors on any of 30+ agents get context with zero per-tool config
Monorepo with 5+ services, different conventions per subdirectory	Nested CLAUDE.md (or nested AGENTS.md if multi-tool). Prefer CLAUDE.md if Claude-only	CLAUDE.md’s `@`-import lets a root file compose per-service rules explicitly. AGENTS.md hierarchy is spec-level but portable `@`-imports do not exist
Migrating an existing CLAUDE.md-only project to multi-tool	Move shared context to AGENTS.md, leave CLAUDE.md as `@AGENTS.md` + Claude-only overrides (or symlink)	`@`-import pattern is community-standard; keeps one source of truth on disk
Compliance-heavy org, one instruction set from security team, block per-project overrides	Managed CLAUDE.md at OS policy path + `managed-only` mode	Only mode that excludes project, user, and local CLAUDE.md plus all AGENTS.md at launch
Personal preferences on a project that relies on AGENTS.md	Do NOT use `CLAUDE.local.md`. Put notes in `~/.claude/CLAUDE.md` (user scope) OR switch project to `claude-md-and-agents-md`	`CLAUDE.local.md` silently suppresses AGENTS.md on the default setting (Issue #96117)
Session with `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`, on a third-party gateway, or on Bedrock/Vertex	Put `@AGENTS.md` inside a one-line CLAUDE.md as workaround	The AGENTS.md loader depends on a remote feature flag; when the flag fetch is blocked, AGENTS.md is silently ignored (Issue #95690, still open)

Common confusions (get these right)

CLAUDE.local.md just adds local overrides. It does not. In the default mode, CLAUDE.local.md counts as a CLAUDE.md for precedence and silently drops every AGENTS.md on the path from cwd to root (Issue #96117).
AGENTS.md is an Anthropic invention. It is not. OpenAI launched it in August 2025 with Google, Cursor, Factory, and Sourcegraph. Donated to the Linux Foundation on December 9, 2025.
Claude Code reads AGENTS.md everywhere it runs. It does not. Bedrock, Vertex, and Foundry deployments do not receive the AGENTS.md fallback at v2.1.277. And on v2.1.277-2.1.280, telemetry-disabled sessions silently missed it.
Merging both files is the default. It is not. Default is winner-takes-all. To load both, opt into claude-md-and-agents-md.
AGENTS.md supports @-imports the same way CLAUDE.md does. Only when Claude Code reads it. The AGENTS.md open spec defines no @-import mechanism, so imports written for Claude Code will not portably resolve in Codex, Cursor, or Gemini CLI.
Splitting a long CLAUDE.md via @-imports shrinks the context. It does not. Imports load at launch and add the full content to context. The “under 200 lines” guidance is about adherence, not parser limits (4 MiB per file is the hard cap).
InstructionsLoaded hooks fire for every instruction file. They do NOT fire for an AGENTS.md read directly via the Project instructions setting. They DO fire for an AGENTS.md that a CLAUDE.md imports or symlinks to.

Practical setup: three patterns that work

Pattern A: Claude-only team

Keep CLAUDE.md as-is. Do nothing else. AGENTS.md is not relevant for you unless a contributor arrives with a different tool.

Pattern B: Multi-tool team with one source of truth

Move all shared context to AGENTS.md at repo root.
Create a one-line CLAUDE.md with just: @AGENTS.md
Optionally add Claude-only overrides below the import in CLAUDE.md.
Alternative (unix only, watch for Windows Git symlink issues): ln -s AGENTS.md CLAUDE.md.

Every agent reads its native file. No drift because both point at (or include) the same source.

Pattern C: Enterprise policy + team AGENTS.md

IT team publishes a managed CLAUDE.md at the OS policy path (/Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux).
Teams commit AGENTS.md at their repo roots for project-specific context (portable across agents).
Set pluginConfigs['agents-md@builtin'].options.instructionFiles = "claude-md-and-agents-md" in managed settings.
Both load. Managed CLAUDE.md is always loaded (does not count for precedence). Team AGENTS.md comes along per-project. No CLAUDE.local.md gotcha because you are in claude-md-and-agents-md mode.

FAQs

Does Claude Code read AGENTS.md?

Yes, since v2.1.277 (released September 18, 2026). It is a fallback: Claude Code reads AGENTS.md only when no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists at or above the current directory. To load both files together, switch to the claude-md-and-agents-md mode via /config > Project instructions.

Which takes precedence, CLAUDE.md or AGENTS.md?

CLAUDE.md, in the default mode. If any CLAUDE.md variant exists in the current directory or above, AGENTS.md is skipped entirely. To change this, use the /config Project instructions toggle: claude-md-and-agents-md (load both), claude-md (never load AGENTS.md), or managed-only (org policy only).

What version of Claude Code added AGENTS.md support?

v2.1.277, released September 18, 2026. Known issue #95690 (still open as of Sept 24, 2026): AGENTS.md may fail to load when CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 is set, or when Claude Code runs behind a third-party gateway, because the loader depends on a remote feature-flag fetch. Workaround: put a one-line CLAUDE.md containing @AGENTS.md at your repo root to route around the flag entirely.

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

Yes. Two ways: (1) opt into claude-md-and-agents-md mode, which loads both files with automatic deduplication; (2) keep one file as the source of truth and have the other import or symlink to it. The @AGENTS.md import inside a CLAUDE.md is the portable pattern; ln -s AGENTS.md CLAUDE.md is the zero-drift unix pattern.

How do I symlink CLAUDE.md to AGENTS.md?

On macOS or Linux: ln -s AGENTS.md CLAUDE.md at your project root. On Windows this requires Developer Mode enabled or admin PowerShell, and Git may check out the symlink as a text file (containing the target path as its content) unless core.symlinks is set. The safer cross-platform pattern is a one-line CLAUDE.md containing @AGENTS.md.

Does Codex read CLAUDE.md?

No. OpenAI Codex reads AGENTS.md only. Codex-only teams must consolidate everything in AGENTS.md. Codex silently truncates AGENTS.md at 32 KiB, so keep it well under that.

Does CLAUDE.local.md break AGENTS.md loading?

Yes, in the default claude-md-or-agents-md mode. CLAUDE.local.md counts as a CLAUDE.md for the precedence check and silently suppresses AGENTS.md on the entire path from cwd to root. Fix: switch to claude-md-and-agents-md, or put personal notes in ~/.claude/CLAUDE.md (user scope, does NOT count for precedence). See GitHub Issue #96117.

Is AGENTS.md an official standard?

Yes. Launched by OpenAI in August 2025 with Google, Cursor, Factory, and Sourcegraph. Donated to the Linux Foundation on December 9, 2025. Now stewarded by the Agentic AI Foundation under MIT license. 60,000+ open-source repos ship AGENTS.md; 23 tools list native support on agents.md.

Does Claude Code read AGENTS.md on Bedrock or Vertex?

Not at v2.1.277 launch. The changelog bullet says explicitly: “not yet on Bedrock, Vertex or Foundry.” Enterprise Claude Code deployments on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry still need a CLAUDE.md at the project root. Anthropic has not published an ETA for adding the fallback to these platforms.

How long should an AGENTS.md file be?

The open spec sets no limit. Community consensus and Anthropic’s own CLAUDE.md guidance: under 200 lines. Codex caps the combined AGENTS.md chain at 32 KiB by default (configurable via the project_doc_max_bytes setting); when the running total is reached, Codex stops adding further files in the precedence chain rather than truncating inside a single file. Claude Code’s hard cap is 4 MiB per file. Longer is not better, because the model has to hold the entire file in context, and bloated instructions cause the model to skip parts.

Should I commit AGENTS.md to git?

Yes for shared context (repo root, subdirectories). No for personal preferences. Those go in AGENTS.local.md for tools that read it (Cline, Codex), or in ~/.claude/CLAUDE.md (user scope) for Claude Code. Note that Claude Code does NOT read AGENTS.local.md, AGENTS.override.md, or anything under .agents/.

What we still do not know

When AGENTS.md fallback will reach Bedrock, Vertex, and Foundry. Anthropic’s public statement is “not yet” with no date.
Exact real-time count of GitHub repos with AGENTS.md. agents.md claims 60,000+. Independent DEV community sampling put adoption at ~6.2% of active repos. GitHub code search is login-gated.
Whether the AGENTS.md open spec will standardize @-imports and hierarchy. Only Claude Code’s implementation supports @-imports inside AGENTS.md today, and imports are not portable.
When Anthropic will fix the feature-flag issue (#95690). The issue is open with no Anthropic response and no fix in the v2.1.281 changelog. Rely on the @AGENTS.md-inside-a-CLAUDE.md workaround for now.
Whether Continue.dev will add first-class AGENTS.md support. Issue #6716 is open; Continue is absent from the agents.md homepage grid.

Where to go next

Claude Code Skills vs MCP vs Hooks vs Plugins: where instruction files sit alongside the other four Claude Code primitives.
Claude Code Hooks Tutorial: InstructionsLoaded and other hooks that fire (or don’t) when instruction files load.
Claude Code Weekly Limit Cut Sept 14: why keeping instruction files under 200 lines matters for your usage budget.
Claude Opus 5.5 Migration Guide: the other big September 2026 change for Claude Code users.
MCP Server Not Connecting Fix Guide: if AGENTS.md instructions reference MCP servers, this covers the setup gotchas.

Last updated: September 24, 2026. I will re-check this page when AGENTS.md ships on Bedrock/Vertex/Foundry, when the AGENTS.md spec adds hierarchy or @-imports, or when Anthropic publishes a formal post-mortem on the telemetry-flag regression.