AGENTS.md 兼容性隐患：如何让 Claude Code 稳定遵循项目规则

最近技术社区讨论度最高的话题之一是 Shopify CEO 在内部推动评估禁用 Claude Code理由是它对 AGENTS.md 的执行不够可靠。这则消息很快引发了连锁讨论因为很多团队正好卡在同一个问题上AI 编码工具越来越强但项目里的规则文件到底应该怎么写才能让不同工具都稳定遵守这篇文章不打算只做新闻解读而是想借这个事件把 AGENTS.md 的核心概念、标准写法、跨工具兼容方案和常见坑位梳理成一套可落地的工程笔记。读完你会知道 AGENTS.md 在 Claude Code 这类 AI 编程工具中是什么角色、为什么会出现不兼容、以及如何在团队中设计一份真正能被稳定执行的规则文件。1. 从 Shopify CEO 的反对说起事件到底在讨论什么1.1 事件背景与争议焦点根据公开报道Shopify CEO 对 Claude Code 的态度比较谨慎甚至考虑在团队内禁用。表面看这是一次工具选型争议但背后的核心矛盾是Claude Code 作为一款终端 AI 编程代理并不能完全按照 AGENTS.md 中的项目约定来执行代码修改。这触及了一个很多开发者正在经历的痛点。过去我们写代码规范是给人看的靠 Code Review 制度来约束现在 AI 编码工具可以直接改代码、执行命令、提交代码那么这些工具是否遵守项目规范就变成了质量和安全的新边界。如果 AI 工具把项目的 AGENTS.md 当成了参考文档而不是强制约束它可能就会绕过你精心设计的架构边界、调用约定和测试流程。对于大型团队来说这不是小问题。Shopify 这样的公司代码库庞大、服务众多、规范复杂AGENTS.md 往往是团队多年沉淀下来的工程经验的结晶。如果 AI 工具无法稳定遵循那它带来的增量产出可能还覆盖不了引入的混乱成本。1.2 为什么 AGENTS.md 会成为导火索AGENTS.md 并不是一个新概念但随着 Claude Code、Codex、Cursor 这类 Agentic Coding 工具在 2025 年集中爆发它很快成了社区约定俗成的项目规则文件。简单说AGENTS.md 是一个放在仓库里的 Markdown 文件用来告诉 AI 编程代理这个项目是干什么的技术栈和框架是什么怎么构建、测试、运行代码风格和架构约束是什么哪些操作是禁止的哪些文件是关键路径改之前要先确认。Claude Code 在实际使用中原生更偏爱的指令文件是 CLAUDE.md它对 AGENTS.md 的支持有一个演进过程。如果某位开发者或团队只维护了 AGENTS.md而 Claude Code 没有把它当作最高优先级指令来处理就会出现规则被忽略的现象。这种偏差在单个文件的小项目中不明显但在 Shopify 这种复杂仓库中会被迅速放大。这里要说明的是本文讨论的不兼容不是指 Claude Code 无法读取 Markdown而是指它对 AGENTS.md 的理解深度、优先级次序和执行稳定性与团队预期不一致。这个问题本质上是工程层面的指令对齐问题而不是简单的函数报错。2. Claude Code 与 AGENTS.md先把两个概念讲清楚2.1 Claude Code 是什么Claude Code 是 Anthropic 推出的 AI 编程代理工具最初以命令行工具形态发布后面逐步扩展了桌面端、VS Code 插件等入口。它的工作方式和传统 Copilot 式补全不同。你可以在终端里用自然语言描述一个任务例如检查一下订单服务的超时逻辑并补充单元测试Claude Code 会自己读取项目代码、分析结构、修改文件、执行测试命令然后给出改动说明。这种代理式工作流对项目上下文的理解要求很高。AI 工具需要知道代码放在哪个目录用什么命令构建测试怎么写项目的架构约束是什么。如果这些信息只靠 AI 临时从代码里推断不仅慢而且容易出错。AGENTS.md 就是用来把这些信息显式提供给 AI 的。2.2 AGENTS.md 是什么AGENTS.md 是一个采用 Markdown 格式的纯文本指令文件通常放在仓库根目录也可以放在特定子目录中用来约束 AI 编程代理在该目录下的行为。从社区实践看它有以下特点它是给 AI 看的项目说明书类似一个给新人的入职手册但不是给人写的而是给 AI 代理看的。它比代码注释更系统能覆盖构建命令、架构约束、禁区等多个维度。它容易被工程化维护因为就是普通 Markdown可以进 Git可以 Code Review可以版本化。和 AGENTS.md 类似的还有 CLAUDE.md、.cursor/rules、copilot-instructions.md、AI.md 等。这些文件本质上是同一类产物只是不同工具对它们的识别优先级不同。2.3 两者的关系指令源与执行者Claude Code 是执行者AGENTS.md 是指令源之一。理想情况下Claude Code 在任务开始时会读取仓库里的 AGENTS.md并将其中的约束作为本次会话的长期上下文持续影响后续的每一步修改。但在实际运行中两者之间还存在很多变量Claude Code 是否默认读取 AGENTS.md取决于版本和对该文件的支持情况如果存在 CLAUDE.mdClaude Code 会优先处理哪个文件指令内容过长的是否会被截断项目里嵌入了多个层级的 AGENTS.md优先级怎么算。这些变量就是兼容性问题背后的真相。理解这一点比单纯吐槽某个工具更有利于解决问题。3. 不兼容的深层原因从工程视角看问题3.1 优先级规则不统一不同 AI 编码工具对规则文件的优先级定义并不相同。Claude Code 最早期的设计里CLAUDE.md 是专属指令文件而 AGENTS.md 是在行业标准化推动下逐步支持的。这就导致一个问题团队如果同时维护 AGENTS.md 和 CLAUDE.md它们之间的优先级可能会随着工具版本更新而变化。比如早期版本可能只看 CLAUDE.md某个版本开始同时读取 AGENTS.md再后来可能是两者合并但以某个文件为主。这种不透明性很容易让团队产生我明明写了规则但它没遵守的感觉。社区里常见的妥协方案是把通用规则放在 AGENTS.md把 Claude Code 专属规则放在 CLAUDE.md并让 CLAUDE.md 明确写一句必须同时遵循 AGENTS.md。但这也只能缓解不能根除。3.2 语义理解与格式解析差异AGENTS.md 本质上是自然语言文本AI 工具的解析效果取决于模型对 Markdown 结构和语义的理解能力。例如你在 AGENTS.md 里写了- 禁止使用 System.out.println 打印日志这句话人类看得很清楚但 AI 代理在修改代码时可能会因为上下文过长而忘记这条约束或者在新建调试代码时认为临时调试不算正式日志。这就是语义约束和实际操作之间的偏差。再看一个更细微的场景表格、列表、代码块混合使用时不同工具的解析策略也不同。有的工具会把表格里的每行当作独立约束有的则只提取关键列。这些差异都会导致同样一份 AGENTS.md在不同工具里表现不同。3.3 上下文窗口与指令截断这是最容易被忽略的工程问题。AGENTS.md 如果写得过长AI 工具在加载项目上下文时会消耗大量上下文窗口空间。当代码内容本身已经很长时AGENTS.md 的后半部分很可能被截断或降权处理。我在实际项目里见过这样的 AGENTS.md洋洋洒洒写了上千行包含各种历史决策记录、技术选型背景、甚至面试题式的自我提问。这种文件对人类读者来说很友好但对 AI 代理来说反而是一种灾难因为关键约束被淹没在大量无关信息里。所以AGENTS.md 的信息密度和结构清晰度会直接影响兼容性和执行效果。这不是工具单方面的问题文件本身的组织方式占很大比重。3.4 多层级文件与作用域冲突在大仓库中AGENTS.md 可以放在根目录也可以放在各子项目中。理论上子目录的 AGENTS.md 应该只对该目录生效根目录的 AGENTS.md 对整个仓库生效。但实际执行时AI 工具对作用域的合并策略并不总是一致。典型冲突是根目录的 AGENTS.md 说所有代码必须通过 Maven 构建但某个子模块是独立的前端工程它自己的 AGENTS.md 说的是使用 pnpm 构建。如果工具按照错误的优先级合并了规则AI 就会用 Maven 去构建前端项目产生荒谬的结果。这也是很多团队抱怨AGENTS.md 导致 AI 越改越乱的根本原因之一不是文件写错了而是文件之间的层级关系没有被工具正确理解。4. 手写一份规范的 AGENTS.md完整示例与字段说明4.1 AGENTS.md 应该包含哪些内容根据社区实践一份高质量的 AGENTS.md 通常分为以下几块项目简介让 AI 快速理解项目性质避免离谱操作。技术栈与环境说明语言、框架、构建工具、数据库等。常用命令启动、测试、打包、静态检查等命令必须是可直接复制的。代码规范命名、分层、异常处理、日志等约束尽量具体。目录结构说明各目录的作用和边界防止 AI 把业务代码写进基础设施目录。高风险禁区哪些文件不能动、哪些操作需要先确认、哪些数据不能改。常见注意事项历史踩坑总结告诉 AI 哪些做法有隐患。这里要特别注意命令和规范必须具体避免请遵守良好的代码风格这类空话。AI 对空泛描述的理解非常不稳定但对具体命令和正反示例的执行要可靠得多。4.2 完整示例一个订单服务项目的 AGENTS.md下面我以一个典型的 Spring Boot 订单服务为例写一份可以直接参考的 AGENTS.md# AGENTS.md ## 项目简介 这是一个订单中台服务负责订单创建、支付回调、超时关闭、售后单生成等核心流程。 服务对数据一致性要求极高任何改动必须保证事务边界完整。 ## 技术栈 - 语言Java 17 - 框架Spring Boot 3.2 - ORMMyBatis-Plus 3.5 - 数据库MySQL 8.0 - 缓存Redis 7 - 构建工具Maven 3.9 ## 常用命令 - 启动本地服务mvn spring-boot:run - 执行全部测试mvn test - 执行单个测试类mvn test -DtestOrderServiceTest - 打包跳过测试mvn clean package -DskipTests - 代码格式化检查mvn spotless:check ## 目录结构 src/main/java/com/example/order/ ├── controller/ # HTTP 入口只做参数接收和结果返回 ├── service/ # 业务逻辑层禁止直接编写 SQL ├── service/impl/ # Service 接口实现 ├── mapper/ # MyBatis-Plus Mapper 接口 ├── entity/ # 数据库实体字段与表结构一一对应 ├── dto/ # 请求和响应对象 ├── enums/ # 枚举定义 ├── common/ # 通用返回结果、异常、常量、工具类 └── config/ # Spring 配置类 ## 代码规范 1. Service 层必须面向接口编程Controller 禁止直接注入 Mapper。 2. 所有对外接口统一返回 ResultT禁止直接返回实体对象。 3. 金额计算必须使用 BigDecimal禁止使用 double 或 float。 4. 日志使用 SLF4J禁止使用 System.out.println。 5. 新增枚举必须继承 IEnum 并提供 value 字段。 6. 涉及订单状态变更时必须使用乐观锁 Version禁止直接 update。 ## 高风险操作 - 禁止修改订单金额相关字段除非有明确审批说明。 - 禁止删除数据库表或清空表数据。 - 禁止将第三方 API 的调用放在事务内。 - 修改 order_status 状态机时必须先更新状态机文档。 ## 常见注意事项 - 数据库表结构变更前先创建 db/migration 目录下的 SQL 脚本。 - Redis Key 必须引用 RedisKeyConstants 常量类禁止硬编码。 - 支付回调接口必须做幂等处理以 order_no event_type 为幂等键。 - 查询列表禁止使用 select *必须明确查询字段。这份文件的好处是每一类信息都有明确的区块AI 可以快速检索。其中高风险操作和常见注意事项是执行稳定性最强的部分因为它们包含了明确的动作和禁止对象。4.3 每个字段为什么这么写项目简介部分AI 通过第一段就能建立对项目的整体认知。对订单服务这类对一致性要求高的项目特别强调事务边界非常关键否则 AI 很容易在拆分方法时把事务注解挪到错误的位置。技术栈部分是命令和代码风格的底层依据。AI 在生成代码前会先判断项目用的什么框架如果你不给它这些信息它可能会按默认习惯生成 Spring Boot 2.x 或 JPA 风格的代码导致与项目现有代码不一致。常用命令直接决定了 AI 在验证改动时的行为。一个常见的坑是AI 修改完代码后可能选择不执行测试因为不知道该用什么命令。如果项目里写明了mvn testAI 的验证意愿会明显提升。高风险操作是必须写的。这个区块用于将人为约束转换成 AI 可理解的边界。订单金额、数据库删除、状态机变更都是典型的高风险场景如果 AI 代理误操作后果可能非常严重。5. 跨工具兼容一份 AGENTS.md 同时服务多款 AI 编码工具5.1 通用优先策略在团队中往往不是只有 Claude Code 一个 AI 工具。有人用 Cursor有人用 GitHub Copilot还有人用 Codex。如果每个工具都有一套独立的规则文件维护成本会爆炸。推荐的策略是单一事实来源把跨工具的通用规则放在 AGENTS.md把工具专属配置放在各自工具的文件中工具专属文件只是补充不重复 AGENTS.md 已有的通用规则。这样做的好处是当项目规范变化时只需要更新 AGENTS.md所有工具通过各自的桥接文件都能间接感知。否则同样的规则要在 CLAUDE.md、.cursor/rules、copilot-instructions.md 中各写一份很快就会因为遗忘而产生冲突。5.2 为 Claude Code 补充桥接文件Claude Code 除了支持 AGENTS.md也支持 CLAUDE.md。为了确保兼容性和稳定性可以在仓库根目录维护一个精简的 CLAUDE.md内容尽量短只做桥接# CLAUDE.md 本文件是 Claude Code 的项目指令入口。 - 开始任务前必须阅读根目录的 AGENTS.md。 - AGENTS.md 中的规范优先级高于本文件。 - 当 AGENTS.md 与本文件冲突时以 AGENTS.md 为准。 - 如果任务涉及代码修改修改后必须运行对应的测试命令。 ## 专属补充 - 重命名方法或类时同步搜索并更新所有调用方。 - 涉及第三方 API 联调时先查看 docs/api-guide.md。这个文件的优势是足够短不会大量占用上下文窗口。它的核心作用是把规则指向 AGENTS.md而不是替代 AGENTS.md。5.3 目录级 AGENTS.md 的作用域管理大仓库建议采用根目录总纲 子目录专项的层级结构repo-root/ ├── AGENTS.md # 全仓库通用规则 ├── services/ │ ├── order-service/ │ │ └── AGENTS.md # 订单服务专项规则 │ └── user-service/ │ └── AGENTS.md # 用户服务专项规则 └── frontend/ └── admin-web/ └── AGENTS.md # 前端专项规则根目录的 AGENTS.md 只写所有模块共同遵守的约定例如 Git 提交规范、统一接口返回格式、禁止提交敏感信息等。各子目录的文件则聚焦该模块特有内容。在实际使用中AI 工具会优先读取它当前所在目录及其父级目录的 AGENTS.md。因此在 Claude Code 中进入services/order-service目录再开始任务能有效减少根目录无关规则对子任务的影响。5.4 避免在 AGENTS.md 中写工具相关指令一个很容易犯的错误是在 AGENTS.md 里写当你使用 Claude Code 时请执行 A当你使用 Cursor 时请执行 B。这种写法会严重降低文件的通用性因为 AI 工具在处理指令时并不总是能准确判断自己是谁。正确的做法是AGENTS.md 只描述项目应该是什么样不描述某个工具应该怎么做。比如写代码必须通过mvn spotless:check检查不要写如果你在用 Claude Code请运行mvn spotless:check。工具适配层的职责应该交给各工具的专属文件。如果某类操作只有 Claude Code 能完成就放在 CLAUDE.md 里如果只有 Cursor 能完成就放在 .cursor/rules 里。6. 常见问题与排查思路6.1 高频问题清单问题现象可能原因解决思路Claude Code 完全不读 AGENTS.md版本过旧或文件名大小写不一致升级 Claude Code 版本确认文件名为 AGENTS.md规则有时生效、有时不生效AGENTS.md 内容过长上下文被截断精简文件把通用规则放在前 50 行和 CLAUDE.md 冲突时行为异常两个文件的优先级定义不明确在 CLAUDE.md 中显式声明 AGENTS.md 优先子目录规则被忽略AI 工具从根目录启动未进入子目录进入目标子目录后再启动 Claude Code表格类约束执行不稳定模型的表格语义解析弱于列表关键约束请用有序列表不要只放表格修改代码后不执行测试AGENTS.md 中命令不完整或不够醒目把测试命令放在常用命令区块最前面中文指令理解偏差语义表达模糊缺少正反示例为关键约束补充错误示例和正确示例6.2 排查顺序建议如果遇到 AGENTS.md 不生效建议按以下顺序排查第一步确认文件名。必须是AGENTS.md注意大小写。某些工具对大小写敏感agents.md和AGENTS.md可能被视为不同文件。第二步确认文件位置。根目录的 AGENTS.md 是否被另一个更高优先级的规则覆盖。例如如果项目里有.cursor/rules且 Cursor 明确优先使用该目录那么 AGENTS.md 在 Cursor 中就会被降权。第三步检查内容长度。打开 AGENTS.md看看你关心的关键约束是不是被埋在了一大段文字后面。如果是把关键约束提到文件头部。第四步验证上下文。在 Claude Code 中直接问你知道本项目的代码规范有哪些让它复述一遍 AGENTS.md 的内容。如果它回答不全说明规则没有被完整加载。第五步观察拆分场景。有些规则在任务开始时被加载但在多轮对话后可能被遗忘。如果发现问题集中在长任务的后半段可以主动让 Claude Code 中途重新读取 AGENTS.md。6.3 验证规则的可靠方法不要只看 AI 口头确认,要让它用行动证明。一个可行的验证方法是故意在任务描述中加入一个违反项目规则的请求观察它是否会拒绝。例如项目规范明确禁止 System.out.println 输出日志你可以让 Claude Code给某个类临时添加 System.out.println 调试输出看它是否遵守约束。如果它直接照做说明规则没有被正确加载或理解如果它拒绝并提醒你项目规范说明规则生效了。这种对抗性验证在团队落地 AGENTS.md 时非常有用可以快速评估一份规则文件的实际约束力。7. 最佳实践与团队落地建议7.1 让 AGENTS.md 短而准根据实际项目经验AGENTS.md 的最佳长度通常在 100 到 300 行之间。过短信息不足过长关键规则会被截断或降权。写作时遵循越靠前越重要的原则。把最高优先级的约束放在文件开头 30 行内例如高风险操作、命令入口、核心架构边界。历史背景、技术选型原因、团队决策记录等内容可以放到独立的 docs 目录中不要塞进 AGENTS.md。7.2 用正反示例代替抽象描述AI 对禁止 xxx的理解通常不如错误示例 vs 正确示例来得直接。比如## 错误示例 java // 错误直接在 Controller 里写业务逻辑 GetMapping(/order) public Order getOrder(String orderNo) { // 这里查了数据库做了状态判断还改了缓存 return orderMapper.selectByOrderNo(orderNo); }正确示例// 正确Controller 只做参数接收和结果返回 GetMapping(/order) public ResultOrderVO getOrder(String orderNo) { return orderService.getOrderDetail(orderNo); }这种双示例写法能显著降低 AI 的误解概率。尤其是在代码风格和分层约束上正反示例几乎是最有效的表达方式。 ### 7.3 把 AGENTS.md 纳入 Code Review 流程 AGENTS.md 会影响 AI 的行为边界因此它的变更也不能随意进行。建议将 AGENTS.md 的修改纳入常规的 Pull Request 评审流程并明确变更记录 - 谁加的、为什么加 - 会不会影响现有 AI 工具的规则解析 - 和已有的规则是否冲突 - 是否需要同步更新 CLAUDE.md 等桥接文件。 如果团队已经用了规范检查工具也可以考虑对 AGENTS.md 做简单的格式校验比如检查是否存在空链接、无效代码块、歧义表述等。 ### 7.4 生产环境中必须设置安全边界 AGENTS.md 只是指令文件它不能替代真正的权限控制和审批机制。对于高风险操作必须在工具层面做限制 - 数据库变更、生产环境操作必须走人工审批流程 - AI 代理不要配置生产环境的数据库连接凭据 - 涉及大量文件删除或全局替换的操作建议先在分支上验证 - Claude Code 等工具在团队内统一使用托管配置避免每个开发者自行修改规则后造成行为漂移。 这些内容虽然是规则之外的规则但它们是 AGENTS.md 能稳定落地的保障。没有权限边界的约束再完美的指令文件也可能被绕过。 ### 7.5 定期评审 AGENTS.md 的有效性 AGENTS.md 不是写一次就结束的静态文件。项目架构在变、依赖在升级、AI 工具对规则的理解能力也在提升。建议每季度做一次评审 - 把实际跑过的 AI 任务和 AGENTS.md 的预期行为做对比 - 找出哪些规则执行得好、哪些规则经常被忽略 - 删除已经过时的命令和规范 - 根据新踩的坑补充新的正反示例。 这种评审机制能让 AGENTS.md 成为团队的活文档而不是一个被人遗忘的仓库化石。 ## 8. 总结 回到 Shopify CEO 考虑禁用 Claude Code 的新闻站在工程角度看真正值得关注的不是某个具体工具的是否可用而是团队是否建立了清晰的 AI 指令治理体系。 AGENTS.md 作为项目级指令文件它的价值在于把团队多年的工程经验显式地传递给 AI 代理。但写了文件和规则被执行之间还存在版本兼容、优先级定义、内容组织、作用域管理、安全边界等大量工作。Claude Code 对 AGENTS.md 的支持确实在持续演进但团队不能把所有责任都丢给工具文件本身的写法和配套机制同样关键。 对于正在准备引入 AI 编码工具的团队我的建议很简单先从小项目开始建一份精简的 AGENTS.md用对抗性验证确认规则真的生效然后逐步扩展到复杂仓库。不要等到 AI 改了核心代码才发现规则形同虚设。 如果你也在团队里维护 AGENTS.md或者在使用 Claude Code 时踩过类似规则不生效的坑欢迎在评论区聊聊你的处理方案。