Claude Code vs AGENTS.md: What the Shopify Ban Means
Does Claude Code read AGENTS.md? It did not, as of August 25, 2026: Anthropic's official documentation said Claude Code reads CLAUDE.md, not AGENTS.md. That changed on 2026-09-18 — see Resolved (2026-09-18, Claude Code v2.1.277) below. AGENTS.md is the open, plain-Markdown "README for agents" standard used by more than 60,000 open-source projects and stewarded by the Linux Foundation's Agentic AI Foundation. The gap just exploded into a public fight: Shopify CEO Tobi Lütke said he is "thinking about banning Claude code at Shopify" until Anthropic reads AGENTS.md and .agents/skills. Here is what happened, why split-brain is real, and what it means for your stack.
What happened: Shopify's CEO put Claude Code on notice
On August 25, 2026, Lütke posted on X that he was considering banning Claude Code at Shopify:
I'm thinking about banning Claude code at Shopify until they change their mind and read AGENTS.md and .agents/skills etc.
Insisting on only reading CLAUDE.md sometimes leads to split brain problems when different team members use different tools. Just unnecessary.
The post drew hundreds of thousands of views within hours, and X's trending topic page framed it as "Shopify CEO Considers Banning Claude Code Over File Reading Issue." The New Stack's headline captured the awkward timing: "Shopify's CEO threatened to ban Claude Code. Anthropic had already closed the feature request."
Framing note: Lütke said he was "thinking about banning" Claude Code. There is no evidence an actual ban has been enacted at Shopify. This is a threat and a signal, not a policy change.
Does Claude Code read AGENTS.md? Not until v2.1.277
The direct answer was no for most of 2026, and this section keeps the record of what the official documentation said at the time. Until 2026-09-18, the memory docs stated it verbatim:
Claude Code reads CLAUDE.md, not AGENTS.md. If your repository already uses AGENTS.md for other coding agents, create a CLAUDE.md that imports it so both tools read the same instructions without duplicating them.
The docs list four ways to bridge the gap:
- @import in CLAUDE.md. Create a CLAUDE.md whose body is
@AGENTS.md. Claude Code loads the imported file at session start, and you can still add Claude-specific instructions around it. - Symlink.
ln -s AGENTS.md CLAUDE.mdworks when you don't need Claude-specific content. Windows users should prefer the import, since symlinks require admin or Developer Mode. - /init with CLAUDE_CODE_NEW_INIT=1. The init command also reads AGENTS.md, .devin/rules/, .windsurf/rules/, and .clinerules, and folds relevant parts into a generated CLAUDE.md.
- /import (v2.1.213+). Appends a one-time copy of AGENTS.md into the matching CLAUDE.md, and carries over MCP servers, commands, subagents, and skills.
One correction: third-party guides claimed Claude Code "reads AGENTS.md as a fallback" when no CLAUDE.md exists. Until 2026-09-18 that was not in the official documentation, and the Claude Code team's own reply contradicted it — it is now the documented, shipped behaviour, recorded in the "Resolved (2026-09-18, Claude Code v2.1.277)" block above.
What is the AGENTS.md standard?
AGENTS.md is a plain Markdown file placed in a repository's root (or nested directories) that tells coding agents how to build, test, and contribute. The official site describes it as "a simple, open format for guiding coding agents, used by over 60k open-source projects" — a README for agents.
OpenAI shipped the format with Codex in August 2025, then handed it to the Agentic AI Foundation (AAIF), a Linux Foundation directed fund co-founded by OpenAI, Anthropic, and Block, which also stewards MCP and goose. Here is the irony at the center: Anthropic co-founded the foundation that stewards AGENTS.md, yet its own flagship coding tool did not read the format natively as of August 2026.
The supported-agents list on agents.md is long: Codex, Cursor, Gemini CLI, GitHub Copilot, Aider, Devin, Windsurf, Junie, Jules, Amp, and more. Claude Code is not on it.
AGENTS.md vs CLAUDE.md vs .agents/skills
| File / convention | What it is | Who reads it | Status |
|---|---|---|---|
| AGENTS.md | Open, tool-neutral instructions for coding agents ("README for agents") | Codex, Cursor, Gemini CLI, Copilot, Aider, Devin, Windsurf, and more | Open standard, AAIF stewarded |
| CLAUDE.md | Claude Code's native memory / instructions file | Claude Code only | Vendor-specific |
| .agents/skills | Cross-tool skills directory convention (Lütke's shorthand) | Codex CLI and other tools | Convention; not part of the agents.md spec |
Two notes. First, .agents/skills is Lütke's shorthand for the skills-directory convention that Codex CLI and others use; it is not documented on the agents.md spec site, and Claude Code's analog is .claude/skills. Second, the practical difference agencies care about: AGENTS.md is portable across tools, CLAUDE.md is not. If a repo standardizes on AGENTS.md, every agent that reads it works from the same instructions.
The split-brain problem, explained
"Split brain" is what happens when one source of truth divides into per-tool copies. Team members use different coding agents, each reading only its own config file. Project context drifts: a build command, a test convention, or a security rule lives in AGENTS.md for the Codex users and in CLAUDE.md for the Claude Code users, and nothing guarantees the two stay in sync.
Lütke's follow-up post made the pain concrete:
But agents and claude files are recursively applied through the tree. With thousands of developed [developers] in a mono repo, it just does happen that one directory is missing one of the two files and this means that a subset of devs work with lobotomy.
We fix this with automation but it's a stupid complexity tax that shouldn't have to be paid.
That is the argument in two lines: a missing file means a subset of developers run their agent with incomplete context, and keeping every directory in sync across thousands of developers is a tax the toolmaker should not have imposed. This is not about whether Claude Code is good. It is about whether the config layer plays well with the rest of the ecosystem.
Anthropic's reply: "more hackable" Claude Code
The Claude Code team responded roughly three hours after the original post. Thariq Shihipar, a member of the technical staff on the team, wrote:
We are working on making Claude Code more hackable, which will include being able to easily use Agents.MD or make other system prompt modifications. I'll share more here when it's ready to roll out.
He also explained the product reasoning and gave the immediate workaround:
Our reasoning for this was that we don't think that model families are interchangeable and the system prompt can have a big impact on performance.
In the immediate term, you can always @Agents.MD from your Claude.MD.
Translation at the time: native AGENTS.md support was on the roadmap, not shipped — it shipped on 2026-09-18 (v2.1.277), recorded below. Anthropic's position is that different models want differently formatted system prompts, so a single cross-tool file cannot capture what each model needs. That is a defensible engineering position. It is also, from a customer's seat, the exact reason the ecosystem standard exists.
The context: the feature request for AGENTS.md support (GitHub issue #6235, opened August 2025) had 377 comments and more than 6,400 reactions, and was closed as completed on August 17, 2026, eight days before Lütke's tweet, even though the docs still described bridges rather than native reading.
Resolved (2026-09-18, Claude Code v2.1.277)
Update, 2026-09-18: Anthropic shipped native AGENTS.md support in Claude Code. Thariq Shihipar (@trq212), Claude Code team, announced it the same day:
We're adding support for AGENTS.md to Claude Code.
Starting today in version 2.1.277, if there is no CLAUDE.md in a folder, Claude will check for and use AGENTS.md.
You can toggle this behavior in /config.
Does Claude Code support AGENTS.md? Yes: since version 2.1.277 (shipped 2026-09-18), Claude Code reads AGENTS.md in any project that has no CLAUDE.md.
Two details the short version skips. First, CLAUDE.md still wins: if a CLAUDE.md (or a CLAUDE.local.md) exists in the working directory or in any directory above it, Claude reads CLAUDE.md only and ignores AGENTS.md. AGENTS.md is a fallback, not a peer. Second, that default is a setting: /config, then "Project instructions".
Why it matters: the split-brain problem behind Shopify's August ban threat now has a shipped first-party fix with a version number: teams that run AGENTS.md alongside other coding agents no longer need an @import or symlink bridge for Claude Code.
What agencies should do
For agency owners, this fight is not entertainment. Your choice of coding agent stack is a cost and a lock-in decision, and AGENTS.md interoperability is now a first-order selection criterion.
- If your repo runs CLAUDE.md today, bridge it now. Standardize on AGENTS.md as the repo's single source of truth, and add a CLAUDE.md that imports it (
@AGENTS.md) or symlinks it. Your future self will not have to reconstruct which file holds the real rules. - If you are choosing a stack, add "reads AGENTS.md natively" to the evaluation. For solo builds it barely matters. For a team, or for client handoffs, it is the difference between one config and N configs.
- If you build automation for clients, treat config portability as a deliverable. A stack that reads the open standard lowers switching costs when a client's team changes tools, and it makes your work less hostage to any single vendor.
- Revisit the decision: Anthropic shipped native support on 2026-09-18. "We are working on it" is not a date — v2.1.277 is one.
The pattern is familiar from every infrastructure fight of the last decade: whoever controls the format controls the switching costs. AGENTS.md is the industry's attempt to keep that power with the user. Agencies that standardize on it early will not have to re-platform when the next tool war starts.
Frequently asked questions
Does Claude Code read AGENTS.md?
Yes, since v2.1.277 (2026-09-18) — but only when no CLAUDE.md exists in the working directory or above it. With both files present, Claude reads CLAUDE.md only, and the @import or symlink bridge is still the way to read AGENTS.md in that case.
What is the AGENTS.md standard?
An open, plain-Markdown file in a repo's root that tells coding agents how to build, test, and contribute. It is a "README for agents," used by more than 60,000 open-source projects and stewarded by the Linux Foundation's Agentic AI Foundation.
What is the difference between AGENTS.md and CLAUDE.md?
AGENTS.md is the open, cross-tool standard read by Codex, Cursor, Gemini CLI, Copilot, and others. CLAUDE.md is Claude Code's native, vendor-specific file. Claude Code reads AGENTS.md natively since v2.1.277 (2026-09-18), but only as a fallback: when a CLAUDE.md or CLAUDE.local.md exists in the working directory or above it, Claude reads the CLAUDE.md files only.
Why doesn't Claude Code read AGENTS.md?
Anthropic says different model families need differently formatted system prompts for performance. The feature request is one of the most-reacted-to on its tracker, and the team said on August 25, 2026, it is working on making Claude Code "more hackable," including AGENTS.md support. That support shipped on 2026-09-18 in v2.1.277.
Why is Shopify banning Claude Code?
Shopify CEO Tobi Lütke posted that he is "thinking about banning Claude code at Shopify" until Anthropic reads AGENTS.md and .agents/skills, citing split-brain problems when different team members use different tools. As of August 25, 2026, it is a threat, not an enacted policy.
What is the split-brain problem in AI coding?
When team members use different coding agents that each read only their own config file, project context drifts across tools: one source of truth splits into per-tool copies that can fall out of sync.
How do I make Claude Code read AGENTS.md?
Since v2.1.277 (2026-09-18) you usually do not have to: Claude Code reads AGENTS.md on its own when no CLAUDE.md exists in the working directory or above it. When a CLAUDE.md is present and you still want AGENTS.md read, create a CLAUDE.md containing @AGENTS.md (supports Claude-specific additions), or symlink it with ln -s AGENTS.md CLAUDE.md. On Windows, use the import; symlinks need admin or Developer Mode.
Choosing your agency's AI stack? Work through the decision framework in our guide to choosing an AI automation agency, and price the tooling with our AI coding agent pricing guide.
Choose your AI automation agency →Sources
- Tobi Lütke (@tobi), "I'm thinking about banning Claude code at Shopify..." — x.com/tobi/status/2092259436538495186
- Tobi Lütke follow-up, "lobotomy" / "complexity tax" — x.com/tobi/status/2092308116524138711
- Thariq Shihipar (@trq212), Claude Code team reply — x.com/trq212/status/2092302273099796842
- X trending topic: "Shopify CEO Considers Banning Claude Code Over File Reading Issue" — x.com/i/trending/2092264944116850961
- Claude Code docs, memory (CLAUDE.md / AGENTS.md) — code.claude.com/docs/en/memory
- GitHub issue #6235, "Feature Request: Support AGENTS.md" — github.com/anthropics/claude-code/issues/6235
- AGENTS.md spec — agents.md
- The New Stack, "Shopify's CEO threatened to ban Claude Code. Anthropic had already closed the feature request." (Aug 25, 2026) — thenewstack.io/shopify-claude-code-agentsmd
- ExplainX, "Shopify CEO vs Claude Code over AGENTS.md" (Aug 25, 2026) — explainx.ai/blog/tobi-shopify-claude-code-agents-md-ban-threat-august-2026
Accuracy note: Originally verified 2026-08-25 (source pack t_89d4e5b0); update block verified 2026-09-20 against the sources above. Quotes preserved verbatim, including Lütke's "Claude code" capitalization and the team's "Agents.MD"/"Claude.MD" spellings, and the @trq212 announcement quoted in full. Tweet metrics are time-of-fetch snapshots. The Shopify ban remains a threat, not enacted policy; what shipped on 2026-09-18 is native AGENTS.md support in Claude Code v2.1.277.