Anthropic added native AGENTS.md support to Claude Code 2.1.277, allowing the tool to apply cross-tool project instructions when no Claude-specific CLAUDE.md file exists. The feature uses a conservative fallback approach, prioritizing CLAUDE.md files and offering four instruction-loading modes through the /config menu. The implementation ships as a built-in mod using Anthropic's emerging extension mechanism, revealing plans to let developers customize the coding harness itself. This reduces friction for teams using multiple AI coding agents, eliminating the need for Claude-specific wrappers. The feature is not yet available through Amazon Bedrock, Google Vertex AI, or Microsoft Foundry.
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.
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.
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.context discovers the applicable project instructions and adds them to Claude’s initial context.
agent.spawn carries the instructions into forked agents and subagents.
tool.call watches file reads so that nested AGENTS.md files can be attached when Claude enters another part of the repository.
These hooks are visible in the mod’s TypeScript source. The feature is therefore more than a hard-coded filename alias. It is a context-loading policy implemented through Claude Code’s emerging extension layer.
The wider Claude Code mods documentation defines mods as plugins whose behavior is implemented through JavaScript or TypeScript hook modules. Anthropic currently labels the system early access, warns that the API can change without notice, and distinguishes it from a general-purpose marketplace.
Anthropic says developers will eventually be able to build custom versions of project instruction handling. In principle, the same mechanism could support an organization-specific filename, generated instructions, conditional context based on repository structure, or a loader that combines several formats according to internal policy. Those are plausible applications of the hook architecture, not announced built-in features.
No stable release date has been provided for general custom mod development. The published agents-md implementation should therefore be treated as a preview of Anthropic’s direction, rather than a promise that every part of the harness is ready for production customization.
The Rollout Still Has Provider and Migration Caveats
The release notes state that direct AGENTS.md support is not initially available for Claude Code sessions running through Amazon Bedrock, Google Vertex AI, or Microsoft Foundry. Anthropic’s documentation also explains that provider configuration, telemetry settings, and feature flags can affect availability. The first session after an upgrade may not receive the feature, while a subsequent session does.
Claude Code also does not list mod-loaded AGENTS.md files directly in /memory or /context. Users can verify loading through the session output, which reports when AGENTS.md is used because no CLAUDE.md was found. Asking Claude which project instructions are active provides another basic check.
Teams should remove older workarounds carefully. A CLAUDE.md file that imports AGENTS.md can remain without causing duplicate loading because its presence prevents the automatic fallback. A custom SessionStart hook that prints or injects AGENTS.md should be removed before enabling the built-in behavior, since that approach can load the same instructions twice. The official migration notes also cover symlinks and other compatibility setups.
How Teams Should Organize Project Instructions
There is no reason to rename a working CLAUDE.md merely because Claude Code supports another format. The best structure depends on which coding agents a repository must support.
Claude-only projects: Keep CLAUDE.md. It remains the first-class option and supports imports, scoped rules, and Claude-specific guidance.
Multi-agent projects with shared rules: Put the common instructions in AGENTS.md. Use a small CLAUDE.md importing it only when Claude needs additional behavior.
Projects already using only AGENTS.md: Upgrade to Claude Code 2.1.277 or later and use the default fallback, provided the selected model provider supports it.
Monorepos: Use nested AGENTS.md files for package-specific commands and conventions. Keep broad rules at the root and narrow details near the relevant code.
Managed enterprise environments: Confirm the organization’s selected instruction mode before assuming repository files will load.
Whichever file a team selects, concise and verifiable instructions work better than a large policy document. The file should name real commands, identify unusual repository constraints, and explain how changes are validated. It should not duplicate information that the agent can reliably infer from standard configuration files.
Final Thoughts
Native AGENTS.md support is a small compatibility feature with a useful architectural consequence. Anthropic is acknowledging that project instructions increasingly need to travel across AI coding tools, while preserving CLAUDE.md for teams that want Claude-specific control.
The mod implementation is the part worth watching. Claude Code currently decides how to discover files, assemble project context, pass instructions to subagents, and react to tool calls. Moving that behavior into an extension layer could let developers modify the harness instead of working around it with shell scripts and startup hooks.
For now, the practical win is simpler repository setup. The larger promise depends on whether Anthropic can stabilize mods, document their security model, and expose enough of the harness without making Claude Code configurations fragile across releases.
Frequently Asked Questions
5 questions
1
Does 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
Does AGENTS.md replace CLAUDE.md in Claude Code?
No. CLAUDE.md remains Claude Code’s preferred project instruction file under the default setting. AGENTS.md acts as a fallback when no project-level Claude file exists. Teams can also import AGENTS.md from CLAUDE.md or change the Project instructions setting to load AGENTS files exclusively or load both formats.
3
How do I enable AGENTS.md in Claude Code?
Upgrade to Claude Code 2.1.277 or later and place AGENTS.md in the project. The default mode should load it automatically when no project CLAUDE.md exists. To change the behavior, run /config, find Project instructions, and select the AGENTS-only, CLAUDE-only, fallback, or load-both mode.
4
Can Claude Code load CLAUDE.md and AGENTS.md together?
Yes. Select CLAUDE.md and AGENTS.md under Project instructions, or explicitly import AGENTS.md from a CLAUDE.md file with @AGENTS.md. In the configurable load-both mode, Claude Code loads the Claude files first and then the AGENTS files. Under the default mode, it chooses one project instruction system instead of merging both.
5
What are Claude Code mods?
Claude Code mods are early-access plugins implemented with JavaScript or TypeScript hook modules. They can respond to events inside the coding harness, including prompt construction, agent creation, and tool calls. Anthropic built AGENTS.md support as a bundled mod, but warns that the broader mods API can change and is not yet a stable plugin marketplace.
