Plan B No More: Claude Code Finally Reads AGENTS.md — Inside the 2.1.277 Release

For more than a year, one of the most persistent papercuts in AI-assisted development had nothing to do with model quality. If your repository shipped an AGENTS.md file — the open standard for project-level AI instructions — Claude Code would simply ignore it. The tool read CLAUDE.md, and only CLAUDE.md. Developers who wanted both had to maintain symlink farms, duplicate files, or synchronization scripts just to keep Anthropic’s coding agent and the rest of the ecosystem pointed at the same instructions.

That era ended on September 18, 2026, with a one-line entry in the Claude Code changelog. Version 2.1.277 “Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead.” The behavior can be changed under “Project instructions” in /config. It is a small feature with a long backstory — and a set of caveats that matter for any team deciding whether to delete their workarounds today.

What Actually Shipped

The mechanics are deliberately conservative. When Claude Code starts a session in a project, it looks first for its native instruction file, CLAUDE.md. If none exists — no CLAUDE.md, and per community testing no CLAUDE.local.md either — the tool now falls back and reads AGENTS.md instead. The setting is exposed as a toggle in the /config panel under “Project instructions,” so enterprises that need to pin behavior can turn the fallback off entirely.

Two limitations are worth flagging immediately. First, the feature is not yet available on Bedrock, Vertex, or Foundry — the managed cloud deployments where a large share of regulated-enterprise Claude Code usage happens. If your organization runs Claude Code through AWS, Google Cloud, or Azure plumbing, you are still living in the pre-2.1.277 world for now. Second, and this is the one that stung early adopters on Hacker News: the fallback covers the instruction file only. It does not include .agents/skills, the directory-level convention that richer AGENTS.md-based setups use to bundle reusable skills alongside instructions. “Note that this does not include .agents/skills. Argh,” wrote one of the first commenters — a fair summary of a half-step.

The AGENTS.md support headline rode along with a broad maintenance release. 2.1.277 also added gateway and plugin controls — a new CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY flag for Claude apps gateways whose only egress is a forward proxy, plus an optional headers: map on gateway upstreams — and shipped a long list of stability fixes: headless claude -p and Agent SDK sessions that could hang silently after internal errors now report and exit with code 1, a “text content blocks must be non-empty” conversation failure is fixed, and a parsing bug in the Edit tool that could mangle edits containing escaped backslashes followed by uXXXX sequences — a real hazard for non-ASCII source code — is corrected.

Why a File-Name Feud Mattered

To understand why 51 points on Hacker News and a wave of blog posts greeted a config fallback, it helps to remember where AGENTS.md came from. The standard was proposed by OpenAI in August 2025 as a vendor-neutral answer to a multiplying mess of tool-specific rule files: CLAUDE.md for Claude Code, .github/copilot-instructions.md for GitHub Copilot, .cursorrules for Cursor, GEMINI.md for Gemini CLI. The pitch was simple — one markdown file at the repository root, read by every coding agent, describing build commands, code style, testing conventions, and architectural guardrails the same way README.md describes the project to humans.

Adoption was fast by developer-tool standards. Codex, Gemini CLI, Cursor, and a long tail of smaller agents picked it up, and by late 2025 the file was embedded in more than 20,000 repositories on GitHub. Claude Code was the conspicuous holdout. Every other major agent read the open standard; Anthropic’s did not.

The holdout had real costs beyond aesthetics. Teams standardized on AGENTS.md found their Claude Code sessions quietly running without any project instructions at all — the tool didn’t warn that it had found an unrecognized file. The workaround culture that grew up around the gap became its own folklore: symlinking CLAUDE.md → AGENTS.md, CI checks to keep the two in sync, and the wry observation on Hacker News that “vendor locks over md file names is crazy.”

Pressure accumulated publicly. Shopify CEO Tobi Lütke — whose company runs one of the largest Claude Code deployments anywhere — tweeted about the mismatch, and the competitive backdrop shifted as OpenAI’s Codex gained ground with GPT-6 Astra momentum in September 2026. “It took the Shopify CEO tweet and Astra causing a large move towards Codex for them to finally give in,” one HN commenter argued. Whether that causal story is exactly right or not, the timing is suggestive: the feature landed weeks after a wave of high-profile AGENTS.md advocacy and amid an unusually competitive coding-agent market.

The Strategy of Being Second

There is a case that Anthropic’s delay was simply engineering triage rather than lock-in strategy — the changelog’s density of fixes suggests a team buried in other priorities. But the shape of the implementation tells its own story. This is a fallback, not a default. CLAUDE.md remains first in the resolution order, and AGENTS.md is read only in its absence. Anthropic gets to claim standard compatibility while keeping its native format in the privileged position — the exact “dual-file approach, prioritize the native format, gracefully fall back to the open standard” that a GitHub issue requested over a year ago.

For teams, the practical question is which file to standardize on going forward. If you already maintain both, the pressure to keep duplicating eases: a single AGENTS.md now serves Claude Code and every other compliant agent, at the cost of losing Claude-specific instructions that deliberately diverge. If you were CLAUDE.md-only and happy, nothing changes. The awkward middle — repositories that need Claude-specific overrides and cross-tool instructions — still has no clean answer, because precedence runs one way only.

The bigger read is about consolidation. Agent instruction formats were the industry’s format war of 2025-26, and this release is effectively the moment the open standard won. When the last major holdout adopts a convention — even partially, even as a fallback — the network effects flip: new projects now default to AGENTS.md because it works everywhere, and tool-specific files become the compatibility shim rather than the primary artifact. What remains unresolved is the richer surface above the file: .agents/skills, nested instruction discovery, imports and precedence rules — the places where vendors can still differentiate. Expect the next standards fight to happen there.

For now, thousands of developers are doing something simpler: running claude --version, updating to 2.1.277, and deleting a symlink. As one Hacker News commenter put it: “Finally. Now I can remove all my symlinks.”

Cover image generated with MiniMax image generation. Sources are listed in the frontmatter and rendered below.