Anthropic's Claude Code is refusing to adopt a widely-used instruction format that competing AI coding tools already support, creating compatibility headaches for large engineering teams. Shopify CEO Tobi Lütke said the company is considering banning Claude Code entirely because it won't read AGENTS.md files, a standardized format that helps coding agents understand project-specific rules and conventions.

Why Does a Markdown File Matter So Much?

In large codebases, developers need a way to give AI coding agents consistent instructions about how to build, test, and format code. Files like AGENTS.md and CLAUDE.md act as persistent guidebooks that agents consult as they work through a repository. The problem is that different AI tools have standardized on different formats.

OpenAI introduced AGENTS.md in August 2025 as an industry standard. By December 2025, it was being used across more than 60,000 open-source projects and supported by tools including Codex, Cursor, Gemini CLI, GitHub Copilot, Jules, and VS Code. The format was eventually handed over to the Agentic AI Foundation under the Linux Foundation for broader governance.

Claude Code, however, uses CLAUDE.md instead and doesn't natively read AGENTS.md files. While Anthropic provides workarounds like importing AGENTS.md from within a CLAUDE.md file or using symbolic links, these solutions require manual coordination across large repositories.

What's the Real Problem at Scale?

At Shopify, the stakes are particularly high. The company has thousands of developers working in a massive monorepo, meaning multiple teams are using different AI coding tools simultaneously. If Claude Code doesn't pick up the same instructions as other agents, developers end up working under different rules depending on which tool they're using.

"Agents and Claude files are recursively applied through the tree. With thousands of developers in a mono repo, it just does happen that one directory is missing one of the two files and this means that a subset of devs work with lobotomy," Lütke stated.

Tobi Lütke, CEO at Shopify

Lütke emphasized that while Shopify has built automation to work around the discrepancy, the burden shouldn't fall on engineering teams. "We fix this with automation, but it's a stupid complexity tax that shouldn't have to be paid," he noted.

How Are Developers Requesting Support?

Developers have been asking Anthropic to support AGENTS.md for nearly a year. Recent requests have specifically pushed for recursive AGENTS.md discovery, which would allow Claude Code to automatically find and apply instruction files throughout a repository's directory tree, just as other tools do. Anthropic has closed these requests as "not planned".

• Industry Adoption: A 2026 study of 2,926 GitHub repositories found that context files are now the most common way developers give coding agents instructions, with AGENTS.md already in widespread use across multiple tools
• Competitive Support: Tools including Codex, Cursor, Gemini CLI, GitHub Copilot, Jules, and VS Code all support AGENTS.md natively, while Claude Code does not
• Workaround Burden: Anthropic offers manual workarounds like importing AGENTS.md from CLAUDE.md or using symbolic links, but these require ongoing maintenance in large repositories

Shopify isn't alone in facing this friction. As more companies bring multiple coding agents into the same repositories, keeping those tools synchronized becomes an increasingly complex operational challenge. Platform teams now have to manage compatibility layers and automation just to ensure different AI agents follow the same rules.

Steps to Manage Claude Code in Multi-Agent Environments

• Create Unified Instruction Files: Maintain both CLAUDE.md and AGENTS.md files in your repository, then import AGENTS.md content into CLAUDE.md so Claude Code can access the same instructions as other tools
• Use Symbolic Links: Set up symbolic links from CLAUDE.md to AGENTS.md files throughout your directory tree to reduce duplication and keep instructions synchronized across the monorepo
• Implement Automation Checks: Build scripts that verify every directory containing AGENTS.md also has corresponding Claude Code instructions, catching misalignment before developers encounter split-brain scenarios

The tension between Claude Code and the AGENTS.md standard reflects a broader challenge in the AI coding agent ecosystem. As these tools become more capable and more teams deploy multiple agents simultaneously, standardization becomes less of a convenience and more of an operational necessity. Anthropic's decision to keep Claude Code on its own path, despite industry momentum behind AGENTS.md, suggests the company may be betting that its own format will eventually win out, or that teams will simply accept the added complexity as a cost of using its tool.