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.

Updated August 26, 2026: Claude Code engineer Thariq Shihipar replied publicly (~461.5K views on the reply). Anthropic is working on making Claude Code more hackable — including easier AGENTS.md use and other system-prompt modifications — with details promised at rollout. See the new section below.

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.

Thariq's official response (August 25–26)

DHH's tag worked. Thariq Shihipar, who works on Claude Code at Anthropic, replied directly to Tobi on the evening of August 25 (~461.5K views on the reply thread). The headline: Anthropic heard the feedback and is working on making Claude Code more hackable — explicitly including easier AGENTS.md support and other system-prompt modifications, with more detail promised when it is ready to ship.

The reasoning Thariq gave is not filename stubbornness for its own sake. Anthropic treats model families as non-interchangeable: the system prompt materially affects performance, and Claude Code already runs different system prompts per model. That connects to his July 24 context-engineering thread — Anthropic removed roughly 80% of Claude Code's system prompt for the newest Claude 5 models with no eval loss, because over-constraining older models (rules like "DO NOT WRITE COMMENTS") wastes reasoning tokens on less capable weights.

For the immediate term, Thariq pointed Tobi at the documented workaround: put @AGENTS.md in CLAUDE.md and Claude Code inlines the shared file at session start. He acknowledged the upkeep is "not worth the squeeze for everyone" and said feedback was heard.

Community pushback in the same thread sharpened the debate without resolving it:

• David Cramer (@zeeg): Anthropic should "build for 6 months from now" — minor model variance will not persist, and per-model instruction files do not scale.
• Thariq's counter: the intelligence gap between models people actually use will keep widening; weaker models still need hard constraints that top-tier models do not.
• Kun Chen (@kunchenguid): wrong philosophy for open repos — he runs five models regularly, contributors use a dozen more; maintaining 17 fine-tuned AGENTS.md files per model is absurd.
• Stephen Benjamin (@stbenjam): the sprawl goes deeper than root filenames — .agents, .github, .claude, .cursor, .gemini, .opencode skill trees in one repo is exhausting; asked about Agent Plugins support.

explainx.ai's read: Thariq's reply is the first public commitment toward native AGENTS.md ergonomics, but it is not a ship date. Symlinks and @AGENTS.md pointers remain the enterprise fix until the hackable rollout lands. For the model-specific prompt rationale in depth, see Claude 5 context engineering.

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. Thariq's August 25 reply confirms Anthropic is now building toward easier cross-format use — but until that ships, Shopify-scale pressure continues.

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 yet — Thariq pledged hackable support is coming (Aug 25); symlinks remain the fix today.
• 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.

Update — September 4, 2026: The AGENTS.md interop question resurfaced under Anthropic's Function Hooks preview — a reply asked directly whether the new plugin system would support it. See Function Hooks and ant apply: Claude Code's Terraform Moment for that thread and Anthropic's separate, shipped ant apply CLI.

Related on explainx.ai

• Function Hooks and ant apply — Claude Code's Terraform moment
• 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)
• Thariq Shihipar (@trq212) — August 25, 2026 reply (~461.5K views); Jul 24 context-engineering thread
• Thread replies: DHH, Mark Schellhas (symlink recipe, Aug 4), Mohammed A.I., Phil Hie, David Cramer (@zeeg), Kun Chen (@kunchenguid), Stephen Benjamin (@stbenjam)

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