Claude Code Adds Configurable AGENTS.md Support

Claude Code 2.1.277 adds support for AGENTS.md project instructions. When a project has no CLAUDE.md, Claude Code can now read AGENTS.md instead, and the behavior can be changed from the Project instructions setting in /config. (Claude Code team member Thariq on X; Claude Code v2.1.277 release)

This is a fallback, not a rename of Claude Code's existing file. The default built-in mod checks whether the project has its own CLAUDE.md before adding AGENTS.md, so a repository does not silently switch instruction sources just because it updates Claude Code. (Anthropic's agents-md mod source; agents-md README)

Key Takeaways

• Claude Code 2.1.277 reads AGENTS.md as a fallback when a project has no CLAUDE.md.
• The behavior is configurable from /config under Project instructions.
• The built-in mod has multiple modes, including fallback, Claude-only, both file types, and managed-only instructions.
• CLAUDE.md still wins in the default fallback mode when a project has its own file.
• It works on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, and LLM gateways since v2.1.281, after launching without them.
• A CLAUDE.local.md counts as a CLAUDE.md, so adding one stops Claude Code from reading AGENTS.md in the default mode.
• Anthropic published the built-in mod's source, including its hook implementation and tests.

A Shared Fallback, Not a Forced Migration

Claude Code has historically looked for CLAUDE.md files in the project tree. The 2.1.277 change makes AGENTS.md usable without asking every repository to add a second Claude-specific file. The release's wording is deliberately narrow: if a project has no CLAUDE.md, Claude Code reads AGENTS.md instead. (Claude Code v2.1.277 release)

That default matters for existing repositories. A project that already has a CLAUDE.md does not begin loading AGENTS.md merely because Claude Code was updated. The published mod README says the default claude-md-or-agents-md mode stands down when the project has a CLAUDE.md of its own, leaving that file to the Claude Code engine. (agents-md README)

One file trips people up. Claude Code's memory docs say a CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in your working directory or any directory above it counts for that check. Adding a personal CLAUDE.local.md to a project that relies on AGENTS.md therefore stops Claude from reading AGENTS.md for you. To keep both, set Project instructions to claude-md-and-agents-md. (Claude Code docs, memory)

The practical effect is a low-friction adoption path: repositories that already carry an AGENTS.md can let Claude Code use it when no Claude-specific instruction file exists, while repositories with an intentional CLAUDE.md keep their current default behavior. That is a compatibility layer, not a deprecation notice for CLAUDE.md.

Four Project-Instruction Modes

The source for the built-in mod documents four values for the instructionFiles option. The default is claude-md-or-agents-md, which uses AGENTS.md only when the project has no CLAUDE.md of its own. (agents-md README)

The other modes make the policy explicit:

• claude-md keeps the existing Claude-only behavior. The mod adds nothing.
• claude-md-or-agents-md uses AGENTS.md as the fallback when the project's own CLAUDE.md is absent.
• claude-md-and-agents-md loads both kinds of project instruction files through the mod's documented walk.
• managed-only removes project, local, and user instruction files while retaining managed policy and memory files.

Users change the setting in /config under Project instructions. The README also documents the corresponding pluginConfigs entry for people managing the option in settings.json. (agents-md README)

The distinction between fallback and both-files mode is important. A team that wants one shared instruction file can use the default fallback. A team that deliberately maintains Claude-specific guidance alongside a cross-tool file can opt into the mode that loads both, then review the resulting instruction order and overlap.

What the Built-In Mod Adds

Anthropic's implementation is not only a filename check. The published source describes a built-in mod that hooks into Claude Code's context flow. It can walk project ancestors for AGENTS.md, add those files as project instruction files, and attach nested AGENTS.md files when Claude reads files in subdirectories. (agents-md README)

The source also includes a mods/agents-md package with a plugin manifest, hooks, tests, and a README. The README says the mod's session.start, prompt.context, agent.spawn, and tool.call hooks handle the configuration row, instruction-file discovery, fork behavior, and nested files. (Anthropic's agents-md mod source)

That makes the feature notable beyond the immediate compatibility behavior. Thariq described it as a built-in mod and said users will be able to build custom versions of project instructions themselves. The public source gives developers a concrete example of how that customization layer is structured. (Thariq on X; agents-md README)

Availability and Upgrade Notes

The release entry identifies the change as part of Claude Code v2.1.277, and at launch it said the feature was not yet available on Bedrock, Vertex, or Foundry. Claude Code v2.1.281, released September 23, 2026, changed that: AGENTS.md support now also works on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways, and sessions with telemetry disabled. On older versions those sessions read CLAUDE.md only, so update Claude Code or import AGENTS.md from a CLAUDE.md. (Claude Code changelog; Claude Code docs, memory) Users on supported Claude Code installations can change the behavior under /config rather than editing a separate configuration file as their first step. (Claude Code v2.1.277 release)

If a repository already uses CLAUDE.md, the safest first check is to leave the default fallback mode in place and confirm that Claude Code continues to use the intended file. If a repository has only AGENTS.md, the update creates a path to use those instructions without duplicating them into a second file. If both files should apply, select the explicit both-files mode and review the project's instruction boundaries before relying on it. (agents-md README)

Bottom Line

Claude Code 2.1.277 turns AGENTS.md into a supported project-instruction fallback without forcing existing repositories to abandon CLAUDE.md. The built-in mod keeps the default conservative, exposes an explicit both-files mode for teams that need it, and publishes the implementation for developers interested in customizing the Claude Code harness. (Claude Code v2.1.277 release; agents-md README)

Corrections and Updates

• October 9, 2026: This page said AGENTS.md support was not yet available on Bedrock, Vertex, or Foundry. The Claude Code 2.1.281 changelog, September 23, 2026, says it now also works on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways, and sessions with telemetry disabled. (Claude Code changelog)

Sources

• Thariq, “We're adding support for AGENTS.md to Claude Code,” X, September 18, 2026: https://x.com/trq212/status/2101009392611278961
• Thariq, “AGENTS.md support is built off of Claude Code mods,” X, September 18, 2026: https://x.com/trq212/status/2101009393731223817
• Anthropic, Claude Code v2.1.277 release notes: https://github.com/anthropics/claude-code/releases/tag/v2.1.277
• Anthropic, agents-md built-in mod source: https://github.com/anthropics/claude-code/tree/main/mods/agents-md
• Anthropic, agents-md README: https://github.com/anthropics/claude-code/blob/main/mods/agents-md/README.md
• Anthropic, Claude Code changelog, v2.1.281 (September 23, 2026), checked 2026-10-09: https://code.claude.com/docs/en/changelog
• Anthropic, Claude Code docs, "How Claude remembers your project" (AGENTS.md section), checked 2026-10-09: https://code.claude.com/docs/en/memory#agents-md