Claude Code Now Reads AGENTS.md: The Cross-Tool Standard Finally Lands

On September 18, 2026, Claude Code version 2.1.277 shipped a feature the agent ecosystem has been waiting for: native support for AGENTS.md. The change was announced by Anthropic's Thariq on X — if a project folder has no CLAUDE.md, Claude Code now checks for and uses AGENTS.md instead. You can toggle the behavior in /config under "Project instructions."

This matters because AGENTS.md has emerged as the closest thing to a universal configuration format for AI coding agents. OpenAI's Codex, Google's Jules and Gemini CLI, Cursor, Aider, Devin, Windsurf, Amp, Zed, Warp, GitHub Copilot's coding agent, Factory, and over a dozen other tools all read it. Until now, Claude Code was the notable holdout.

What Changed

The implementation is deliberately conservative. Claude Code treats AGENTS.md as a fallback, not a merge target. The precedence order is:

CLAUDE.md (or CLAUDE.local.md) in the working directory or any ancestor
AGENTS.md in the working directory or any ancestor — only if no CLAUDE.md exists

This means you cannot layer AGENTS.md underneath a CLAUDE.md to share base conventions while keeping Claude-specific overrides. The moment a CLAUDE.md exists anywhere in the ancestor chain, AGENTS.md is ignored entirely.

You can override this in /config → Project instructions to load both, but the default is fallback-only. It's also not yet available on Bedrock, Vertex, or Foundry deployments — Anthropic's changelog notes this without a timeline.

Why the Fallback Design Matters

The fallback approach avoids a real problem: CLAUDE.md supports features AGENTS.md doesn't, notably @import statements for modular instruction files and tool-specific directives. If Claude Code merged both files, you'd get subtle conflicts — imported sections from CLAUDE.md would apply, but AGENTS.md has no equivalent mechanism. The fallback keeps the mental model simple: one instruction source wins.

For teams standardizing on AGENTS.md across tools, the practical workflow is:

Keep AGENTS.md at the repo root as the canonical cross-tool contract
Add a CLAUDE.md only when you need Claude-specific behavior (imports, hooks, custom slash commands)
When CLAUDE.md exists, it replaces AGENTS.md for Claude Code — so either put everything in CLAUDE.md or use the /config toggle to load both

Practical tip: If you adopt AGENTS.md as your primary format, consider a minimal CLAUDE.md that only contains @import statements pulling in shared modules, plus any Claude-only settings. That way the bulk of your conventions stay in the portable file.

What AGENTS.md Actually Standardizes

The AGENTS.md spec (hosted at github.com/agentsmd/agents.md) is intentionally minimal. It defines a plain Markdown file at the repository root with sections for:

Build & test commands — how to compile, lint, type-check, run tests
Code conventions — style, naming, architectural patterns
Boundaries — directories or files agents should not modify
Project context — enough orientation that a fresh session can be productive immediately

It does not standardize advanced features like model routing, tool permissions, or session persistence. Those remain tool-specific. The value is in the baseline — a new agent (or a new team member) can read one file and know how to build, test, and navigate the codebase without asking.

Migration Checklist for Existing Projects

If you already maintain a CLAUDE.md and want to adopt AGENTS.md for cross-tool compatibility:

Extract the portable subset — build commands, test commands, coding conventions, directory boundaries — into a new AGENTS.md at the repo root.
Slim down CLAUDE.md — keep only @imports, hook configurations, slash command definitions, and Claude-specific permissions.
Add a pointer in CLAUDE.md — a comment at the top noting "Shared conventions in AGENTS.md" helps future maintainers.
Test the fallback — temporarily rename CLAUDE.md, verify Claude Code picks up AGENTS.md, then restore.
Commit both — version control the config files so the whole team benefits.

What This Signals

Anthropic adopting AGENTS.md — even as a fallback — is a signal that the cross-tool convention has reached critical mass. When Codex, Cursor, Copilot, Gemini, and now Claude Code all read the same file, the instruction file stops being a proprietary lock-in mechanism and starts being a genuine interoperability layer.

For developers who switch between tools (Claude Code for complex refactors, Codex for quick tasks, Cursor for IDE integration), this reduces the configuration tax. You write the build commands and conventions once. Each tool layers its own extensions on top.

The fallback design also means adoption is non-breaking. Existing CLAUDE.md files keep working exactly as before. Teams can migrate at their own pace, or not at all.

What's Still Missing

No merge/overlay mode by default — you must opt in via /config
No support on Bedrock, Vertex AI, or Foundry yet
No standard for tool-specific extensions within AGENTS.md (though agent-spec is exploring this)
No built-in validator or linter for AGENTS.md structure

None of these are blockers. The core use case — one portable instruction file read by every major agent — now works in Claude Code.

If this was useful, you can support my open-source work on Ko-fi or check out my services.