Claude Code 2.1.277 Adds AGENTS.md Fallback, Not Merge

The Register first reported the move as Anthropic adopting OpenAI’s Markdown-based instruction mechanism. The more consequential detail is in Anthropic’s own changelog and the open-source implementation: a repository that already has CLAUDE.md will not automatically start consuming AGENTS.md under the default behavior. For existing Claude Code projects, the update is deliberately conservative.

That avoids surprising behavior changes, but it means administrators and maintainers should not mistake this release for instant cross-tool standardization. Teams that maintain both files today still need to decide whether to migrate, retain Claude-specific instructions, or explicitly configure Claude Code to read both sets.

Claude Code’s default is compatibility, not consolidation​

Anthropic says version 2.1.277 reads AGENTS.md “instead” in a project with no CLAUDE.md; the behavior can be changed in the Project instructions area of Claude Code’s /config command. The feature is also unavailable for Claude Code deployments through Amazon Bedrock, Google Vertex AI, and Microsoft Foundry at launch.

The distinction between “fallback” and “merge” is the part that changes operational planning. A development team may have assumed that adding an AGENTS.md file to a repository would immediately give every supported coding agent the same policy, build commands, test requirements, and secure-development rules. It will for tools that already prioritize that file, but a Claude Code session running with the default setting will continue to follow CLAUDE.md wherever that file exists.

Anthropic’s published source for the built-in feature shows several possible modes: Claude-only instructions, CLAUDE.md-or-AGENTS.md, a mode that reads both, and a managed-only option. The default fallback mode also detects a project-level CLAUDE.md before standing down from AGENTS.md. In practical terms, a stale CLAUDE.md can remain the effective policy even after a team has started treating AGENTS.md as its shared source of truth.

That is a sensible backward-compatibility choice. It is also a predictable source of policy drift if the migration is treated as a rename rather than a configuration change.

AGENTS.md has a neutral home, even if OpenAI started it​

Calling AGENTS.md “OpenAI’s format” is historically accurate but now incomplete. The Linux Foundation announced in December 2025 that OpenAI had contributed the project to the Agentic AI Foundation, alongside Anthropic’s Model Context Protocol and Block’s Goose framework. The foundation describes AGENTS.md as a simple Markdown convention for passing repository-specific guidance to coding agents.

The format is intentionally light. It has no mandatory schema or set of fields: a project can put development environment details, build commands, test procedures, coding rules, pull-request conventions, and security notes in ordinary Markdown. The AGENTS.md project says nested files can tailor instructions for individual packages in a large repository, with the closest relevant file taking precedence.

That flexibility has helped it spread. The Linux Foundation said at its launch that more than 60,000 open-source projects had adopted it, and listed GitHub Copilot, Codex, Cursor, Devin, Gemini CLI, Jules, VS Code, and several other agent products or environments as adopters. Microsoft is also a platinum member of the Agentic AI Foundation, which makes this more than a détente between two model vendors: it is part of the developer-tooling stack around GitHub, VS Code, Windows workstations, and Azure-connected engineering teams.

The shared governance matters because it removes one of the usual objections to standardizing on a rival’s file name. Anthropic is not adopting a proprietary OpenAI runtime or API. It is reading a plaintext project instruction file now held under a neutral open-source foundation.

The useful migration is to separate common rules from Claude-specific behavior​

For a team using Claude Code and Codex or GitHub Copilot, the cleanest approach is to distinguish rules every agent should receive from instructions that depend on Claude Code’s own features.

Put broadly applicable repository guidance in AGENTS.md: the supported Node.js or .NET version, bootstrap commands, required test suites, formatting checks, directories agents must not alter, secrets-handling rules, and change-control requirements. These are instructions a new human contributor should largely understand as well, even if the file is aimed at automation.

Keep a CLAUDE.md only where the repository needs Claude-specific behavior: instructions tied to Claude Code skills, hooks, subagent workflows, MCP configuration, or tool-specific conventions. That arrangement gives other agents a common baseline without forcing every product to interpret vendor-specific details.

The trap is duplicating common rules into both files and expecting people to keep them synchronized. The reported workaround before this release was often a symbolic link, but a symlink is not automatically portable across Windows development environments, Git worktrees, containers, and hosted CI runners. It can also obscure which file an agent actually read when diagnosing an unexpected change.

A more durable approach is to make one file authoritative for shared rules and document the relationship plainly. If both files are necessary, avoid restating whole policies. A short Claude-specific file that points developers toward the shared guidance is easier to audit than two competing instruction manuals with nearly identical content.

Treat agent instruction files as controlled configuration​

The interoperability gain also expands the number of files that can shape an agent’s behavior. That deserves the same review discipline teams apply to CI workflow files, package scripts, Dockerfiles, and repository-level configuration.

An AGENTS.md file does not execute code by itself. But it can tell an agent which commands to run, which directories to inspect, which tests to bypass, or where to send generated output. In repositories where an agent has shell access, credentials, deployment permissions, or broad write permissions, unreviewed instruction changes can materially influence what the agent attempts next.

The safe operating model is straightforward:

• Commit AGENTS.md and CLAUDE.md to source control and require code review for changes.
• Keep commands in instruction files specific, reproducible, and least-privileged; do not normalize blanket requests to disable tests, protections, or sandboxing.
• Use Claude Code’s configuration deliberately rather than assuming its fallback behavior creates a merged policy.
• Test the chosen configuration in a disposable branch or workspace before deleting legacy files.
• Confirm the same behavior on developer Windows devices, WSL environments, CI runners, and cloud-hosted agent sessions, because provider support is not yet uniform.

Anthropic bundled this compatibility change with several security- and reliability-oriented fixes in 2.1.277. The release now strips invisible Unicode formatting and tag characters from prompts before showing the cleaned prompt for review, and it frames subagent results so their content cannot appear as if it were a top-level session instruction. It also fixes a Windows case where a turn could fail with an out-of-memory error after Claude replied, preventing that response’s tool calls from running.

Those improvements do not turn AGENTS.md into a security boundary. They do show Anthropic is treating prompt and instruction provenance as an active engineering problem while it opens Claude Code to a broader convention.

Azure-hosted teams must wait for the promised portability​

The headline benefit is real: a repository can increasingly carry one agent-facing playbook rather than a separate CLAUDE.md, AGENTS.md, and tool-by-tool configuration collection. But on September 18, the benefit applies first to supported Claude Code installations, including developers who update their local Windows CLI through standard channels.

Organizations using Claude through Microsoft Foundry do not receive AGENTS.md support in this release, according to Anthropic’s official notes. For those teams, the immediate result is not fewer files; it is another compatibility split to track.

For everyone else, version 2.1.277 is best seen as an opportunity to audit instruction ownership before adopting a shared file. The immediate payoff comes only after the repository has one reviewed source for common agent rules and Claude Code has been configured to read it.