Claude Code’s AGENTS.md Stance Exposes the Cost of Tool Fragmentation

Introduction

A Markdown file has become a fault line between AI coding tools. Shopify CEO Tobi Lütke publicly said that Shopify might disable Claude Code internally unless Anthropic allows it to read AGENTS.md. For an individual developer, this may look like a minor filename mismatch. For an enterprise with thousands of developers and a large monorepo, however, it can become a recurring “complexity tax.”

What is at stake

AGENTS.md and CLAUDE.md are repository instructions for coding agents. They can describe build commands, testing requirements, coding conventions, and operational boundaries. When an agent works in a directory, it can load relevant instruction files from the directory tree, with more local rules generally taking precedence.

The compatibility problem is that AGENTS.md, introduced by OpenAI, has been adopted by tools including Codex, Cursor, Gemini CLI, GitHub Copilot, Jules, and VS Code. The format was later moved to the Linux Foundation’s Agentic AI Foundation. Claude Code follows a different path: it uses CLAUDE.md and does not natively read AGENTS.md. A repository may therefore provide complete context to one agent while leaving Claude Code without the same rules.

That gap is difficult to manage manually in a large codebase. Teams may need imports, symbolic links, recursive discovery scripts, file watchers, startup configuration, and Git ignore rules to keep the two systems aligned. The material describes a Mac-based workaround using fswatch and launchd. Such a setup can reduce the immediate problem, but it also demonstrates that companies are building infrastructure merely to compensate for a product-level compatibility choice.

Why Anthropic’s reply did not settle the issue

Thariq, a member of the Claude Code team, said Anthropic is improving customization and will make it easier to use AGENTS.md or modify related system prompts. For now, the workaround is to reference “@AGENTS.md” from CLAUDE.md. The response did not clearly say that Claude Code would automatically discover AGENTS.md in the same way as other tools.

Anthropic’s rationale is that different models may require different context, skills, and system prompts. Developers counter that organizations already use several models, and asking them to maintain a separate instruction set for every model would move adaptation costs from the product to the repository. Model-specific behavior can be handled inside the harness; users should not have to maintain a growing collection of parallel Markdown files.

Broader implications

The real issue is not whether one filename is inherently better. It is who pays for incompatibility. A symbolic link or import may be acceptable for an individual user, but enterprise instruction files are shared engineering assets. Recursive loading, visibility into which rules were applied, and consistency across tools should ideally be platform capabilities.

Anthropic can retain CLAUDE.md for Claude-specific extensions while supporting AGENTS.md as the default shared layer. Without that balance, developers may see the dispute as more than a file-format preference: it becomes a question of whether one tool deserves a separate ecosystem that every team must maintain.

Source: InfoQ 中文