AGENTS.md just became the one instruction file every major coding agent reads

Anthropic shipped Claude Code v2.1.277 on September 18, 2026, and the top line of its changelog reads: "Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under 'Project instructions' in /config (not yet on Bedrock, Vertex or Foundry)."

The change was announced by Claude Code engineer Thariq Shihipar: "Starting today in version 2.1.277, if there is no CLAUDE.md in a folder, Claude will check for and use AGENTS.md." CLAUDE.md keeps precedence. It is a fallback, not a merge and not an override.

Why it matters

Claude Code was the last major coding agent not reading the vendor-neutral instruction file. AGENTS.md is the OpenAI-led specification (formalized for Codex CLI in August 2025, donated to the Linux Foundation's Agentic AI Foundation in December 2025), and more than 60,000 open-source projects had adopted the format by late 2025. Codex, Cursor, Gemini CLI, GitHub Copilot, and others already read it. Teams running Claude Code alongside any of them had to maintain a separate CLAUDE.md, a symlink, an @AGENTS.md import, or a hook that printed the file into context. That tax is now gone for the default configuration.

OpenAI's head of core product, Thibault Sottiaux, welcomed the move publicly ("Yay! This is the way. Come to the light," per Singulism's coverage of the exchange), with Shihipar replying in kind. It is a small moment, but it is the visible symbol of spec convergence: the two labs now share the Agentic AI Foundation as the neutral home for both MCP and AGENTS.md.

The rules, precisely

The docs spell the default behavior out as a table: if your repo has an AGENTS.md and no CLAUDE.md or CLAUDE.local.md in the working directory or above it, Claude reads your AGENTS.md. If a CLAUDE.md exists in that tree, Claude reads the CLAUDE.md files only. A CLAUDE.md that already imports AGENTS.md via @AGENTS.md continues to work, and an AGENTS.md loaded via import or symlink is never read twice.

It is not a binary toggle. Under "Project instructions" in /config, there are four values:

• claude-md-or-agents-md: CLAUDE.md files, or AGENTS.md when no CLAUDE.md exists. This is the default.
• claude-md-and-agents-md: both, every time, each directory's CLAUDE.md first, then its AGENTS.md.
• claude-md: CLAUDE.md only, matching pre-v2.1.277 behavior.
• managed-only: only the organization's managed CLAUDE.md and auto memory; project, local, and user instruction files excluded.

Two operational details from the docs: the setting is read from user-level settings (~/.claude/settings.json, a --settings file, or managed settings) under the built-in agents-md plugin's ID, and Claude Code ignores it in project and local settings files, so you cannot commit the choice to a repo and have it apply to teammates. Whichever value you pick applies from your next message on, not retroactively in the current one.

And the carve-out most likely to bite: the fallback is not available on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry at launch. A team that runs Claude Code through one of those providers cannot rely on the fallback yet, and a repo that assumes it will behave differently depending on how each developer launched the tool.

What a team should do

Consolidate to one AGENTS.md at the repo root: build commands, test commands, code conventions, security rules. Plain Markdown, no required schema. The convention supports layering: agents walk the directory tree and the nearest file to the code being edited takes precedence, so a monorepo can keep a short root file with org-wide rules and per-package files for what differs, rather than one enormous root file.

Then clean up the old workarounds. If a CLAUDE.md exists only to duplicate AGENTS.md, delete it. If it holds Claude-specific instructions, keep it: the docs' suggested shared setup is a CLAUDE.md whose first line is @AGENTS.md, followed by a Claude-only section. A SessionStart hook that prints AGENTS.md into context should be removed now that Claude reads the file directly, since it would add a second copy. A plain symlink still works, though the Edit and Write tools refuse to write through symlinks and point Claude at AGENTS.md instead.

Correction (2026-09-26): Don't delete that duplicate CLAUDE.md just yet. A carve-out discovered after this article's research: the AGENTS.md loader is a built-in plugin gated by the remote feature flag tengu_agents_md_mod, which defaults to off. Any session that doesn't fetch Anthropic's feature flags - telemetry disabled (DISABLE_TELEMETRY=1 or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1, where any value counts as set), first session after a fresh install/upgrade, or launches through Bedrock, Vertex, Foundry, or a gateway - silently skips AGENTS.md with no warning; the session answers as if no project instructions exist. Until you've confirmed your fleet actually loads AGENTS.md (a one-line canary test works), keep a one-line CLAUDE.md containing @AGENTS.md - imports don't depend on the flag. Anthropic acknowledged the behavior as a rollout artifact on Hacker News and reported a fix shipping in Claude Code v2.1.281 (Sep 23, 2026); verify it on your installs before deleting CLAUDE.md.

For organizations, the managed-only value is the policy lever: it lets you run with only centrally managed instructions, excluding every per-repo file.

What remains unknown

No timeline has been given for the Bedrock, Vertex, and Foundry gap. Until those deployments support the fallback, multi-harness teams at enterprises on those providers should treat AGENTS.md consolidation as aspirational, not done.

It is also unclear whether the default changes. A merge mode (claude-md-and-agents-md) exists but is opt-in; Anthropic has not said whether reading both will become the default, or whether the four-value picker is the permanent shape of the setting.

Finally, convergence is not complete. Gemini CLI still requires a configuration entry to read AGENTS.md, and every agent has its own precedence rules for layered files. One filename is now read by every major agent, which ends the file-format war. The next argument will be about which file wins in each directory, and that one is still per-agent.