Claude Code Refuses Native AGENTS.md Support: A Year-Long Developer Controversy

A GitHub feature request that accumulated 6,644 upvotes came to a rather absurd end. That number surpasses the feedback many official product announcements ever receive — and what it asked for wasn't complicated: native support for AGENTS.md files in Claude Code. After digging through the GitHub thread and official documentation firsthand, the real story turns out to be more interesting than what's been circulating online.

The AGENTS.md vs. CLAUDE.md Divide

AGENTS.md is a configuration standard championed by OpenAI, with Cursor, Google, and others contributing to its ecosystem. It has since been handed off to a Linux Foundation-affiliated organization for stewardship. According to the project's own website, over 60,000 GitHub repositories have already adopted the format. Its purpose is straightforward: give AI coding tools a unified, shareable instruction file.

Claude Code has taken a different path, sticking with its own CLAUDE.md. The official documentation is unambiguous — Claude Code reads CLAUDE.md, not AGENTS.md. The only compatibility workaround is to add an import statement for AGENTS.md inside CLAUDE.md, or to manually create a symlink.

What looks like a minor naming disagreement gets amplified quickly in real-world engineering environments where multiple tools are used in tandem.

The standardization logic behind AGENTS.md is analogous to .editorconfig in software engineering: if different editors agree on the same configuration file, developers don't need to maintain separate settings for every tool. The same problem has emerged with AI coding tools — Cursor, GitHub Copilot, Claude Code, Gemini CLI, and others each read different instruction files. A team of ten-plus engineers mixing three or four AI tools must maintain multiple nearly identical files just to ensure consistent coding standards and context. AGENTS.md aims to eliminate that coordination cost. Handing it off to the Linux Foundation is meant to keep the standard vendor-neutral — but Anthropic's decision not to participate is itself a clear ecosystem stance.

Shopify CEO Goes Public

The dispute has drawn in Shopify's projects as well. According to research done on this story, Shopify CEO Tobi Lütke publicly stated on social media that he was considering banning Claude Code internally unless Anthropic agreed to read these files.

His reasoning was concrete: both configuration files propagate recursively through the directory tree, and with thousands of engineers sharing a single codebase, some directories will inevitably be missing one file or the other. In those gaps, developers using Claude Code are essentially working with "an agent with part of its brain cut out."

This isn't a complaint from an ordinary user — it's a formal statement from a major customer with thousands of engineers. It elevated a technical detail into a procurement decision.

How That Issue Actually Got Closed

The truly absurd part is buried in the issue's original record.

Last month, the issue was marked "completed" and closed. The Anthropic engineer's proposed solution: create a CLAUDE.md with a single AGENTS.md import line, or use a symlink. The problem is that this is word-for-word identical to the workaround that had existed for a year.

Developers pushed back immediately: this solution still requires a CLAUDE.md file in the repository to work — that's a workaround, not genuine adoption. One developer pressed further: "Why not just change two lines of code?"

More puzzling still: another developer discovered that the issue was likely not deliberately closed by Anthropic at all, but accidentally triggered by a completely unrelated commit in a third-party repository. That commit's message referenced this issue's number, causing GitHub to automatically associate and close it.

In other words, a feature request with over 6,600 upvotes accumulated over an entire year may have been closed by an accidental trigger.

GitHub's automatic issue-closing mechanism is the technical root cause here. When a commit message contains specific keywords combined with an issue number — such as fixes #1234, closes #1234, or resolves #1234 — GitHub automatically marks that issue as closed. By default, this even works cross-repository (within the same organization, or via a full repository path reference). This means anyone could write "closes anthropics/claude-code#[number]" in a commit message on their own repo and close an Anthropic issue without any review. The mechanism was designed to let developers automatically clean up issues when merging PRs — but in this case, its side effect was silently erasing a highly-voted public request with no official confirmation.

What the Docs Actually Changed

Rather than relying solely on "what the documentation says," the full changelog (over 7,000 lines) was pulled and reviewed line by line.

Two new additions were confirmed:

• An import command: copies and merges configurations from AGENTS.md and other tools into CLAUDE.md in one go
• An environment variable: when enabled, reads AGENTS.md once during CLAUDE.md generation

The critical distinction: both of these are one-time operations, not native reads on every conversation. That's a fundamentally different treatment from CLAUDE.md itself, which is loaded every time. And in those 7,000+ lines of changelog, searching for AGENTS.md and the one-time import command returns nothing — developers who said this fix wasn't logged in the changelog were correct.

This issue isn't isolated, either. Another similar request has been open since last August, repeatedly auto-closed by bots and reopened, with over 500 upvotes and still no resolution.

Anthropic's Response and Developer Pushback

In the face of criticism, Anthropic team members haven't been entirely silent. On social media, they responded that they are improving customizability so developers can more easily use AGENTS.md in the future.

Their stated rationale: different models need different context and instructions. The team also cited a number — they've removed roughly 80% of system prompts for the latest generation of models.

But developers did the math and pushed back: one developer said they personally use five models, and others on their team use even more. If every model requires a separate instruction file, a single project could require a dozen files to maintain in sync with every update. His exact words: "Nobody is going to do that."

Some observers framed this as a symptom of a larger problem: refusing to follow conventions that peers have widely adopted, and insisting that your own file holds a special status, signals a "we know best" attitude. One commenter said they love many of Anthropic's products but hopes the company recognizes this is a cultural problem — and that it's causing Anthropic to gradually lose developer trust.

Anthropics' claim about removing "roughly 80% of system prompts" has a specific context: early large language models required extensive system prompts to constrain behavior, while newer models (such as the Claude 3.5/3.7 series), after more thorough RLHF and Constitutional AI training, have internalized more safety and style constraints and no longer depend on external prompts as a safety net. This reflects genuine model capability improvements — but using it to explain why AGENTS.md isn't natively read is a non sequitur. Whether to read a universal config file and how long system prompts are are two independent engineering decisions. Developer pushback hit this mismatch squarely: their ask was never about reducing prompt length. It was about having one file that every tool can recognize, eliminating the sync burden across multi-tool environments.

What to Do Now If You're Maintaining a Multi-Tool Repository

Setting aside the broader debate, there's one practical thing developers maintaining repositories with multiple AI coding tools should do right now: check whether your AGENTS.md and CLAUDE.md files are out of sync.

The simplest approach, per the official documentation, is to add an import for AGENTS.md inside CLAUDE.md, or set up a symlink, so both configurations stay consistent and you don't end up with blind spots in recursive directory traversal.

The assessment here is that this won't be the last time a major customer applies public pressure. The evidence: there's still another similar request open, with 500+ upvotes and no response. A falsifiable standard has also been set: if within three months Anthropic makes Claude Code natively read AGENTS.md — no imports, no symlinks required — then this judgment will have been wrong.

This dispute looks like a file naming argument on the surface. Underneath, it's a more fundamental question: in an era of multi-tool, multi-model AI coding, should vendors embrace universal conventions or defend the special status of their own ecosystem? The answer is a matter of technology — and of developer trust.