Claude Code Adopts AGENTS.md: The Last Coding-Agent Holdout Blinks

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:

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:

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.

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

The Bedrock Gap: Where AGENTS.md Support Doesn't Exist

Here's the part the changelog buries and the docs surface: native AGENTS.md loading is feature-flagged, and the flag doesn't fly everywhere. Claude reads AGENTS.md natively only in sessions that fetch feature flags from Anthropic. The documented exceptions:

• Amazon Bedrock, Vertex, and Foundry sessions — the changelog itself says "not yet on Bedrock, Vertex or Foundry."
• Telemetry disabled — sessions without feature-flag fetching fall back to CLAUDE.md-only. If your hardening policy disables telemetry, AGENTS.md support disappears with it.
• First session after install/upgrade — AGENTS.md reads from the next session on.
• disableAllHooks or allowManagedHooksOnly set, or the built-in agents-md plugin disabled in /plugin — the feature is a plugin, so plugin policy kills it.

The workaround is the one the ecosystem used for the last year: CLAUDE.md containing a single line, @AGENTS.md. The import path is engine-native, works on every provider, fires InstructionsLoaded hooks, and shows up in /memory — which brings us to the divergences.

Import vs. Native Read: Four Divergences That Matter

The docs list exactly where a natively-read AGENTS.md behaves differently from a CLAUDE.md. For governance work, these matter:

That last row is the security-relevant one. An AGENTS.md sitting at the repo root can pull in a file from outside the repository — @/etc/something in the worst case — without triggering the approval prompt a CLAUDE.md import would. The docs frame it as convenience; a red team frames it as a prompt-injection surface that skips a consent gate. If AGENTS.md files in your org can be modified via merge-PR from an external contributor (they can — it's a plain markdown file in the repo), the @import of paths outside the working directory is a data-flow channel your code-review policy doesn't currently name.

Who Adopted What: The Vendor Matrix

With Anthropic in, every major coding agent now reads the same file. The agents.md registry tracks adoption and claims over 60,000 open-source projects now ship an AGENTS.md — including openai/codex (the standard's origin repo), apache/airflow (4,600+ forks), temporalio SDKs, and thousands of internal monorepos that adopted it as CI-adjacent documentation.

The takeaway: AGENTS.md won. Not because it's technically superior — it's a plain markdown file — but because it's the only instruction format that every agent can read without translation. The "tuned per-model prompt" argument (Anthropic's thariq made it publicly: prompts should be tuned for models, and blindly applying AGENTS.md "is probably an antipattern") lost to the operational reality that nobody maintains 60 instruction files per repo, and platform teams won't either.

What This Means for Platform Teams: Three Moves

# Option A — AGENTS.md canonical (recommended for multi-agent orgs)
repo/
├── AGENTS.md            # single source of truth, all tools read it
└── (no CLAUDE.md anywhere — check CI for stray files)

# Option B — AGENTS.md canonical + Claude-specific overrides
repo/
├── AGENTS.md            # portable core
└── CLAUDE.md            # one line: @AGENTS.md, plus Claude-only rules below
                          # fires hooks, lists in /memory, works on Bedrock

# Option C — lock-in explicit
repo/
└── CLAUDE.md            # claude-md mode; AGENTS.md deliberately ignored

Why This Matters More Than It Looks

The cynical read is correct in one respect: nothing about Claude's model changed. What changed is the topology of agent configuration. For two years the ecosystem looked like this:

BEFORE (2024–mid 2026)                    AFTER (Sep 18, 2026)
┌─────────────────────────┐               ┌─────────────────────────┐
│ your repo               │               │ your repo               │
│  ├─ CLAUDE.md    ───────┼── Claude only │  └─ AGENTS.md ─┬─ Claude Code │
│  ├─ GEMINI.md   ────────┼── Gemini only │                ├─ Codex       │
│  ├─ .cursor/rules ──────┼── Cursor only │                ├─ Gemini CLI  │
│  ├─ CONVENTIONS.md ─────┼── Aider only  │                ├─ Cursor      │
│  └─ (AGENTS.md) ────────┼── everyone else│                └─ 60+ tools   │
│                         │               │                          │
│  4–6 instruction files  │               │  1 instruction file       │
│  drifting apart silently│               │  + optional vendor shim   │
└─────────────────────────┘               └─────────────────────────┘

Instruction files drift. Anyone who maintained both CLAUDE.md and AGENTS.md knows the CLAUDE.md copy grows Claude-specific workarounds until the two disagree about what "run the tests" means. Standardization collapses that surface to one file with one CODEOWNERS line — and one place to audit when an agent does something you didn't expect.

The second-order effect is the one platform engineers should price in: AGENTS.md is becoming the first broadly-adopted piece of agent governance surface. It's plain markdown, so it diffs cleanly, reviews like code, and rides existing Git workflows — but it's also executed by every agent that reads it. The ZCode workspace-upload fiasco of last week (our coverage: ZCode's silent .git upload) is the bookend: instruction files are how agents learn what they're allowed to do. A file that sixty tools treat as authoritative context is now part of your platform's security perimeter, whether your threat model admits it or not.

Who Should Skip This

Standard Platform Monkey honesty: not every team needs to act this week.

• Single-agent shops (Claude-only) that already maintain a good CLAUDE.md: nothing breaks. The default mode keeps CLAUDE.md winning. Migrate when a second agent arrives, not before.
• Bedrock/Vertex/Foundry-pinned enterprises: native AGENTS.md support isn't flag-enabled for you yet. The @AGENTS.md import shim works today and is indistinguishable in effect — standardize on it until the flag reaches your provider.
• Teams with no AI-agent usage: an AGENTS.md with no agents is a README with worse SEO. Skip.
• Orgs with a strict central prompt function: managed-only mode drops AGENTS.md anyway. Your governance already chose; just document it.

Bottom Line

Claude Code reading AGENTS.md isn't a feature announcement; it's the end of the instruction-file format war. One open file, sixty tools, every major vendor. The work left is governance-shaped: pick your canonical file, wire it into CODEOWNERS and review policy, watch the external-@import surface, and scaffold it into golden paths before the copy-paste versions land. The agents are converging on a standard — the interesting question is whether your platform's review pipeline converges on treating that standard like the production configuration it now is.

Reference links: Claude Code changelog and memory/AGENTS.md docs, mods/agents-md source, agents.md spec & adoption registry, HN discussion.