Shopify's CEO threatened to ban Claude Code over AGENTS.md — the bridge works, and that's not the point

On August 17, 2026, Anthropic closed issue #6235 in the Claude Code repository. It had been open for 361 days, collected 5,026 thumbs-up reactions and 384 comments, and asked for one thing: let Claude Code read AGENTS.md, the shared instructions file that Codex, Cursor, and Windsurf already read natively. It was closed as completed — not “won’t fix” — by Boris Cherny, with a comment pointing to a workaround.

About a week later, Shopify CEO Tobi Lütke posted that he was thinking about banning Claude Code at Shopify until it reads AGENTS.md and .agents/skills, because insisting on CLAUDE.md alone “sometimes leads to split brain problems when different team members use different tools.”

We ran the workaround. It works. That turns out to be the least interesting part of the story.

The 30-second version

• A bare AGENTS.md with no CLAUDE.md beside it is never loaded. We confirmed this on Claude Code 2.1.243. That part of the complaint is real.
• Both documented bridges work: a CLAUDE.md containing the single line @AGENTS.md, and a CLAUDE.md symlinked to AGENTS.md. Imports across directories (@docs/AGENTS.md) work too.
• Anthropic’s docs state it plainly: “Claude Code reads CLAUDE.md, not AGENTS.md.”
• On Windows both routes have a known problem. The docs tell Windows users to prefer the import because symlinks need Administrator rights or Developer Mode — and there’s an open bug report that the import isn’t expanded in the VS Code extension on Windows, where the agent sees the literal text @AGENTS.md. Same repo, different context depending on your OS and client. That is the split-brain Lütke is describing.
• Use the import shim, not the symlink, and verify it with /context rather than assuming.

What actually happened

Three related requests closed in one day reads as a deliberate triage pass, not a drive-by. The closing comment gave the two bridges and a link to the memory docs. Reporting after the post says a Claude Code team member responded that different model families have different behavioral characteristics and that Claude models have preferences about how instructions are organized, acknowledged that maintaining more than one configuration system creates extra work, and pointed at the same @AGENTS.md import. No commitment either way on native support.

The detail that set the tone is the resolution state. Closing the most-upvoted issue in the repository as completed, when the thing being asked for was not built, converts a live product decision into settled triage. A workaround answers “can I do this?” It doesn’t answer “should every repository have to?”

We tested every persistent bridge

Method: put a made-up deploy command in AGENTS.md and nothing else, start a fresh Claude Code session in that directory with all file-reading tools denied (--disallowed-tools Read Glob Grep Bash …), and ask for the deploy command. With no way to open a file, a correct answer can only come from what was loaded into context at session start. Claude Code 2.1.243, macOS, terminal.

So the widely repeated claim that Claude Code “refuses to read AGENTS.md” is wrong as stated. It reads it fine. It just won’t go looking for it.

The import is the better of the two bridges for a reason that has nothing to do with Windows: a symlinked CLAUDE.md is AGENTS.md, so there’s nowhere to put Claude-specific instructions. With the import you get both — the shared file first, then anything you want to add underneath:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Imports resolve relative to the file containing them, nest up to four hops deep, and are skipped inside backticks and fenced code blocks. Everything imported is expanded into context at launch, so an import organizes your instructions but does not shrink them — a point worth remembering if your shared file is long.

The Windows hole

This is the part no one else has written up, and it’s the part that supports Lütke’s argument better than the ban threat does.

Anthropic’s docs say, verbatim: “On Windows, creating a symlink requires Administrator privileges or Developer Mode, so use the @AGENTS.md import instead.” Sound advice — git on Windows doesn’t materialize symlinks as symlinks unless core.symlinks is on, so a symlinked CLAUDE.md can arrive in a Windows checkout as a one-line text file containing the path AGENTS.md. The agent then loads a file whose entire content is a filename.

But issue #81189, still open, reports that the import route fails too — specifically in the Claude for VS Code extension on Windows, where the agent sees the literal string @AGENTS.md instead of the expanded file, while the same repository works correctly in a terminal on the same machine. That report is one user’s testing, not something Anthropic has confirmed, and we could not reproduce it here because we don’t have a Windows machine. Treat it as a caution, not a verdict.

Take the two together and a mixed team gets this: the symlink is the fragile option on Windows, the import is the recommended option on Windows, and the import has an open report of silently failing in the most common Windows editor. Both failures are quiet. No error, no warning — the agent just doesn’t know the rules everyone assumed it knew.

That is exactly the failure mode worth caring about. A tool that can’t read your instructions is an annoyance you notice immediately. A tool that reads them for some of your team and not others is a correctness problem you find in review, three weeks later.

Live bridge or one-time copy

Two more routes exist, and they are not the same kind of thing.

The bottom two are migrations, not bridges. They snapshot what AGENTS.md said on the day you ran them. Edit AGENTS.md a month later and Claude Code keeps reading the stale copy while every other agent on the team picks up the change — a split brain that is harder to spot than the one Lütke described, because both files exist and both look maintained. If you want one source of truth, use one of the top two. We tested those two; the copy routes we’re describing from Anthropic’s documentation, not from our own run.

What Shopify is actually complaining about

Not “it can’t work.” It can, in about thirty seconds. The complaint is about where the default sits.

Every bridge above is per repository, opt in, forever. Shopify has thousands of developers and a very large codebase. Making this work is not a thirty-second fix there; it’s a policy you have to roll out, enforce on every new repository, and check in CI, because the failure is silent. Any repo that misses the shim gets agents running without the instructions the team believes are in force. Multiply by the number of repos and the number of tools in use and you get what Lütke called a complexity tax — and the reason a CEO is talking about it at all is that platform teams, not individual developers, absorb that tax.

There’s a real argument on the other side, and it deserves to be stated properly. Instruction files are not interchangeable text. CLAUDE.md supports @ imports, CLAUDE.local.md for uncommitted personal notes, a hierarchy that merges managed policy, user, project and subdirectory files, claudeMdExcludes for skipping other teams’ files in a monorepo, and path-scoped rules under .claude/rules/. A file written for a different agent may be tuned to a different tool’s capabilities and a different model’s preferences. Auto-loading it means importing instructions that were never written with your loading rules in mind.

That argument justifies keeping CLAUDE.md as the canonical, feature-rich file. It does not obviously justify refusing to fall back to AGENTS.md when no CLAUDE.md exists at all — which is precisely what issue #89825, filed the day after the post, asks for. That’s the narrow version of the request, and it’s the one that would have made Shopify’s problem disappear without touching anything else.

What to do about it

One repo, or a team on one platform. Add the import shim. A CLAUDE.md whose first line is @AGENTS.md, plus any Claude-specific notes below it. Then run /context in a fresh session and confirm CLAUDE.md appears under Memory files. Don’t skip the check — the failure is silent, so verifying it is the whole job.

A mixed team with Windows developers. Same shim, and add a check that a real human runs at least once on Windows in the VS Code extension: start a session and ask the agent to repeat a distinctive line from AGENTS.md. If it can’t, you’ve hit #81189 and your Windows developers are running without shared instructions. Do not use the symlink here.

A monorepo. Root AGENTS.md with the org-wide facts, per-package AGENTS.md with only the local deltas, and mirror the structure with per-directory CLAUDE.md shims. Our AGENTS.md template has the layout. If ancestor files from other teams keep landing in your context, claudeMdExcludes in .claude/settings.local.json takes glob patterns.

A platform team rolling this out. Treat the shim as a repository template requirement and lint for it, the same way you lint for a license file. Two lines in CI — does CLAUDE.md exist, does it reference AGENTS.md — cost less than one afternoon of debugging why an agent ignored a convention that was written down the whole time.

And keep the files short whichever route you take. Everything here loads into every session of every agent that reads it, and Anthropic’s own guidance is to target under 200 lines per file. The bridge is not the expensive part; what you put across it is.

Companion reading

• CLAUDE.md vs AGENTS.md — which one does Claude Code actually read? — the state of the standard and when to make which file canonical.
• AGENTS.md template — a lean starter, the shim, and the monorepo variation.
• How to write a great CLAUDE.md — what earns its place in a file that loads every session.
• Anthropic deleted 80% of Claude Code’s system prompt and it got better — why shorter instruction files score better.

Sources

1. Feature Request: Support AGENTS.md. — anthropics/claude-code issue #6235
2. Support for AGENTS.md and .agents/skills/ — issue #31005
3. VSCode Extension import failure within CLAUDE.md for adjacent AGENTS.md file — issue #81189
4. Root AGENTS.md not auto-loaded at session start when no CLAUDE.md exists — issue #89825
5. How Claude remembers your project — Claude Code docs
6. Tobi Lütke on X
7. Shopify’s CEO threatened to ban Claude Code. Anthropic had already closed the feature request. — The New Stack
8. Shopify CEO threatens to ditch Claude Code; Anthropic finally responds to AGENTS.md compatibility dispute — BigGo Finance
9. AGENTS.md

FAQ

Does Claude Code read AGENTS.md? Not on its own. Anthropic’s documentation states verbatim that Claude Code reads CLAUDE.md, not AGENTS.md. We confirmed on Claude Code 2.1.243 that a repository containing only an AGENTS.md, with no CLAUDE.md beside it, loads nothing at session start. It will read AGENTS.md if you bridge to it — a CLAUDE.md containing the line @AGENTS.md, or a CLAUDE.md symlinked to AGENTS.md. Both bridges worked in our testing, including imports that point into a subdirectory.

Why did Anthropic close issue #6235? It was closed on August 17, 2026 as completed, by Boris Cherny, with a comment giving the import and symlink workarounds and linking to the memory documentation. It had been open 361 days with 5,026 thumbs-up reactions and 384 comments. Two related requests, #62371 and #84830, were closed the same day. Reporting after Tobi Lütke’s post says a Claude Code team member cited differences in how model families prefer instructions to be organized and acknowledged that maintaining multiple configuration systems creates extra work, without committing to native support either way.

What did Shopify’s CEO actually say? Tobi Lütke posted on X that he was thinking about banning Claude Code at Shopify until Anthropic changes its mind and reads AGENTS.md and .agents/skills, adding that insisting on reading only CLAUDE.md “sometimes leads to split brain problems when different team members use different tools.” He called it unnecessary. It was framed as something he was considering, not an announced policy.

Should I use the import shim or the symlink? The import, in almost every case. A symlinked CLAUDE.md is the same file as AGENTS.md, so there is nowhere to add Claude-specific instructions, and on Windows a symlink needs Administrator rights or Developer Mode — Anthropic’s own docs tell Windows users to prefer the import for that reason. The import also lets you put shared instructions first and Claude-only notes underneath.

Does the AGENTS.md workaround break on Windows? Both routes have a known problem there. Symlinks require elevated rights or Developer Mode, and a symlinked file can arrive in a Windows git checkout as plain text containing a path. Separately, an open issue reports that the @AGENTS.md import is not expanded in the Claude for VS Code extension on Windows, so the agent sees the literal text rather than the file’s contents, while the same repository works in a terminal. That report is one user’s testing and Anthropic has not confirmed it. Verify with /context on each platform your team uses rather than assuming.

Is /import the same as the @AGENTS.md shim? No. /import, available from v2.1.213, appends a one-time copy of files such as AGENTS.md into CLAUDE.md and carries over MCP servers, commands, subagents and skills. It’s a migration, not a link: later edits to AGENTS.md won’t reach Claude Code. The @AGENTS.md import and the symlink both re-read the file at every session start. Use one of those if you want a single source of truth.