Shopify CEO Tobi Lütke Considers Banning Claude Code Over AGENTS.md — Why This “Small” File Could Reshape AI Coding

Key Takeaways

• Shopify CEO Tobi Lütke said on August 25, 2026 that he was considering banning Claude Code at Shopify until it can read AGENTS.md, .agents/skills/, and similar vendor-neutral agent configuration directly.
• The dispute is not really about one Markdown filename. It is about whether repository-level AI instructions belong to a specific coding-agent vendor or should remain portable across tools.
• Claude Code still treats CLAUDE.md as its native project memory file. Teams can import AGENTS.md, reference it from CLAUDE.md, or use a symlink, but those approaches add coordination overhead in large repositories.
• Shopify is unusually sensitive to this problem because its World monorepo contains code, skills, conventions, runbooks, AGENTS.md files, and other machine-readable engineering knowledge used by AI agents at company scale.
• The likely long-term architecture is one vendor-neutral instruction layer plus optional tool-specific overrides rather than separate copies of the same rules for every AI coding product.
• As of August 26, 2026, Claude Code has improved migration and interoperability features, but its official project-memory behavior still distinguishes CLAUDE.md from native AGENTS.md discovery.

What Happened Between Shopify and Claude Code?

On August 25, 2026, Shopify CEO Tobi Lütke publicly challenged Anthropic over how Claude Code handles repository instructions.

Lütke said he was considering banning Claude Code at Shopify until the tool could read AGENTS.md, .agents/skills/, and related shared agent configuration directly. His concern was that insisting on CLAUDE.md can create a split-brain problem when engineers working in the same repository use different AI coding agents.

The wording matters. Shopify did not announce a completed company-wide ban. The statement was a public warning about a tooling design decision that becomes expensive at organizational scale.

Claude Code team member Thariq Shihipar responded that Anthropic is working on making Claude Code more hackable, including easier use of Agents.MD and broader system-prompt customization.

That response makes the episode more than a social-media argument. It exposes a rapidly growing infrastructure question: who owns the project context that AI coding agents rely on?

Why AGENTS.md Matters

AGENTS.md is a repository-level instruction file designed to give coding agents persistent project context.

A useful AGENTS.md can tell an agent:

• how the repository is structured;
• which package manager and commands to use;
• how tests should be run;
• what architectural boundaries must not be crossed;
• which generated files should never be edited manually;
• how database migrations are handled;
• which security or compatibility constraints apply;
• which directory-specific rules override broader defaults.

A simplified example looks like this:

# Repository instructions

Package manager: pnpm

Before opening a pull request:
- run pnpm lint
- run pnpm test
- run pnpm typecheck

Do not edit generated GraphQL files manually.

Changes under packages/payments must preserve backward compatibility.

The important property is not Markdown itself. The important property is portability.

If the same repository is used with Codex, Gemini CLI, Cursor, GitHub Copilot, Claude Code, and future agents, maintaining one canonical set of project rules is safer than maintaining six semantically equivalent copies.

CLAUDE.md vs AGENTS.md: The Real Difference

Claude Code uses CLAUDE.md as its native repository memory mechanism.

That gives Anthropic room to optimize instructions specifically for Claude models and Claude Code workflows. Tool-specific configuration is not inherently bad. In fact, certain instructions can be useful only to Claude Code.

The problem starts when tool-specific configuration becomes the only reliable path to shared repository policy.

A healthy distinction is:

This layered model allows teams to keep the project truth independent from whichever agent happens to be popular this quarter.

What Does “Split Brain” Mean in a Coding Repository?

Consider a large monorepo with nested instructions:

world/
├── AGENTS.md
├── CLAUDE.md
├── checkout/
│   ├── AGENTS.md
│   └── CLAUDE.md
├── payments/
│   ├── AGENTS.md
│   └── payments-api/
│       └── AGENTS.md
└── storefront/
    ├── AGENTS.md
    └── CLAUDE.md

Now assume payments-api/AGENTS.md contains a critical rule:

All settlement API changes must remain backward compatible.

Run the integration suite before modifying settlement state transitions.

An agent that automatically discovers nested AGENTS.md files may receive that rule.

A Claude Code session that relies only on a different hierarchy of CLAUDE.md files may not receive the same information unless the repository has deliberately mirrored or imported it.

Two engineers can therefore ask different agents to modify the same package while unknowingly giving those agents different policy sets.

That is the split brain:

Repository truth
 |
 +--> Agent A sees root + payments + payments-api rules
 |
 +--> Agent B sees root + payments rules only

The code is shared. The AI context is not.

For a small project this can be an inconvenience. For a large company, it becomes an engineering-governance problem.

Why a Symlink Is Not a Complete Enterprise Solution

The obvious workaround is straightforward:

ln -s AGENTS.md CLAUDE.md

Another option is a CLAUDE.md file that imports the shared instructions:

@AGENTS.md

## Claude Code

Use plan mode for changes under src/billing/.

Both are useful and can be perfectly reasonable for small and medium-sized repositories.

The difficulty is not whether the workaround works. The difficulty is ensuring it never stops working anywhere in a huge directory tree.

At scale, teams must answer questions such as:

• Does every nested AGENTS.md have an equivalent Claude-visible path?
• What happens when a team creates a new package and forgets the adapter?
• Are symlinks handled consistently on Windows and in every development environment?
• Does a generated CLAUDE.md drift away from the canonical AGENTS.md?
• Does CI verify the relationship?
• Are local overrides being interpreted consistently?
• Does migration tooling copy configuration once or keep it synchronized over time?

The workaround can therefore create an additional system that itself needs tests, linting, automation, and ownership.

That is why the disagreement is best understood as a complexity-tax argument, not a Markdown argument.

Why Shopify Is an Important Test Case

Shopify has already reorganized significant parts of its engineering environment around AI agents.

Its large monorepo, called World, is not merely a code container. Shopify has described it as holding code alongside skills, conventions, intent documents, runbooks, AGENTS.md files, and written-down domain knowledge.

That matters because repository instructions are no longer decorative documentation. They increasingly act as machine-readable organizational memory.

Shopify's internal agent River demonstrates the scale involved. In a reported 30-day period, River handled tens of thousands of sessions across thousands of Slack channels and co-authored thousands of merged pull requests.

River sits on top of Shopify's agent platform, Aquifer, which separates durable sessions, agent harnesses, sandboxes, credentials, gateways, and observability.

One of the important architectural goals in that platform is replaceability: models, runtimes, and harness implementations should be swappable without forcing the entire surrounding system to change.

A repository knowledge layer tied tightly to one vendor runs against that philosophy.

The Deeper Architecture: Repository Knowledge Should Outlive the Agent

The most important lesson from the Shopify dispute is that the repository is becoming an AI runtime environment.

Historically, a repository contained:

README.md
package.json
.gitignore
CI configuration
source code
tests

An agent-ready repository increasingly contains:

README.md
AGENTS.md
skills/
runbooks/
architecture decisions
tool policies
evaluation rules
automation hooks
repository-specific memory

These files may remain useful for years.

The AI coding tool used by the team may change every few months.

That leads to a fundamental design principle:

Durable project knowledge should have a longer lifecycle than any single agent vendor.

This is the same reason teams prefer portable standards for environment variables, package metadata, source control, and protocol interfaces.

What Claude Code Supports Today

As of August 26, 2026, Claude Code has meaningful interoperability features, but its native project-memory model still centers on CLAUDE.md.

This distinction is easy to miss.

Migration support is not the same as continuous native discovery.

If /import copies an instruction into Claude configuration once, future edits to the original AGENTS.md still need a synchronization strategy unless the resulting configuration references the canonical file.

Why .agents/skills/ Is Part of the Same Debate

Repository instructions answer questions such as:

How should an agent work in this project?

Skills answer a different question:

What reusable capability can the agent load when it needs to perform a specific task?

A skill may include:

release-check/
├── SKILL.md
├── scripts/
├── references/
└── assets/

For example, a release skill could teach an agent how to:

• validate a changelog;
• inspect versioning rules;
• run release tests;
• verify package provenance;
• produce a release checklist.

The Agent Skills format focuses on the skill structure and progressive loading behavior. The .agents/skills/ location has emerged as a cross-client interoperability convention rather than being the only possible installation location defined by the core format.

That nuance matters.

The ecosystem is standardizing on two different layers at once:

1. the format of an agent skill;
2. the places where multiple clients should discover skills.

The Shopify request connects both layers because a portable skill is less useful if every coding agent requires a different directory layout.

Why Anthropic May Still Want CLAUDE.md

There is also a legitimate technical argument on Anthropic's side.

Different model families do not necessarily respond optimally to identical system instructions.

A Claude-specific file can express preferences such as:

@AGENTS.md

## Claude-specific guidance

For complex refactors:
- inspect neighboring abstractions before editing;
- use plan mode before touching more than three packages;
- keep implementation notes concise;
- verify generated artifacts before concluding.

That configuration can coexist with a portable base.

The mistake would be treating portability and model-specific optimization as mutually exclusive.

The stronger architecture is:

          Repository
               |
            AGENTS.md
      shared project policy
               |
     +---------+---------+
     |         |         |
 Claude Code  Codex   Gemini CLI
     |         |         |
 CLAUDE.md  overrides  overrides
 optional tuning

In this model, vendor configuration becomes an override layer, not a duplicated source of truth.

AGENTS.md Is Becoming an Ecosystem Standard

The argument also matters because AGENTS.md is no longer an obscure convention.

After its August 2025 release, the format was reported as adopted by more than 60,000 open-source projects and agent frameworks. The ecosystem includes major coding-agent products and developer environments.

In December 2025, AGENTS.md was contributed to the Agentic AI Foundation under the Linux Foundation, creating a neutral governance path for the convention.

Anthropic is itself part of the broader foundation effort, while its Model Context Protocol represents another major piece of open agent infrastructure.

This creates an important strategic pattern:

• MCP standardizes how agents connect to tools and data.
• AGENTS.md standardizes how repositories communicate project instructions.
• Agent Skills standardize reusable bundles of procedural knowledge.
• Vendor-specific files optimize behavior for a particular agent.

These layers solve different problems and can work together.

The Emerging Open Agent Stack

A mature agent-ready project may eventually look like this:

project/
├── AGENTS.md
├── .agents/
│   └── skills/
│       ├── deploy/
│       │   └── SKILL.md
│       ├── database-migration/
│       │   └── SKILL.md
│       └── security-review/
│           └── SKILL.md
├── CLAUDE.md
├── .claude/
│   └── skills/
├── .cursor/
├── package.json
└── src/

The long-term goal should not be to eliminate every vendor directory.

The goal should be to make vendor directories optional specialization layers.

A team should be able to remove one coding agent and adopt another without losing the project's architectural memory.

Practical Setup for Multi-Agent Teams Today

Until native behavior converges, teams can reduce risk with a canonical-source strategy.

1. Put shared policy in AGENTS.md

Keep architecture, commands, tests, safety rules, and directory-specific constraints in the portable file.

Avoid putting core repository truth only in CLAUDE.md.

2. Make CLAUDE.md import the canonical file

@AGENTS.md

## Claude Code-specific instructions

Prefer plan mode for cross-package refactors.

This keeps duplication low while preserving Claude-specific tuning.

3. Add CI checks for nested files

Large monorepos should detect when a new nested AGENTS.md is created without a compatible Claude Code path.

A conceptual check might enforce:

for every nested AGENTS.md:
  verify Claude Code can reach the same canonical instructions

The exact implementation depends on the repository hierarchy and chosen import strategy.

4. Test agent context, not just files

A repository can contain the right Markdown files and still load the wrong context.

Teams should periodically verify:

• which memory files the agent actually loaded;
• which nested instructions apply at the current working directory;
• whether imported content is current;
• whether conflicting rules exist;
• whether local configuration unintentionally overrides shared policy.

5. Keep vendor-specific instructions small

If CLAUDE.md becomes a second full project handbook, configuration drift becomes almost inevitable.

A good target is:

AGENTS.md = project truth
CLAUDE.md = Claude-specific delta

Common Pitfalls

Duplicating the Entire Instruction Set

Copying the same 500-line policy into several vendor files feels safe at first.

It is usually the highest-risk approach because the copies diverge silently.

Treating One-Time Imports as Synchronization

Migration tools help adoption. They do not automatically guarantee that future changes remain synchronized.

Teams should distinguish between:

• copying configuration;
• referencing configuration;
• discovering configuration natively.

Ignoring Nested Directory Semantics

The biggest failures often happen below the repository root.

A root-level adapter can appear correct while package-level instructions remain invisible to one agent.

Mixing Portable Policy With Model Prompt Tuning

Rules such as database compatibility requirements belong in shared project policy.

Instructions such as how a specific model should plan a large refactor belong in vendor-specific configuration.

Keeping those concerns separate makes migrations far easier.

Assuming Every Skill Directory Is Equivalent

A skill format can be portable even when discovery paths differ between clients.

Teams should test how each client finds both project-level and user-level skills.

What Happens Next?

The most likely outcome is not the disappearance of CLAUDE.md.

The more likely outcome is increased interoperability.

Claude Code has already added stronger initialization and import paths for configuration created by other coding tools. Anthropic has also publicly indicated that easier Agents.MD usage is part of work to make Claude Code more customizable.

The next meaningful milestones to watch are:

• native AGENTS.md discovery without an adapter;
• documented precedence rules between AGENTS.md and CLAUDE.md;
• native or officially standardized .agents/skills/ discovery;
• clearer behavior for nested instruction files;
• a compatibility layer that preserves model-specific optimization;
• cross-agent tests that let enterprises verify which instructions each tool actually loaded.

Those details will determine whether interoperability is only convenient for individual developers or reliable enough for large organizations.

Why This Dispute Is Bigger Than Claude Code

Coding-agent competition is moving beyond raw model quality.

Enterprises increasingly need answers to infrastructure questions:

• Can a repository change coding agents without rewriting its knowledge layer?
• Can skills move between clients?
• Can agents share the same architectural constraints?
• Can organizations audit which instructions influenced an automated code change?
• Can an agent configuration remain valid when the underlying model changes?
• Can a monorepo maintain one authoritative set of AI-readable policies?

These are the questions that determine whether AI coding remains a collection of personal productivity tools or becomes durable engineering infrastructure.

The Shopify episode is important precisely because Shopify is already operating on the second side of that transition.

Conclusion

Tobi Lütke's criticism of Claude Code looks trivial only if AGENTS.md is viewed as a text file.

At enterprise scale, it represents something much larger: the ownership and portability of machine-readable engineering knowledge.

Claude Code's CLAUDE.md remains useful for Claude-specific optimization. AGENTS.md is useful for vendor-neutral repository truth. The most robust future is likely to support both, with clear precedence and native interoperability rather than forcing teams to duplicate configuration.

For engineering teams using multiple AI coding agents today, the practical rule is simple: keep shared project knowledge canonical, keep vendor-specific layers thin, and verify the context agents actually load.

The winners in the next phase of AI coding may not be the tools with the most proprietary configuration. They may be the tools that fit most cleanly into an open, portable agent stack.