Claude Code Now Reads AGENTS.md, Falling Back From CLAUDE.md

Anthropic shipped AGENTS.md support in Claude Code 2.1.277 on September 18, 2026, announced by Claude Code team member Thariq: if a folder has no CLAUDE.md, Claude Code now checks for and uses AGENTS.md instead — the emerging cross-tool convention already adopted by Codex, Cursor, and a growing list of other agent harnesses. It's a small, practical fix for a real annoyance (maintaining duplicate config files across tools), and it's also the first public, shipped example of Claude Code Mods, Anthropic's new system for customizing the harness itself.

TL;DR

The problem this actually solves

Project-level instructions for coding agents have splintered across tools over the past year — Claude Code reads CLAUDE.md, other harnesses have adopted AGENTS.md as a shared, tool-agnostic convention meant to work the same way across Codex, Cursor, and others without each vendor requiring its own file. A team using more than one coding agent across their workflow — a common reality, not an edge case, as explainx.ai's own coverage comparing Claude Code, Codex, Gemini CLI, and GLM reflects — previously had to either maintain two nearly-identical files in parallel and keep them manually synced, or pick one tool's convention and accept that any other tool in the stack wouldn't pick up the same project context automatically.

This change removes that duplication for the common case: a project that's already standardized on AGENTS.md for cross-tool compatibility doesn't need a separate CLAUDE.md purely so Claude Code also gets the same instructions — Claude Code will now read the shared file directly. CLAUDE.md remains the preferred file when both exist, and still supports Claude-Code-specific capabilities (like file imports) that a generic cross-tool file isn't designed to carry — so this is a fallback for simplicity, not a deprecation of the Claude-specific format.

Built as a Claude Code Mod, not a core feature

The more structurally interesting detail is how Anthropic shipped this. Thariq's own follow-up post: "AGENTS.md support is built off of Claude Code mods, our upcoming way to customize the Claude Code harness. This is a built-in mod, but you'll be able to build custom versions of project instructions yourself as you'd like too." That connects directly to Claude Code Mods, which explainx.ai covered when Anthropic's Boris Cherny first announced the system via a GitHub issue in mid-September 2026 — a customization layer distinct from the existing skills system, aimed at extending the interactive session surface and harness behavior itself, not just the model's capability set.

Shipping AGENTS.md support as a mod, rather than hard-coding it into Claude Code's core, is a meaningful signal about Anthropic's own intended use of the mod system: rather than keeping mods purely as a community/third-party extension mechanism, Anthropic is using the same system for its own first-party features, and publishing the source as a public, concrete reference implementation. Anyone building their own custom mod now has a real, working example — not just documentation — of a mod that changes how Claude Code discovers and loads project configuration, published at anthropics/claude-code/tree/main/mods/agents-md.

The reaction

The response, based on the visible replies, was straightforwardly positive — a rarer thing for a Claude Code feature launch than the usual mix of praise and pointed critique. Guillermo Rauch (Vercel CEO) and Tibo (Lovable) both posted brief approving replies; one developer's reply — "i can finally delete this" — captures the practical relief this solves directly: one less duplicated file to maintain per project for anyone running multiple agent harnesses side by side.

Why fallback, not replacement, is the right design choice

It's worth being explicit about why Anthropic chose a fallback pattern (only reading AGENTS.md when CLAUDE.md is absent) rather than either ignoring AGENTS.md entirely or merging both files' instructions together. A pure merge would introduce real ambiguity — if a CLAUDE.md and an AGENTS.md in the same folder gave contradictory instructions, which one wins, and how would a user debug that without reading both files carefully every time? A fallback avoids that ambiguity by making the precedence rule simple and predictable: CLAUDE.md always wins when present, AGENTS.md is used only when there's nothing more specific to Claude Code to fall back on. That's a conservative design choice that trades some flexibility (you can't easily layer Claude-specific additions on top of a shared AGENTS.md without fully duplicating it into a CLAUDE.md) for predictability, which is generally the right tradeoff for a file that directly shapes what an autonomous agent does in your codebase — an ambiguous merge rule is exactly the kind of thing that produces confusing, hard-to-debug agent behavior when two config files quietly disagree with each other.

This also mirrors a broader pattern worth naming: as the number of AI coding agents in a typical team's toolchain grows — explainx.ai's own comparison of Claude Code, Codex, Gemini CLI, and GLM covers four popular options, and that's before counting newer entrants — the industry is visibly converging on shared conventions for the boring, unglamorous parts of agent tooling (how config files are named and discovered) even while each vendor still competes hard on the actual model and harness capability underneath. That's a healthy sign for anyone worried about full lock-in to one vendor's specific file format; the convergence on AGENTS.md as a shared standard, with vendors like Anthropic now supporting it as a fallback rather than requiring their own format exclusively, reduces the switching cost of trying a second or third agent harness alongside whichever one a team already uses as its primary.

Why this is a small feature with an outsized signal

It's worth noting why a fallback file-lookup rule, on its own a genuinely minor technical change, is worth this much attention: it's a concrete data point on how the major AI coding agent vendors are choosing to compete going forward. Rather than treating project configuration format as a lock-in mechanism — forcing users to standardize on one vendor's specific file to get full functionality — Anthropic chose interoperability for this particular piece of the stack, at essentially zero cost to its own product's differentiation, since the actual competitive advantage lives in the model quality, the harness's tool integrations, and the broader Claude Code feature set, not in which markdown filename a project happens to use. That's a meaningfully different posture than treating every piece of the stack as a wall meant to keep users inside one ecosystem, and it's a signal worth watching for from other vendors on similarly low-stakes, high-friction interoperability questions going forward.

Honest limitations

• This is a fallback, not a merge — if a folder has both CLAUDE.md and AGENTS.md, Claude Code reads only CLAUDE.md; there's no described mechanism for combining instructions from both files.
• Claude-Code-specific directives in AGENTS.md aren't guaranteed to work — since AGENTS.md is a generic, cross-tool format, any Claude-Code-specific syntax or imports that only CLAUDE.md supports may not function the same way when Claude Code reads a plain AGENTS.md file.
• The broader custom-mods system isn't generally available yet — this is a built-in, Anthropic-shipped mod; the announcement frames general custom-mod building as "upcoming," not yet fully open to arbitrary user-built mods.
• No detail on how folder-level precedence works in nested directories — whether a CLAUDE.md in a parent directory overrides an AGENTS.md in a subdirectory, or vice versa, isn't specified in the announcement.

What this means for builders

If your team runs more than one coding agent across different tools — a common setup for teams evaluating or mixing Claude Code, Codex, and other harnesses — this is worth adopting immediately: standardize on AGENTS.md for shared, tool-agnostic project instructions, and only add a CLAUDE.md when you specifically need Claude-Code-only directives (imports, hooks-adjacent configuration) that the generic format doesn't support. For anyone interested in building their own Claude Code customizations, the published mod source is worth reading directly as a template — it's a genuine reference implementation from the team that built the mod system, not just documentation describing one in the abstract. And for teams currently maintaining separate, manually-synced config files across two or more agent tools specifically to avoid missing out on any one tool's capabilities, this is a good moment to consolidate: audit which of your current CLAUDE.md directives are actually Claude-Code-specific versus generically applicable project instructions any agent could use, and move the generic ones into a shared AGENTS.md now rather than continuing to maintain the duplication indefinitely, which pays off the moment a second team member starts using a different agent harness on the same codebase.

Related on explainx.ai

• Claude Code Mods: community extensions, explained
• Agent Markdown files: the complete guide (CLAUDE.md, AGENTS.md, and more)
• What is CLAUDE.md? Persistent memory for Claude Code
• Claude Code vs. Codex vs. Gemini CLI vs. GLM 5.2
• Claude Code commands: complete slash command reference
• Claude Code Projects: one conversation coordinates parallel cloud threads
• Official source: GitHub — anthropics/claude-code/mods/agents-md

This post is sourced to Anthropic's own September 18, 2026 announcement (Thariq, on X) and the published mod source on GitHub. Feature behavior reflects Claude Code 2.1.277 as announced; verify current behavior against the official docs before relying on exact defaults.