The Timeline: From Most-Upvoted Issue to CEO Threat to Native Support

The fight for AGENTS.md support in Claude Code is one of the defining public stories of the 2026 AI coding landscape. It started quietly on August 21, 2025, when a user filed issue #6235 asking Anthropic to make Claude Code read the cross-vendor instruction file. Over the following year, that single request became the most-upvoted issue in the entire anthropics/claude-code repository, accumulating roughly 4,667 to 5,026 thumbs-up reactions and 361 to 384 comments.

What made the issue so explosive was context. By late 2025, AGENTS.md had become a genuine industry standard: the Agentic AI Foundation under the Linux Foundation formalized the format in December 2025, and OpenAI contributed it alongside Anthropic’s MCP (Model Context Protocol). More than 60,000 open-source projects adopted the file, and some 20+ coding tools — Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf, Zed, and Jules among them — read it natively. Claude Code was the glaring holdout, reading only its proprietary CLAUDE.md.

The pressure peaked on August 25, 2026, when Shopify CEO Tobi Lütke said publicly that he was considering banning Claude Code from his company until it respected AGENTS.md and .agents/skills. He called the CLAUDE.md-only approach a “complexity tax” that created a “split brain” among thousands of Shopify developers working across a massive monorepo.

The issue was finally closed on August 17, 2026, marked “completed” — but the closeout shipped a workaround, not a built-in feature. That nuance mattered, and it is largely why a wave of criticism followed the close and why a parallel request (issue #34235, opened in March) remains open with about 110 reactions even after #6235 was closed. The anger was never that the workaround fails; it was that an issue this important was closed as “completed” when the tool still did not read AGENTS.md natively.

What Actually Changed: Claude Code 2.1.277 and the Four Loading Modes

The real change landed on September 18, 2026, with release 2.1.277. As of that version, Claude Code reads AGENTS.md automatically whenever a repository contains an AGENTS.md but no CLAUDE.md on the path. No import, no symlink, no hook required.

The behavior is not a hardcoded switch but a feature-flagged built-in plugin called agents-md, exposed through the /config interface under “Project instructions” with four modes:

• claude-md-or-agents-md (default): uses either file, preferring CLAUDE.md when both exist, falling back to AGENTS.md when it is the only one present.
• claude-md-and-agents-md: merges both files instead of choosing one.
• claude-md: restores the legacy behavior and ignores AGENTS.md entirely.
• managed-only: reads instructions only from the managed/enterprise settings channel.

Anthropic engineer Thariq Shihipar explained the original reasoning in public: different model families are not interchangeable, and system prompts materially affect performance, so Anthropic was wary of blindly adopting a format designed for other vendors. The eventual implementation shipped via a new “mods” mechanism, and Anthropic open-sourced the agents-md mod itself.

Does Claude Code Read AGENTS.md Today? (The Honest Answer)

The short answer is: usually yes, but conditionally. On a default, up-to-date desktop install of 2.1.277 or later, Claude Code will load instructions from AGENTS.md if the repository has one and no CLAUDE.md is present. That covers the vast majority of solo developers and standard CI setups.

The honest caveat is a long list of conditions where native support silently does not apply:

• The feature is gated behind telemetry flags. Setting DO_NOT_TRACK, DISABLE_TELEMETRY, or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC disables the plugin entirely — which is ironic, because privacy-conscious users are precisely the ones who still get the old behavior.
• It does not run on Bedrock, Vertex, or Foundry. Enterprise teams routed through Anthropic’s cloud deployments are locked out of native support.
• It is disabled when hooks are restricted or the agents-md plugin is explicitly turned off.
• The first session after an install or upgrade may not load AGENTS.md; the feature sometimes needs a throwaway session first.
• Critically, a directory that contains a CLAUDE.local.md file can silently switch the tool back to ignoring AGENTS.md entirely.

So the honest answer depends on your environment. If you are on a default local install with telemetry on and no local override file, yes — Claude Code reads AGENTS.md today. If any of the conditions above apply, you are still on the pre-2.1.277 path.

The Pre-2.1.277 Workarounds — and Which to Keep or Delete Now

For a year, the only ways to make Claude Code respect AGENTS.md were community bridges. Now that native support exists, you should audit what you have and remove the noisy pieces.

The @AGENTS.md Import (Import vs Symlink)

The preferred pre-release bridge is a thin CLAUDE.md file that imports AGENTS.md with a single line: @AGENTS.md. This approach is best because the CLAUDE.md file remains tiny and can hold Claude-specific lines that should not leak to other tools, while AGENTS.md stays the single source of truth.

The trade-off to understand: imports do not save context. An imported file expands at session launch exactly as if it were inline, so a long shared AGENTS.md costs the same tokens whether you import it or paste the text directly. The two approaches are not a “lighter” alternative — they load identically.

The Symlink Route

The other common bridge is a symlink: ln -s AGENTS.md CLAUDE.md. This keeps a single physical file and works well in most Unix environments. The catch is Windows: creating the symlink needs Admin rights or Developer Mode, and if Git’s core.symlinks=false is set, the link checks out as a plain text file literally containing the word “AGENTS.md”, which no tool will interpret. On top of that, Claude Code’s Edit and Write tools refuse to write through a symlink (issue #66559).

The SessionStart Hook

For repositories you cannot commit to — vendor checkouts, generated code, or upstream forks — the SessionStart hook in ~/.claude/settings.json was the escape hatch. It injects the AGENTS.md contents at session start. Now that native support exists, this hook has a new downside: on versions where the plugin is active, it injects a duplicate copy of the file, which costs extra tokens. If you are on 2.1.277+ with the feature enabled, remove the hook.

/import and /init Migrations (One-Time Copies That Drift)

The /import command (available since 2.1.213) and /init with CLAUDE_CODE_NEW_INIT=1 produce one-time copies of AGENTS.md into CLAUDE.md. These snapshots drift: once generated, they are independent files, and any edit you make to AGENTS.md no longer reaches Claude Code. If you used these to migrate, replace the copied content with a live @AGENTS.md import after migrating so the two stay in sync.

The Silent-Failure Trap: Why Every Fix Can Quietly Break

Every single path — the bridges and the native fallback alike — can fail without any error message. The correctness damage often surfaces only weeks later in a code review, when you realize the AI never had the instructions you thought it did. There are three specific traps worth memorizing.

The CLAUDE.local.md Trap

CLAUDE.local.md is personal, machine-specific guidance that Claude loads on top of project files. But here is the trap the documentation rarely emphasizes: adding a CLAUDE.local.md silently changes which project file wins. In claude-md-or-agents-md default mode, the presence of any CLAUDE.md-family file on the path tips the balance, and you can find yourself back to AGENTS.md being ignored without a single error or warning.

Windows: Symlinks and the VS Code Import Bug (#81189)

On Windows, the @AGENTS.md import is not expanded inside the VS Code extension — an open bug tracked as #81189. The agent sees the literal text @AGENTS.md and does nothing. Combined with the symlink permissions problem and Git checkout behavior, Windows teams have the least reliable pre-2.1.277 experience of anyone, and the safest recommendation for a Windows mixed team is an import at the repo root plus a CI check.

Monorepo Subdirectory Imports (#78697)

Imports in a parent or root CLAUDE.md do not expand when you launch Claude Code from a subdirectory — bug #78697. For a monorepo with 88 AGENTS.md files (the OpenAI repo carries roughly that many), hand-maintaining CLAUDE.md stubs is unmaintainable, which is why generated stubs plus a CI check that every AGENTS.md is referenced is the only sane approach.

Why Anthropic Resisted — and Why It Finally Yielded

Anthropic’s public resistance was rooted in a substantive technical argument, not stubbornness. As Shihipar explained, model families are not interchangeable, and the system prompt directly shapes performance. Adopting a file designed to be vendor-neutral meant every tool in a team would inject the same instructions into different models with different strengths — and Anthropic did not want to inherit that coupling.

There was also a policy argument, captured in the “complexity tax” criticism: making AGENTS.md opt-in per repository forever would force platform teams and thousands of developers to maintain parallel instruction files, and the coordination cost of that “split brain” scales with team size. The combination of the record-setting issue, the CEO threat, and the growing ubiquity of the standard (60,000+ projects) finally tipped the calculus, and Anthropic shipped the agents-md mod rather than hardcoding a client behavior — a design choice that keeps the file’s loading configurable and vendor-neutral.

The Context-Cost Reality Check (>20% Inference Cost Debate)

Not everyone believes more instruction files is a win. Kent C. Dodds flagged research on August 13, 2026 showing that AGENTS.md files often do not improve task success while adding more than 20% to inference cost. The mechanism is straightforward: every instruction line occupies context window on every request, and long shared files load identically whether imported or inline. For a bloated file, the token blast radius multiplies across every tool in the team that reads it.

This is an argument for editorial hygiene, not for abandoning AGENTS.md: keep files under roughly 200 lines, delete lines that apply to only one tool, and remember that a fat shared file taxes Codex and Cursor exactly as much as it taxes Claude Code. The right response to the cost concern is a lean file, not the absence of one.

Recommended Setup by Team Type (Decision Matrix)

There is no single correct answer, so here is a matrix keyed to your situation:

• Solo developer, Claude Code only: if you are on 2.1.277+, use native support with a single CLAUDE.md and skip AGENTS.md. There is no cross-tool benefit worth a second file.
• Multi-tool team (Codex + Cursor + Claude Code): AGENTS.md is the source of truth, and CLAUDE.md is a thin shim with a single @AGENTS.md import. One owner edits AGENTS.md. On 2.1.277+, the “or” mode reads it directly; use “and” mode only if you genuinely need CLAUDE.md-only lines.
• Monorepo (nested AGENTS.md files): generate CLAUDE.md stubs from each AGENTS.md and add a CI check that the reference exists. Hand-maintenance does not scale.
• Windows mixed team: import at the root, avoid symlinks, and add a CI check. Remember the VS Code import bug (#81189) when targeting the extension.
• Vendor or upstream repo you cannot commit to: drop the SessionStart hook once your version supports native loading, since it now risks duplicate injection.

In every case, keep the file lean and verify it actually loads rather than assuming.

How to Verify AGENTS.md Is Actually Loaded (/context)

Do not trust that a setup works. The silent-failure traps mean you should verify per session. There is a nuance: a directly loaded AGENTS.md does not appear under Memory files in /context the way a CLAUDE.md does. Instead, look for an “AGENTS.md loaded” line in the output, or the simplest robust check — ask Claude to quote the instructions back to it.

For the bridge-based setups, the symlink prints nothing on success, so pair it with /context under Memory files to confirm the import expanded. The cost of a two-second verification is trivial next to a review that discovers weeks later that the agent never saw the rules.

Bottom Line for Your Repo

Claude Code finally reads AGENTS.md natively as of 2.1.277, closing the most-upvoted issue in its history. If you are on that version with telemetry enabled and no CLAUDE.local.md trap, you can delete your imports and hooks and rely on the default behavior. If you are in an enterprise cloud deployment, on a privacy-hardened config, or on Windows, you still need a bridge — keep the @AGENTS.md import shim, avoid symlinks on Windows, and drop the SessionStart hook to prevent duplicate token cost. Whatever you choose, verify with /context that the file actually loaded, and keep instructions under about 200 lines so the context-cost tax stays worth paying.

FAQ

Does Claude Code read AGENTS.md as of 2026?

Yes, as of release 2.1.277 (September 18, 2026), Claude Code reads AGENTS.md automatically when a repository has AGENTS.md but no CLAUDE.md on the path. The behavior is configurable through four Project-instructions modes in /config.

Why did Claude Code take so long to support AGENTS.md?

Anthropic argued that model families are not interchangeable and that system prompts affect performance, so it was reluctant to adopt a vendor-neutral file. The record-setting issue, a public CEO threat, and the format’s widespread adoption (60,000+ projects) ultimately led to native support via the open-sourced agents-md mod.

What is the difference between importing AGENTS.md and symlinking it?

Both make Claude Code read AGENTS.md, but an import (@AGENTS.md) can also hold Claude-specific lines and is preferred, while a symlink (ln -s AGENTS.md CLAUDE.md) works well on Unix but requires Admin or Developer Mode on Windows and has symlink/write-tool bugs there.

Do I still need a workaround after Claude Code 2.1.277?

Only if you are on Bedrock/Vertex/Foundry, disable telemetry (which disables the plugin), use a CLAUDE.local.md override, or hit Windows-specific bugs. Otherwise native support covers you and you should remove the SessionStart hook to avoid duplicate token cost.

How do I confirm AGENTS.md actually loaded?

Run /context and look for an “AGENTS.md loaded” line — a directly loaded AGENTS.md does not appear under Memory files the way CLAUDE.md does. The most reliable check is to ask the model to quote the instructions back to you.