Anthropic released Claude Code 2.1.277 on Sept. 18 U.S. time, and the first item in the changelog was support for AGENTS.md. Starting with this version, Claude Code will read AGENTS.md when a project does not contain CLAUDE.md. Users can also change the Project instructions setting in /config so the tool reads both files.
Anthropic said the feature does not currently apply to three cloud channels: Amazon Bedrock, Google Vertex AI, and Microsoft Foundry.
AGENTS.md had already spread across open-source projects
AGENTS.md is a project instruction file written for AI coding agents. It typically includes build commands, testing methods, and coding standards that an agent reads before starting work. CLAUDE.md serves the same purpose, but was designed specifically for Claude Code.
OpenAI introduced AGENTS.md in August 2025, then donated it in December that year to the Agentic AI Foundation, or AAIF, a newly formed foundation under the Linux Foundation. AAIF said at the time that more than 60,000 open-source projects and agent frameworks had adopted the format, with support from Codex, Cursor, Gemini CLI, and GitHub Copilot.
Anthropic’s own MCP, short for Model Context Protocol, was donated to AAIF on the same day, and Anthropic is also a platinum member of the foundation. By the timeline cited in the report, Claude Code took another nine months after that point to begin reading AGENTS.md. Developers had already opened GitHub requests for support in August 2025.
Shopify’s CEO had publicly objected to the CLAUDE.md-only approach
At the end of August, Shopify CEO Tobi Lütke said publicly that he was considering banning Claude Code at Shopify 「until they change their mind and read AGENTS.md and .agents/skills files」. He said insisting on CLAUDE.md alone could leave teams using different tools with two separate sets of rules, which he called 「totally unnecessary」.
Lütke later added that Shopify has thousands of developers working in the same monorepo. Both instruction file types can apply step by step along the directory tree, he said, and some directory will inevitably miss one of them. 「This means some developers are working in a lobotomized state,」 he said. Shopify currently uses automation to patch over the issue, which Lütke described as 「a stupid complexity tax we should not be paying」.
According to the report’s summary, the support rollout came 24 days after Lütke’s Aug. 25 threat to ban the tool.
Anthropic had argued that model families were not interchangeable
Claude Code engineer Thariq Shihipar responded later the same day, saying the team was making Claude Code easier to customize. He said users would be able to use AGENTS.md directly and also modify other system prompts.
He explained that Claude Code had read only CLAUDE.md because Anthropic believed 「different model families are not interchangeable, and system prompts have a large impact on performance」. Claude Code also maintains different system prompts internally for different models.
In that reply, Shihipar linked to his own July 24 post. In it, he said Anthropic had removed about 80% of Claude Code’s system prompts for a new generation of models, then documented how prompts, Skills, and CLAUDE.md should be written. He also acknowledged that this required substantial maintenance and 「not everyone will think it’s worth it」. In the short term, he suggested that users import AGENTS.md inside CLAUDE.md with 「@AGENTS.md」.
Support was implemented as a built-in mod, with source code published on GitHub
When announcing the update on Sept. 18, Shihipar said AGENTS.md support had been built using Claude Code’s mods system. Mods are an upcoming mechanism from Anthropic for customizing how Claude Code behaves. He said this AGENTS.md support was delivered as a built-in mod, and developers will later be able to create different ways of loading project instructions based on their own needs.
The announcement post drew more than 2.73 million views, according to the report.
Anthropic also published the source code for the agents-md mod on GitHub. The same directory includes three other built-in mods: diff, telemetry, and sec-default. Documentation lists four modes:
- Read only CLAUDE.md
- Read AGENTS.md only when CLAUDE.md is absent, which is the default
- Read both files
- Keep only centrally distributed enterprise instruction files
The documentation says this option must be written into a user or enterprise configuration file. Configuration files inside the project directory are not read for this setting.
Default behavior still prefers CLAUDE.md when it exists
Under the documented default mode, if any CLAUDE.md exists between the repository root and the working directory, Claude Code will not read AGENTS.md. For repositories like Shopify’s, where both file types coexist, users need to switch to the mode that reads both files in order to apply rules from each side.
That mode will skip any AGENTS.md file that has already been imported or linked by CLAUDE.md, so the same content is not loaded twice.
FAQ answer: yes, Claude Code can now read AGENTS.md
On the question of whether Claude Code can read AGENTS.md, the report’s answer was yes. From version 2.1.277 onward, Claude Code automatically switches to AGENTS.md when a project has no CLAUDE.md, and users can also configure it to read both through Project instructions in /config. The feature still does not apply to Bedrock, Vertex, or Foundry.