Anthropic added native AGENTS.md support to Claude Code 2.1.277 on September 18, 2026. When a project does not contain a CLAUDE.md instruction file, Claude Code can now find and apply instructions from AGENTS.md instead.
The immediate benefit is straightforward: teams using several AI coding agents no longer need a Claude-specific wrapper solely to expose the same project rules to Claude Code. Existing CLAUDE.md configurations still take precedence by default, preventing an upgrade from unexpectedly merging two potentially conflicting instruction sets.
The more consequential part is how Anthropic implemented the feature. AGENTS.md support ships as a built-in Claude Code mod, using the same forthcoming extension mechanism intended to let developers customize the coding harness itself.
Claude Code 2.1.277 Adds Native AGENTS.md Support
Anthropic announced the feature in a post explaining that Claude Code would check for AGENTS.md when no CLAUDE.md was available. The post also confirmed that users can control the behavior through the /config menu. The announcement’s reference to “today” meant September 18, 2026.
The official release notes describe the feature as native support for AGENTS.md, with automatic fallback and explicit configuration options. Claude Code users who already rely on a small CLAUDE.md file containing @AGENTS.md do not need to change it immediately. The wrapper continues to work, although it is no longer necessary for installations that receive the direct support.
This is not a new instruction format created by Anthropic. AGENTS.md is an open convention designed to give AI coding tools a predictable place to find repository-specific information, including build commands, testing procedures, coding conventions, architecture notes, and pull request requirements.
Claude Code Uses AGENTS.md Only as a Fallback
The default behavior is deliberately conservative. Claude Code does not automatically combine CLAUDE.md and AGENTS.md, nor does it decide between them independently in every directory.
At session startup, Claude Code searches from the working directory toward the project root. If it finds any project-level CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md along that path, it uses the existing Claude instruction system and does not load project-level AGENTS.md files. If none of those files exists, it loads AGENTS.md and .claude/AGENTS.md files from the same directory hierarchy.
| Project configuration | Default Claude Code behavior |
|---|---|
Only AGENTS.md exists | Load AGENTS.md |
Only CLAUDE.md exists | Load CLAUDE.md |
| Both files exist | Load CLAUDE.md and ignore AGENTS.md |
CLAUDE.md imports @AGENTS.md | Load both through the explicit import |
CLAUDE.local.md exists | Treat it as a Claude project file and skip fallback |
| Neither file exists | Continue without project-level instructions |
The distinction matters because the announcement’s “if there is no CLAUDE.md in a folder” wording can sound like a per-directory merge rule. In the default mode, the initial choice applies across the project path. A root-level CLAUDE.md is enough to keep Claude Code on its established instruction system.
User-level instructions in ~/.claude/CLAUDE.md, organization-managed policies, .claude/rules/, and auto memory do not prevent the fallback. They remain active alongside whichever project instruction format Claude Code selects.
Nested instructions also work. When Claude reads a file in a deeper subdirectory, the mod can attach a nearby AGENTS.md or .claude/AGENTS.md that applies to that part of the repository. More specific instructions take precedence when nested files conflict, matching the hierarchical model promoted by the wider AGENTS.md convention.
One Shared Instruction File Reduces Cross-Tool Friction
The AGENTS.md specification describes the file as a README for AI coding agents. It keeps machine-facing instructions separate from the human-focused project README and supports additional files inside subprojects or monorepo packages.
Before Claude Code 2.1.277, a team standardizing on AGENTS.md generally had to add a Claude-specific bridge:
@AGENTS.md
That bridge was not difficult to maintain, but it created another file whose only purpose was compatibility. Native fallback removes it for repositories that have no additional Claude-specific requirements.
Projects that do need Claude-specific guidance can still use the import pattern. A practical arrangement is to put shared commands, architecture, testing rules, and style conventions in AGENTS.md, then create a short CLAUDE.md that imports those rules and adds Claude-only instructions:
@AGENTS.md
## Claude Code Instructions
Use the project's existing verification commands before committing.
Ask before modifying generated files.
This structure makes the common rules available to multiple AI agents without giving up Claude Code’s file imports or its more specific instruction features. It also avoids maintaining two independent copies of the same commands, which can gradually diverge.
The Config Menu Offers Four Instruction Modes
Claude Code’s /config menu now includes a Project instructions setting. For normal repository files, the official project-memory documentation defines four loading modes. A separate managed-only option is available for organizations that want to suppress repository-level instructions entirely.
| Setting | Result |
|---|---|
CLAUDE.md or AGENTS.md | Use Claude files when present; otherwise fall back to AGENTS.md |
CLAUDE.md | Load Claude instruction files and ignore AGENTS.md |
AGENTS.md | Load AGENTS.md even when Claude files exist |
CLAUDE.md and AGENTS.md | Load both formats, with Claude files loaded first |
only managed instructions | Exclude repository files and use organization-managed instructions |
The load-both option is useful during migration or when the two formats intentionally contain different guidance. Teams should still check for overlapping or contradictory rules because loading more instruction files is not automatically better. Duplicate commands consume context and can make agent behavior less predictable.
The AGENTS.md-only option serves a different purpose. It allows a team to standardize on the cross-tool format even when an older CLAUDE.md remains in the repository. Conversely, organizations that do not want third-party repository instructions can explicitly retain the Claude-only or managed-only modes.
The Built-In Mod Reveals Anthropic’s Larger Plan
Anthropic published the built-in AGENTS.md mod in the Claude Code repository. Although the source is visible as a plugin-style directory, Anthropic notes that the runtime implementation ships inside the Claude Code binary. The published files document how the built-in behavior is structured.
The implementation uses several hook points:
prompt.contextdiscovers the applicable project instructions and adds them to Claude’s initial context.agent.spawncarries the instructions into forked agents and subagents.tool.callwatches file reads so that nested files can be attached when Claude enters another part of the repository.
Frequently Asked Questions
5 questions
1Does Claude Code support AGENTS.md?
Yes. Claude Code 2.1.277 added native AGENTS.md support on September 18, 2026. In the default configuration, Claude Code loads AGENTS.md when it cannot find a project-level CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md between the working directory and project root.
2
Sources
- Claude Code 2.1.277github.com
- https://x.com/trq212/status/2101009392611278961x.com
- claude-code/mods/agents-md at main · anthropics/claude-codegithub.com
- AGENTS.md specificationagents.md
- How Claude remembers your project - Claude Code Docscode.claude.com
- the mod’s TypeScript sourcegithub.com
- Claude Code mods documentationgithub.com
- official migration notes
