Shopify施压Claude Code：AGENTS.md之争为何关乎企业AI编程标准

围绕 Claude Code 是否应该读取 AGENTS.md 和 .agents/skills，一场看似普通的配置文件争议，正在暴露企业使用 AI 编程工具时的现实难题。

根据相关讨论，Shopify CEO Tobi Lütke 对 Claude Code 的兼容策略表达了明确态度：如果工具继续依赖自己的 CLAUDE.md 与技能目录，而不能兼容团队通用配置，企业就可能重新考虑是否继续使用。

这并不只是“多维护一个 Markdown 文件”那么简单。对大型工程团队而言，项目规则一旦分散，就会直接增加管理成本，并让不同 Coding Agent 产生不一致的执行结果。

核心矛盾：同一仓库出现两套指令

现代开发团队往往不会只使用一种 AI编程工具。同一个代码仓库中，可能同时存在 Codex、Cursor、Claude Code，以及其他自动化审查或代码生成工具。

越来越多工具开始支持 AGENTS.md，团队可以在其中集中记录：

• 项目目录结构与模块职责
• 代码格式和命名规则
• 构建、测试及检查命令
• 禁止修改的文件或目录
• 提交代码前必须完成的步骤
• Agent 执行任务时需要遵守的边界

但 Claude Code 主要使用 CLAUDE.md，并通过 .claude/skills 管理相关能力。由此可能产生一个直接问题：同一项目中的不同 Agent，读取到的规则并不完全相同。

什么是“脑裂”问题

所谓“脑裂”，可以理解为一个仓库拥有两套彼此独立的 Agent Context。例如，AGENTS.md 要求使用 pnpm test，CLAUDE.md 却仍然保留旧的 npm test；一份文件禁止修改数据库迁移记录，另一份文件没有同步这项限制。

最终可能出现以下情况：

1. 不同 Agent 对相同任务给出不同方案。
2. 某些工具执行了已经废弃的命令。
3. 代码生成结果不符合团队最新规范。
4. 开发者难以判断哪份配置才是最终标准。
5. 自动化流程出现偶发且难以复现的问题。

个人项目手动同步两份文件或许还能接受，但大型团队中的规则会频繁更新。工程师数量越多、仓库越复杂，配置同步的成本就越高。

企业为什么在意通用配置标准

企业采购开发工具，不只比较模型能力，还会评估接入成本、治理能力与替换难度。

降低长期维护成本

如果每引入一种 Coding Agent，就要额外创建一套专属规则，团队很快会面对多个平行配置。安全要求、测试方式或目录结构每次调整，都必须同步修改多处内容。

这类重复工作不能直接创造业务价值，却可能因为一次遗漏造成代码质量或合规问题。企业更希望建立一份统一的 企业开发规范，让不同工具读取同一个可信来源。

避免被单一工具绑定

专有配置可以提供更深的功能，但也会增加迁移成本。如果项目规范大量写入某家工具独有的文件和技能目录，后续更换 Agent 时就需要重新整理。

AGENTS.md 的价值正在于开放和易迁移。它不要求团队把工程规则绑定到特定模型，也有利于多种工具在同一仓库中协同工作。

让采购权影响工具路线

当大型企业明确提出兼容要求时，影响往往不止一个客户。模型能力再强，如果不能融入现有工程体系，也可能在企业采购评估中失分。

因此，这场讨论真正关注的不是哪个文件名更好，而是谁来决定 Coding Agent 的项目配置方式：工具厂商、企业用户，还是一个可被广泛支持的公共约定。

实用方案：建立单一规则源

在相关工具尚未完全统一之前，团队不必手动维护两份独立内容。更稳妥的做法是建立一个“单一事实来源”，再自动生成 AGENTS.md 和 CLAUDE.md。

推荐目录结构

project/
├── docs/
│   └── agent-guidelines.md
├── AGENTS.md
├── CLAUDE.md
└── scripts/
    └── sync-agent-rules.py

其中，docs/agent-guidelines.md 保存通用规则；两个入口文件由脚本生成。某个工具独有的说明，则放在对应文件的附加区域，不要混入公共规则。

简单的同步脚本

from pathlib import Path

root = Path(__file__).resolve().parent.parent
source = root / "docs" / "agent-guidelines.md"
content = source.read_text(encoding="utf-8")

header = "<!-- 此文件由脚本生成，请勿直接修改 -->\n\n"

for filename in ("AGENTS.md", "CLAUDE.md"):
    (root / filename).write_text(header + content, encoding="utf-8")

print("AGENTS.md 与 CLAUDE.md 已完成同步")

团队还可以在 CI 中运行该脚本，并检查生成文件是否存在未提交的变化。一旦有人修改公共规范却忘记同步，流水线就会及时提醒。

需要注意的是，AGENTS.md 与 CLAUDE.md 的具体能力并不一定完全相同。自动同步适合复制通用规则，但技能声明、专属命令和工具权限仍应分别维护，不能简单假设两个体系完全等价。

团队落地时应检查什么

准备同时接入多种 Agent 的团队，可以优先完成以下工作：

• 明确哪份文件是项目规则的唯一来源。
• 将测试、构建和格式化命令写成可直接执行的形式。
• 为危险操作、敏感目录和生成文件设置清晰边界。
• 在 CI 中验证多个配置文件是否保持同步。
• 定期删除过期指令，避免 Agent 执行旧流程。
• 评估新工具时，把开放配置兼容性列入采购标准。

结语

AGENTS.md 与 CLAUDE.md 之争，表面上是文件兼容问题，实际反映了 AI 编程进入企业后的标准化需求。企业需要的不只是更聪明的模型，还需要稳定、统一、可审计且容易迁移的工程配置。

未来更有竞争力的 Coding Agent，很可能不是要求团队围绕工具重新建立规则，而是主动兼容现有项目规范。对开发团队来说，现阶段最实际的选择，就是尽早建立单一规则源，通过脚本和 CI 消除两套配置长期分叉的风险。