September 18, 2026. Claude Code 2.1.277 shipped a one-line changelog entry that quietly settles a year-long standards fight: "Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under 'Project instructions' in /config." Anthropic's CLI — the last major coding agent that still required its own proprietary instruction file — now reads the open AGENTS.md format natively. OpenAI's Codex, Google's Gemini CLI and Jules, Cursor, Amp, Aider, Zed, Warp, VS Code, and roughly sixty more tools adopted it years ago. Anthropic held out. The holdout is over.

On Hacker News the change drew 423 points and 151 comments in its first day — unusual traction for what looks like a file-name mapping. It isn't. The fight was never about the file name; it was about whether your project's agent instructions are portable infrastructure or per-vendor config sprawl. Platform teams that standardized on CLAUDE.md now own a migration decision, and teams that standardized on AGENTS.md own a new precedence bug surface. This piece breaks down exactly what shipped, the four-way precedence rules that now govern every repo, the deployment gaps that will bite you on Bedrock, and the governance stance we recommend.

What Actually Shipped: One Option, Four Modes

The implementation is not a hack. Anthropic open-sourced it as a mod — one of four built-in Claude Code plugins whose source lives in the anthropics/claude-code repo under mods/agents-md and ships compiled into the binary. The entire behavior is one option, instructionFiles, set via the Project instructions panel in /config:

ModeWhat Claude readsWho should set it
claude-md-or-agents-md (default)Your CLAUDE.md files — or your AGENTS.md files only when no CLAUDE.md / .claude/CLAUDE.md / CLAUDE.local.md exists in the working directory or any directory above itMost repos. AGENTS.md works "just works" without touching anything.
claude-md-and-agents-mdBoth files, per-directory: CLAUDE.md first, AGENTS.md after it. Files already @-imported or symlinked aren't double-loadedHybrid shops mid-migration, or teams that want agent-portable instructions beside Claude-specific overrides
claude-mdCLAUDE.md only. AGENTS.md ignoredRepos that never want agent-file portability; lock-in as an explicit choice
managed-onlyOrg-managed CLAUDE.md + auto memory only. Project/local/user CLAUDE.md, .claude/rules/, and every AGENTS.md droppedEnterprises running a central prompt/governance function

The critical precedence rule: under the default mode, the presence of any CLAUDE.md — including an uncommitted CLAUDE.local.md you keep for personal preferences — silently disables AGENTS.md loading. Per the docs: "Because CLAUDE.local.md counts, adding one to keep your own uncommitted instructions in a project that relies on AGENTS.md stops Claude from reading AGENTS.md for you." One stray local file and your entire agent-instruction contract stops applying for that developer. This is the single most likely operational failure mode of the whole feature.

The Precedence Table Every Repo Owner Should Pin

Claude Code's official docs give the exact resolution logic. Here it is in the form your team will actually consult:

Your repo has…Claude Code reads
AGENTS.md, no CLAUDE.md / CLAUDE.local.md anywhere above the working directoryAGENTS.md — plus every AGENTS.md and .claude/AGENTS.md up the directory tree
AGENTS.md + any CLAUDE.md or CLAUDE.local.md in or above the working directoryCLAUDE.md only — AGENTS.md silently ignored
CLAUDE.md that @-imports AGENTS.mdCLAUDE.md with AGENTS.md included through the import (works on every version, including Bedrock)

Files that don't block AGENTS.md loading and still load alongside it: your ~/.claude/CLAUDE.md (user-global), the org's managed CLAUDE.md, and .claude/rules/ files. Files that are never read: AGENTS.local.md, AGENTS.override.md, anything under .agents/. Subdirectory AGENTS.md files attach when Claude reads a file in that subdirectory with the Read tool (nested context), mirroring how nested CLAUDE.md files behave.

Load-order diagram — default mode (claude-md-or-agents-md):

session start
    │
    ├─ engine walks working-dir → root
    │      finds CLAUDE.md / .claude/CLAUDE.md / CLAUDE.local.md anywhere on path?
    │
    ├─ YES ──► CLAUDE.md chain loaded (AGENTS.md ignored entirely)
    │
    └─ NO  ──► agents-md mod loads every AGENTS.md + .claude/AGENTS.md on path
                   │
                   ├─ rendered into prompt.context as {path, kind: "project", content}
                   ├─ same framing/preamble/omission rules as CLAUDE.md
                   ├─ announced: "no CLAUDE.md found; AGENTS.md loaded: /repo/AGENTS.md"
                   └─ @path imports expanded, claudeMdExcludes patterns applied