最近开发者社区里有一个争论传得很快Shopify CEO 在社交平台上公开说他正在考虑在公司范围内禁用 Claude Code原因不是模型能力不够也不是价格问题而是这个工具不兼容 AGENTS.md。消息传开之后社区立刻分成两派。一派觉得这是审慎的管理决策另一派觉得为了一个 Markdown 配置文件就上纲上线多少有点小题大做。我的看法更偏向前者。这件事真正的信息量不在“Claude Code 到底行不行”而在一个更底层的问题上当越来越多 AI 编程代理走进代码仓库时仓库里那份说明文件正在从“可读可不读的建议”变成“必须遵守的合同”。一个不认合同的工具就算能力再强也会被严肃的团队请出局。这篇文章不打算替任何一方站台。我更想把这件事拆开来看AGENTS.md 到底是什么为什么它能引起一个 CEO 的“禁用”念头Claude Code 在这段讨论里处在什么位置以及如果你也在用 AI 编程工具该怎么把这类指令文件真正接入工程流程。1. 先还原一下这件事不是“工具不好用”是“工具不守规矩”1.1 事件的基本脉络先说清楚这篇文章讨论的事件来自公开报道和社区讨论细节还在快速变化我尽量只讲在多个来源中反复出现的事实。大致脉络是Shopify CEO 提到他正在考虑把 Claude Code 加入公司开发环境的禁用名单理由是 Claude Code 没有正确对待 AGENTS.md 文件。对于 Shopify 这种规模的工程团队来说这其实不是一句随口的吐槽。一旦一个工具进入公司开发流程它就会接触大量内部代码、执行本地命令、修改文件。如果它不遵守仓库里约定的规则团队就没法在“允许它做什么”和“禁止它做什么”之间建立信任。所以这不是一个“个人喜好”问题而是团队对工具可用性的基本判断。1.2 AGENTS.md 到底是什么AGENTS.md 是一个 Markdown 文件通常放在仓库根目录或关键子目录里作用是给 AI 编程代理提供“在这个仓库里怎么干活”的说明。它和 README 最大的区别是读者不同README 是给人看的AGENTS.md 是给代理看的。一份合格的 AGENTS.md 通常包含这些内容项目是什么、技术栈是什么。构建、测试、类型检查的常用命令。目录结构和架构约定。必须遵守的规则比如“不要改动生成文件”“新增代码必须带测试”。推荐的工作流比如“先补测试再实现”。下面是一个示例结构# AGENTS.md ## 项目概述 这是一个面向中小团队的订单管理系统使用 Next.js PostgreSQL。 ## 常用命令 - 启动开发服务器: npm run dev - 运行测试: npm test - 类型检查: npm run typecheck ## 架构约定 - 业务逻辑放在 src/domain/services - 数据访问层使用 Prisma 生成的 client - 新接口必须带输入校验不能直接信任前端参数 ## 禁止事项 - 不要直接修改 package-lock.json除非依赖确实变更 - 不要绕过 eslint也不要对已有禁用的 lint 规则开例外这个格式只是示例真正的内容取决于仓库复杂度、团队偏好和工具的解读方式。但关键点很清楚AGENTS.md 不是给人看的文档它是一组可执行的约束。1.3 为什么一个 CEO 会为一份说明文件较真因为一旦一个团队开始同时使用多个 AI 编程工具问题立刻就来了。Cursor 读 AGENTS.md某些 CI 代理也读 AGENTS.md但 Claude Code 早期主要读自己的 CLAUDE.md。如果团队必须维护两份指令文件就会遇到一个经典的工程问题不同步。今天在 AGENTS.md 里加了一条安全约束明天 CLAUDE.md 里忘了同步代理就可能做出违规动作。我见过不少团队在引入 AI 编程工具时最担心的其实不是模型笨而是模型“不守规矩”。代码写得慢可以重写但代理在不知情的情况下改了不该改的文件、删了不该删的逻辑、把密钥格式改乱了这些问题修复成本非常高。所以“不兼容 AGENTS.md”对普通用户来说也许只是“少读一个文件”对一个大团队来说是信任问题。一个不认仓库规则的代理会被视为不可治理的工具。CEO 的第一反应是“禁用”而不是“让开发人员手动约束它”也就可以理解了。下面是几个常见指令文件的简单对比文件主要读者作用维护方式README.md人介绍项目、安装方式、用法项目维护者AGENTS.mdAI 编程代理定义代理在仓库内的工作方式团队共同维护CLAUDE.mdClaude Code给 Claude Code 的项目上下文使用 Claude Code 的开发者.cursorrulesCursor给 Cursor 的特定规则使用 Cursor 的开发者2. 从“读文件”到“守合同”指令文件正在变成工程基础设施2.1 AGENTS.md 解决的是“代理上下文”问题AI 编程代理和普通脚本最大的区别在于它每次运行都可能面对一个全新的上下文窗口。它没有团队记忆也不会主动去看你的 Wiki 和架构文档。如果没有一个稳定、可见、可版本管理的入口代理对仓库的理解就只能靠随机探索和模型先验结果自然不稳定。AGENTS.md 就是那个入口。它把“项目怎么构建、代码怎么组织、什么不能碰”提炼成代理进入仓库后第一件应该读取的文件。这样无论你用的是哪个模型、哪个工具只要它认这份文件它的初始行为就会收敛到一个相对可控的范围。这个思路和给新员工做入职手册是一样的。一个没有 onboarding 文档的团队新人上手全凭打听有了一份规范文档新人至少不会在第一天就踩进最明显的坑。AGENTS.md 就是把这样的手册从“给人看”扩展到“给代理看”。2.2 兼容性不是功能清单而是生态位问题讨论 AGENTS.md 兼容性时很多人的第一个疑问是不就是读一个 Markdown 文件吗有什么难的难点不在解析文件而在“优先级”和“执行承诺”。一个工具可以在启动时读取 AGENTS.md但如果用户在对话里说了一句话把 AGENTS.md 里的规则覆盖了这个工具到底是遵守规则还是遵守对话指令这是一个产品决策不是技术难点。更现实的问题是如果工具只把自己私有格式的指令文件当作“一等公民”而对社区通用的 AGENTS.md 只是“顺带支持”那么在一个多工具协作的团队里AGENTS.md 很容易成为那个被遗忘的文件。一旦出现分歧代理的行为就不守恒了。所以在基础设施 AGENTS.md兼容性引争议：AI编程代理的“工程合同”如何左右工具存废？
最近开发者社区里有一个争论传得很快Shopify CEO 在社交平台上公开说他正在考虑在公司范围内禁用 Claude Code原因不是模型能力不够也不是价格问题而是这个工具不兼容 AGENTS.md。消息传开之后社区立刻分成两派。一派觉得这是审慎的管理决策另一派觉得为了一个 Markdown 配置文件就上纲上线多少有点小题大做。我的看法更偏向前者。这件事真正的信息量不在“Claude Code 到底行不行”而在一个更底层的问题上当越来越多 AI 编程代理走进代码仓库时仓库里那份说明文件正在从“可读可不读的建议”变成“必须遵守的合同”。一个不认合同的工具就算能力再强也会被严肃的团队请出局。这篇文章不打算替任何一方站台。我更想把这件事拆开来看AGENTS.md 到底是什么为什么它能引起一个 CEO 的“禁用”念头Claude Code 在这段讨论里处在什么位置以及如果你也在用 AI 编程工具该怎么把这类指令文件真正接入工程流程。1. 先还原一下这件事不是“工具不好用”是“工具不守规矩”1.1 事件的基本脉络先说清楚这篇文章讨论的事件来自公开报道和社区讨论细节还在快速变化我尽量只讲在多个来源中反复出现的事实。大致脉络是Shopify CEO 提到他正在考虑把 Claude Code 加入公司开发环境的禁用名单理由是 Claude Code 没有正确对待 AGENTS.md 文件。对于 Shopify 这种规模的工程团队来说这其实不是一句随口的吐槽。一旦一个工具进入公司开发流程它就会接触大量内部代码、执行本地命令、修改文件。如果它不遵守仓库里约定的规则团队就没法在“允许它做什么”和“禁止它做什么”之间建立信任。所以这不是一个“个人喜好”问题而是团队对工具可用性的基本判断。1.2 AGENTS.md 到底是什么AGENTS.md 是一个 Markdown 文件通常放在仓库根目录或关键子目录里作用是给 AI 编程代理提供“在这个仓库里怎么干活”的说明。它和 README 最大的区别是读者不同README 是给人看的AGENTS.md 是给代理看的。一份合格的 AGENTS.md 通常包含这些内容项目是什么、技术栈是什么。构建、测试、类型检查的常用命令。目录结构和架构约定。必须遵守的规则比如“不要改动生成文件”“新增代码必须带测试”。推荐的工作流比如“先补测试再实现”。下面是一个示例结构# AGENTS.md ## 项目概述 这是一个面向中小团队的订单管理系统使用 Next.js PostgreSQL。 ## 常用命令 - 启动开发服务器: npm run dev - 运行测试: npm test - 类型检查: npm run typecheck ## 架构约定 - 业务逻辑放在 src/domain/services - 数据访问层使用 Prisma 生成的 client - 新接口必须带输入校验不能直接信任前端参数 ## 禁止事项 - 不要直接修改 package-lock.json除非依赖确实变更 - 不要绕过 eslint也不要对已有禁用的 lint 规则开例外这个格式只是示例真正的内容取决于仓库复杂度、团队偏好和工具的解读方式。但关键点很清楚AGENTS.md 不是给人看的文档它是一组可执行的约束。1.3 为什么一个 CEO 会为一份说明文件较真因为一旦一个团队开始同时使用多个 AI 编程工具问题立刻就来了。Cursor 读 AGENTS.md某些 CI 代理也读 AGENTS.md但 Claude Code 早期主要读自己的 CLAUDE.md。如果团队必须维护两份指令文件就会遇到一个经典的工程问题不同步。今天在 AGENTS.md 里加了一条安全约束明天 CLAUDE.md 里忘了同步代理就可能做出违规动作。我见过不少团队在引入 AI 编程工具时最担心的其实不是模型笨而是模型“不守规矩”。代码写得慢可以重写但代理在不知情的情况下改了不该改的文件、删了不该删的逻辑、把密钥格式改乱了这些问题修复成本非常高。所以“不兼容 AGENTS.md”对普通用户来说也许只是“少读一个文件”对一个大团队来说是信任问题。一个不认仓库规则的代理会被视为不可治理的工具。CEO 的第一反应是“禁用”而不是“让开发人员手动约束它”也就可以理解了。下面是几个常见指令文件的简单对比文件主要读者作用维护方式README.md人介绍项目、安装方式、用法项目维护者AGENTS.mdAI 编程代理定义代理在仓库内的工作方式团队共同维护CLAUDE.mdClaude Code给 Claude Code 的项目上下文使用 Claude Code 的开发者.cursorrulesCursor给 Cursor 的特定规则使用 Cursor 的开发者2. 从“读文件”到“守合同”指令文件正在变成工程基础设施2.1 AGENTS.md 解决的是“代理上下文”问题AI 编程代理和普通脚本最大的区别在于它每次运行都可能面对一个全新的上下文窗口。它没有团队记忆也不会主动去看你的 Wiki 和架构文档。如果没有一个稳定、可见、可版本管理的入口代理对仓库的理解就只能靠随机探索和模型先验结果自然不稳定。AGENTS.md 就是那个入口。它把“项目怎么构建、代码怎么组织、什么不能碰”提炼成代理进入仓库后第一件应该读取的文件。这样无论你用的是哪个模型、哪个工具只要它认这份文件它的初始行为就会收敛到一个相对可控的范围。这个思路和给新员工做入职手册是一样的。一个没有 onboarding 文档的团队新人上手全凭打听有了一份规范文档新人至少不会在第一天就踩进最明显的坑。AGENTS.md 就是把这样的手册从“给人看”扩展到“给代理看”。2.2 兼容性不是功能清单而是生态位问题讨论 AGENTS.md 兼容性时很多人的第一个疑问是不就是读一个 Markdown 文件吗有什么难的难点不在解析文件而在“优先级”和“执行承诺”。一个工具可以在启动时读取 AGENTS.md但如果用户在对话里说了一句话把 AGENTS.md 里的规则覆盖了这个工具到底是遵守规则还是遵守对话指令这是一个产品决策不是技术难点。更现实的问题是如果工具只把自己私有格式的指令文件当作“一等公民”而对社区通用的 AGENTS.md 只是“顺带支持”那么在一个多工具协作的团队里AGENTS.md 很容易成为那个被遗忘的文件。一旦出现分歧代理的行为就不守恒了。所以在基础设施