Anthropic has added support for AGENTS.md to Claude Code, allowing the coding assistant to use the file as project instructions when a repository does not contain a CLAUDE.md file.
The change arrived with Claude Code 2.1.277, released on September 18, 2026. The release notes state that the new behavior can be changed under Project instructions in the /config menu. The feature is not yet available when Claude Code is used through Amazon Bedrock, Google Vertex AI or Microsoft Foundry.
Claude Code’s 2.1.277 release notes describe the change as a fallback: when a project has no CLAUDE.md, Claude Code reads AGENTS.md instead.
This distinction is important because the update does not simply make both files equivalent in every configuration. Existing projects that use CLAUDE.md can continue using it, while the project-instruction setting provides control over the file-selection behavior.
The new support addresses a long-running request from Claude Code users who work with more than one coding agent. Before the change, developers using AGENTS.md for other tools had to maintain a separate CLAUDE.md, duplicate their instructions, or use a workaround that pointed Claude Code to the shared file.
A Claude Code feature request opened on GitHub in March 2026 described AGENTS.md as a widely adopted, tool-agnostic convention used by Codex and other coding agents. The request argued that requiring a separate Claude-specific file created additional maintenance work and increased the risk that instructions would diverge between tools.
The GitHub feature request proposed either loading AGENTS.md as a fallback or reading it alongside CLAUDE.md with a defined precedence order.
Other Claude Code requests made a similar case. One request filed in August 2025 had attracted thousands of reactions before native support was added, while additional issues were opened in 2026 calling for compatibility with AGENTS.md and the broader agent-oriented file layout.
The original AGENTS.md feature request documents the history of that demand and the earlier workarounds used by developers.
AGENTS.md is primarily associated with repository-level instructions for coding agents. These files can contain information such as coding conventions, repository structure, testing requirements, development commands and project-specific rules.
OpenAI’s Codex documentation shows how the format is used in practice. Codex can apply AGENTS.md instructions according to the directory in which the file is located, with more deeply nested files taking precedence over broader instructions when conflicts occur.
OpenAI’s AGENTS.md documentation and the Codex implementation provide details on how Codex discovers and assembles these instructions.
The format has increasingly been used across coding-agent products, although describing it as a formal industry standard would be too strong. It is better understood as a growing de facto convention for portable project instructions.
That distinction is relevant because different tools can still interpret project instructions differently. Supporting the same filename does not mean that Claude Code, Codex and other agents have identical rules for precedence, discovery, skills, permissions or execution.
Claude Code’s implementation also arrives alongside a broader change in how the product can be extended. Anthropic team member Thariq Shihipar said the AGENTS.md behavior is implemented through Claude Code’s new mods system, opening the possibility of greater customization over how project instructions are handled.
Simon Willison’s report on Shihipar’s announcement records the explanation of the new support and its connection to the mods system.
Beyond AGENTS.md, version 2.1.277 also introduced a configuration option for Claude apps gateways operating behind forward proxies, added support for static upstream headers, and fixed several issues involving hung sessions and failed conversations.
The release fixed cases in which claude -p and Agent SDK sessions could hang without returning a result after an internal error. It also fixed failures involving empty text content blocks in conversations.
Anthropic’s change comes as developers increasingly use multiple AI coding systems on the same repositories. A shared repository instruction file can reduce the need to maintain separate copies of project rules, although teams still need to account for differences in how each tool interprets and applies those instructions.
The Register’s report said the change was welcomed by developers dealing with compatibility problems between coding-agent tools.
For projects that already use AGENTS.md without a CLAUDE.md, Claude Code 2.1.277 removes the need for a separate Claude-specific instruction file in the supported environments. For projects that already depend on CLAUDE.md, the release does not require an immediate change.
Discover more from Aree Blog
Subscribe now to keep reading and get access to the full archive.
