Shopify’s leadership announced a potential ban on Anthropic’s Claude Code because the tool does not natively consume the AGENTS.md files that many projects use for agent instructions. In a monorepo with thousands of developers, this mismatch creates divergent behavior between coding agents, forcing the platform team to add custom automation to keep the repository consistent.
Claude Code configuration gap
Claude Code reads CLAUDE.md files and can discover them recursively as it traverses a repository. By contrast, the industry‑wide AGENTS.md format—introduced by OpenAI in August 2025 and now used by dozens of tools—remains invisible to Claude Code. Anthropic has offered workarounds such as importing AGENTS.md content into CLAUDE.md or using symbolic links, but the company has officially closed the feature request for native AGENTS.md support as “not planned.”
Why the divergence matters to engineering teams
When a directory contains an AGENTS.md file but lacks a matching CLAUDE.md, developers using Claude Code receive a different set of instructions than those using other agents. In a large monorepo this can lead to a “split‑brain” situation where a subset of developers operate with incomplete or conflicting guidance, a problem Shopify’s CEO described as “lobotomy.” The practical impact includes:
- Inconsistent code generation or linting results across teams.
- Additional manual steps or scripts to synchronize instruction files.
- Higher cognitive load for developers who must remember which tool respects which file.
Architectural and operational implications
From an architecture perspective the mismatch forces platform teams to treat instruction files as a separate configuration artifact that must be kept in sync. This adds a “complexity tax” in the form of automation pipelines that copy or link AGENTS.md content into CLAUDE.md locations. Operationally, the extra scripts become part of the CI/CD flow, increasing the surface area for failures and requiring monitoring. Security engineers should note that divergent instruction sets could cause agents to apply different build or testing commands, potentially bypassing established hardening steps if a tool follows an outdated or incomplete file.
Related CloudNinjas coverage: AI engineering.
What This Means For Practitioners
Teams should evaluate their repository’s instruction‑file strategy and consider one of the following actions:
- Standardize on a single format (e.g., adopt
AGENTS.mdacross all agents) and deprecateCLAUDE.mdwhere possible. - Implement repository‑wide checks that verify the presence of both files in every relevant directory, treating mismatches as build failures.
- Monitor Anthropic’s roadmap for any change in native
AGENTS.mdsupport, and be prepared to adjust automation if the feature becomes available. - Document the chosen approach in internal engineering guidelines to reduce “split‑brain” risk for new developers.
By treating instruction files as a first‑class configuration concern, platform and DevOps teams can limit the operational overhead and keep AI‑assisted development consistent across large codebases.
