Tobi Threatens Claude Code Ban Over AGENTS.md — Shopify Split-Brain Problem

Filename politics, real split-brain.

On August 25, 2026, Shopify CEO Tobi Lutke posted on X (~174K views) that he was thinking about banning Claude Code at Shopify until Anthropic "change their mind and read AGENTS.md and .agents/skills etc." His exact complaint: insisting on only reading CLAUDE.md "sometimes leads to split brain problems when different team members use different tools. Just unnecessary."

That is not a product launch. It is a CEO-level escalation of a problem every multi-harness shop already feels: one repo, three instruction trees, and no vendor willing to lose their branded filename.

TL;DR — what people are asking

What Tobi actually said

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 thread picked up quickly:

• DHH replied that it was "so unnecessary" and tagged Anthropic's Thariq Shihipar to "talk some sense."
• Mark Schellhas (Aug 4) had already posted the symlink recipe: CLAUDE.md → AGENTS.md, .claude → .agents.
• Mohammed A.I. said his CLAUDE.md workaround is one word — @AGENTS.md — and that he switched to OpenCode and pi for AGENTS-first workflows.
• Phil Hie dryly noted that "threatening a vendor with a ban over a filename is peak tobi."

All of those reactions are useful. None of them cancel the underlying issue.

Why split-brain happens

Modern repos no longer standardize on one coding agent. A Shopify-scale monorepo might have:

When Alice commits team standards to AGENTS.md because she lives in Codex, and Bob's Claude Code session never loads that file, you get two truths:

1. Bob's agent misses Alice's lint philosophy, test commands, and safety rules.
2. Alice's PR review catches "violations" Bob's harness never saw coming.

That is not model quality. That is context routing. explainx.ai's agent markdown files guide maps fifteen-plus filename conventions; Tobi's post is what happens when a company mandates AI usage before those conventions converge.

Shopify is an extreme case — reflexive AI is a baseline expectation, headcount asks require proving AI cannot do the job — but the filename fight scales down to any team running Cursor and Claude Code side by side.

Copy-paste fixes (today, not after a vendor meeting)

Option 1 — full symlink (Schellhas pattern)

# From repo root — pick ONE canonical source (usually AGENTS.md)
ln -sf AGENTS.md CLAUDE.md
ln -sf .agents .claude
git add CLAUDE.md .claude   # symlinks commit like normal files on most setups

Verify both harnesses resolve the same inode:

readlink CLAUDE.md .claude
ls -la AGENTS.md CLAUDE.md

Option 2 — one-word CLAUDE.md pointer

If symlinks break on a teammate's Windows checkout, a minimal CLAUDE.md can defer:

@AGENTS.md

Claude Code loads the pointer; the body lives in AGENTS.md. This is a community workaround, not documented Anthropic behavior — test on your version before rolling out org-wide.

Option 3 — skills-only alignment

Keep separate top-level files if you must, but unify skills:

ln -sf ../.agents/skills .claude/skills

Skills carry procedures (progressive disclosure keeps token cost down). Split skill trees hurt worse than split root files because procedures diverge silently.

Why Anthropic prefers CLAUDE.md (and why that annoys enterprises)

Claude Code launched with CLAUDE.md as its persistent memory layer — project facts, build commands, conventions loaded every session. Anthropic also ships Skills under .claude/skills/ with lazy loading. That stack is coherent inside Claude Code.

The cross-vendor AGENTS.md project — uppercase plural, tool-agnostic — emerged because Codex, OpenCode, Gemini CLI, and others needed a neutral filename teams could commit without picking a vendor mascot. explainx.ai's AGENTS.md code-quality post treats it as the durable place for judgment calls; linters and CI handle enforcement.

Anthropic is not wrong to optimize for its own harness. Enterprise buyers are not wrong to want one file per repo. Those two truths collide in Tobi's timeline.

Replies asking "why doesn't Anthropic just read AGENTS.md?" miss the product strategy: CLAUDE.md is a brand surface and a tuned loading path, not an accident. Whether that survives Shopify-scale pressure is now a public question.

What Shopify teams should do this week

1. Pick a canonical file — usually AGENTS.md if Codex/OpenCode share the repo, or CLAUDE.md if Claude Code is the majority of sessions. Document the choice in README, not in a third file.
2. Symlink the other name — do not maintain two copies. Duplicated instruction files drift within days.
3. Audit skills directories — grep for .claude/skills and .agents/skills divergence; merge or symlink.
4. Keep enforceable rules out of markdown — architecture boundaries, formatting, and test gates belong in CI (Sanglard's two-layer pattern).
5. Do not wait for a ban — Tobi's post is leverage, not a roadmap. Ship the symlink before legal talks to Anthropic.

For harness comparison and token overhead when running multiple tools on the same repo, see the Systima Claude Code vs OpenCode study — fat instruction files bill on every turn regardless of filename.

Honest limitations

• Symlinks on Windows — require Developer Mode or admin rights for unprivileged symlinks; some teams use the @AGENTS.md pointer instead.
• No native AGENTS.md in Claude Code — as of August 25, 2026; future Anthropic releases could change this without updating your repo.
• Cursor rules are a third tree — symlinks fix Claude/Codex/OpenCode alignment; Cursor users may still need .cursor/rules imports or duplication.
• Ban threat ≠ policy — treat Tobi's post as signal, not HR guidance. Your org's vendor mix may differ.

Related on explainx.ai

• Agent markdown files — complete guide
• AGENTS.md for code quality vs linters
• What is CLAUDE.md?
• CLAUDE.md vs SKILL.md vs MCP
• What are agent skills?
• Steering Claude Code — CLAUDE.md, skills, hooks
• Meta 73.7T tokens — Spotify & Shopify AI engineering
• Claude Code everyday users — usage drift (companion)

Sources

• Tobi Lutke (@tobi) — August 25, 2026 X post (~174K views)
• Thread replies: DHH, Mark Schellhas (symlink recipe, Aug 4), Mohammed A.I., Phil Hie

Tobi's post and reply counts reflect public X visibility as of August 25, 2026. Symlink behavior varies by OS and git settings — test on your checkout before org-wide rollout. Follow @explainx_ai for harness-standard updates.