Claude Code adds AGENTS.md support as configurable fallback for project instructions

Known version: Claude Code v2.1.277 or later. Anthropic’s docs explicitly require this version for direct AGENTS.md reading. How Claude remembers your project - Claude Code Docs

Known capability: By default, Claude Code reads AGENTS.md only when no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists in the working directory or above it. User-level ~/.claude/CLAUDE.md, organization-managed CLAUDE.md, and .claude/rules/ do not block the AGENTS.md fallback. How Claude remembers your project - Claude Code Docs

Configuration access: Users can change the behavior through /config under Project instructions, with documented values: claude-md-or-agents-md as default, claude-md-and-agents-md, claude-md, and managed-only. The same can be configured via the built-in agents-md@builtin plugin configuration in user, --settings, or managed settings; project and local settings are ignored for this plugin option. How Claude remembers your project - Claude Code Docs

Unavailable or limited cases: Anthropic says AGENTS.md support is unavailable before v2.1.277, in sessions that do not fetch feature flags from Anthropic—such as Amazon Bedrock or another third-party provider, or when telemetry is disabled—on the first session after install/upgrade, when relevant hooks/plugin restrictions are set, or if the built-in agents-md plugin is disabled. How Claude remembers your project - Claude Code Docs

Exact model: Not specified in the story or documentation. This is a Claude Code harness behavior, not a documented model release.

The implementation is notable because Anthropic is using a built-in plugin/mod rather than only hard-coding the behavior into the core CLI. The public mods/agents-md README says AGENTS.md is read “the way Claude Code reads CLAUDE.md,” under a single option named instructionFiles. The default mode, claude-md-or-agents-md, loads AGENTS.md only when the project has no own instruction files recognized as CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md; the claude-md-and-agents-md mode loads both while avoiding duplicate loading for imported or symlinked files. claude-code/mods/agents-md at main · anthropics/claude-code · GitHub

Architecturally, the mod participates in prompt-context construction. The GitHub README says the engine provides instruction files behind claudeMd to a prompt.context hook; the hook can answer with a changed list; then the engine renders those files with its normal framing and downstream omission rules. That means an AGENTS.md added by this plugin becomes, downstream, a project instruction file rather than a separate memory mechanism. claude-code/mods/agents-md at main · anthropics/claude-code · GitHub

Implementation implications:

• Fallback is not merge-by-default. Existing Claude-first repositories with CLAUDE.md will not automatically read AGENTS.md unless configured to do so or unless CLAUDE.md imports it. How Claude remembers your project - Claude Code Docs
• CLAUDE.local.md can unexpectedly suppress AGENTS.md. Anthropic explicitly warns that adding local personal instructions in CLAUDE.local.md in a project relying on AGENTS.md stops default direct AGENTS.md loading; use claude-md-and-agents-md if both are needed. How Claude remembers your project - Claude Code Docs
• Directly loaded AGENTS.md is less visible in some introspection surfaces. Anthropic says a directly loaded AGENTS.md is not listed in /memory or the Memory files list in /context; users must look for the “AGENTS.md loaded” line or ask Claude what project instructions it received. How Claude remembers your project - Claude Code Docs
• Direct AGENTS.md has different hook/import behavior. Anthropic documents differences from CLAUDE.md: InstructionsLoaded hooks do not fire for directly loaded AGENTS.md; --add-dir does not load added directories’ AGENTS.md; and external imports load only if previously approved. How Claude remembers your project - Claude Code Docs

Reproducibility is stronger than a pure vendor announcement because the agents-md mod source and tests are publicly referenced in the Anthropic GitHub repository, and the documented settings provide a concrete way to reproduce each loading mode. However, no cited source provides an independent black-box test matrix across operating systems, provider routes, symlinks, monorepos, and disabled-telemetry environments. claude-code/mods/agents-md at main · anthropics/claude-code · GitHub

Repository instruction files have become part of the agentic coding stack: they encode build commands, coding conventions, architecture notes, testing workflows, and workflow constraints. A June 2026 paper characterizes coding agents as a combination of a language model and harness, where the harness runs the agent loop, executes tools, and injects configuration files into context. Configuration Smells in AGENTS.md Files: Common Mistakes in Configuring Coding Agents

Empirical evidence remains unsettled. Lulla et al. studied 10 repositories and 124 pull requests under with/without-AGENTS.md conditions, reporting lower median runtime and reduced output-token consumption while maintaining comparable task completion behavior. That supports a cost/latency hypothesis, not necessarily a correctness hypothesis. On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents

Khatri’s later controlled ablation studied Claude Code and Codex across real repository tasks and found that context strategy did not measurably move correctness within its bounds; the paper argues failures were usually due to implementation skill rather than missing repository knowledge. This conflicts with simplistic claims that adding AGENTS.md will automatically make agents “better.” Do Context Files Help Coding Agents? A Two-Agent Ablation Study on Real Repositories

Dos Santos et al. add a governance caution: in 100 popular repositories with AGENTS.md or CLAUDE.md, they found widespread configuration smells including lint leakage, context bloat, skill leakage, and conflicting instructions. This is directly relevant to Claude Code’s new support because easier reuse of AGENTS.md also makes poor instructions easier to propagate across tools. Configuration Smells in AGENTS.md Files: Common Mistakes in Configuring Coding Agents

The main limitation is that the feature changes which text enters context, not whether the model obeys that text. Anthropic explicitly states that CLAUDE.md-style content is contextual guidance; vague or conflicting instructions may not be followed, and mandatory controls should use hooks, permissions, sandbox settings, or other managed settings. How Claude remembers your project - Claude Code Docs

Security and governance risks include accidental loading of stale instructions, duplicated context through old workarounds, and invisible divergence between tools. Anthropic advises removing prior SessionStart-hook workarounds that print AGENTS.md, because direct loading plus hook injection can duplicate the file in context. It also notes Windows symlink pitfalls and recommends @AGENTS.md imports where symlinks are unreliable. How Claude remembers your project - Claude Code Docs

The evidence base does not justify performance claims. There is no cited Anthropic benchmark showing that native AGENTS.md support improves Claude Code task success, and independent research is mixed: efficiency gains in one study, bounded-null correctness results in another. On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents

For engineering leaders, this reduces configuration friction in multi-agent environments. Teams can standardize on AGENTS.md for shared repository instructions and use CLAUDE.md only where Claude-specific behavior is needed. The safest migration path is to audit existing CLAUDE.md shims, imports, symlinks, and hooks before deleting anything. Anthropic says a CLAUDE.md containing @AGENTS.md can remain safely because Claude will not read the same content twice under documented modes. How Claude remembers your project - Claude Code Docs

For platform teams, the governance pattern is: put broad policy in managed settings or managed CLAUDE.md, put project conventions in AGENTS.md/CLAUDE.md, keep files concise, and use hooks/settings for actions that must be enforced. Anthropic’s docs distinguish behavioral guidance from enforced settings such as permissions, sandbox isolation, provider routing, and login restrictions. How Claude remembers your project - Claude Code Docs

For developers, the immediate checklist is:

1. Upgrade Claude Code to v2.1.277 or later.
2. Run a session and verify whether AGENTS.md loaded.
3. If both files are needed, set Project instructions to claude-md-and-agents-md.
4. Remove old hooks that inject AGENTS.md into context.
5. Review AGENTS.md for bloat, duplicated lint rules, stale commands, and contradictions.