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.md，Claude 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 - ORM：MyBatis-Plus 3.5 - 数据库：MySQL 8.0 - 缓存：Redis 7 - 构建工具：Maven 3.9+ ## 常用命令 - 启动本地服务：`mvn spring-boot:run` - 执行全部测试：`mvn test` - 执行单个测试类：`mvn test -Dtest=OrderServiceTest` - 打包（跳过测试）：`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. 所有对外接口统一返回 `Result<T>`，禁止直接返回实体对象。 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 test，AI 的验证意愿会明显提升。

高风险操作是必须写的。这个区块用于将人为约束转换成 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 高频问题清单

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 Result<OrderVO> 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 时踩过类似"规则不生效"的坑，欢迎在评论区聊聊你的处理方案。