AGENTS.md：一个文件让Cursor、Claude Code、Codex共用规则

开发者在同一个仓库里同时使用 Cursor、Claude Code 和 Codex 已经越来越常见。分工也大致清晰：Cursor 负责编辑器内的读写，Claude Code 处理终端里的多文件操作，Codex 跑后台任务，顺便充当第二审查人。

问题出在规则上。三个工具各自读取不同的指令文件，三套规则很容易漂移，最终导致智能体之间互相"打架"。

三个工具，三套规则

每个 AI 编程工具都有自己的配置文件约定。Cursor 有自己的 rules 文件夹，Claude Code 读取 claude.md，Codex 读取 agents.md。

单独使用时都没问题。但当三个工具同时在一个仓库里工作时，三份规则文件会逐渐分叉——你在 Cursor 的规则里加了一条代码规范，忘了同步到 claude.md，Codex 又完全看不到。结果是同一个仓库里，三个智能体遵循着三套不同的行为准则。

这种碎片化带来的不是小麻烦。当智能体对代码风格、目录结构或操作边界的理解不一致时，它们给出的建议和修改会互相矛盾，开发者反而要花更多精力去协调工具之间的冲突。

AGENTS.md 已经是事实标准

这个问题的解决方案其实已经存在。据 OpenAI 在 2025 年 12 月将 agents.md 捐赠给 Linux 基金会时披露，目前已有超过 60,000 个项目在使用这一格式。它与 Anthropic 的 MCP 一起，成为 Linux 基金会下的开放标准项目。

Codex 原生支持 agents.md。它的读取逻辑是从仓库根目录开始，逐层向下查找，离当前文件夹最近的那份文件优先级最高。这种层级化的查找方式意味着你可以在根目录放一份通用规则，在特定子目录里放更具体的覆盖规则。

Cursor 也支持读取 agents.md，将其作为 rules 文件夹的纯 Markdown 替代方案。

三套规则文件收敛成一份，智能体之间的行为差异自然就减少了。

Linux 基金会与开放标准治理

Linux 基金会是全球最大的开源非营利组织，托管着 Linux 内核、Kubernetes、Node.js 等大量关键基础设施项目。它常被用作中立托管方，当一个技术格式被多家竞争公司共同采用时，将其捐赠给基金会可以避免单一厂商控制标准走向。OpenAI 将 agents.md 捐赠给基金会，意味着这一格式不再属于任何一家 AI 厂商，而是由社区共同维护，其他工具（包括 Anthropic、Google 等竞品）都可以放心采用而不必担心被卡脖子。Anthropic 的 MCP（Model Context Protocol）同样走的是这条路径——先由一家公司提出，再通过基金会中立化，从而成为跨厂商的通用接口。理解这一点，就能明白为什么 agents.md 有可能真正成为长期稳定的事实标准，而不只是某家公司的私有约定。

层级化配置查找

层级化查找是一种常见的配置解析模式：程序从当前工作目录开始，逐级向上（或从根目录逐级向下）搜索配置文件，越靠近当前上下文的文件优先级越高。Git 的 .gitignore、ESLint 的 .eslintrc、npm 的 .npmrc 都采用类似机制。对智能体而言，这种设计允许你在仓库根目录写一份宽泛的通用规则，再在 backend/ 或 frontend/ 等子目录里写更细的覆盖规则，从而让不同模块遵循各自的规范，而不必把所有规则堆在一个巨大的文件里。这也是 agents.md 能够同时适配大型多包仓库和轻量单目录项目的原因。

Claude Code 的一个坑

Claude Code 对 agents.md 的支持有一个需要特别注意的地方。

如果仓库里没有 claude.md，Claude Code 会读取 agents.md。但如果两个文件同时存在，它只会读取 claude.md，完全忽略 agents.md。

这意味着从其他工具迁移过来的开发者，如果仓库里还留着旧的 claude.md，就会遇到规则不生效的问题。修复方法只需要一行：在 claude.md 里写入对 agents.md 的引用（比如 @agents.md），Claude Code 就会同时加载两份文件。

文件引用语法 @agents.md

Claude Code 支持在 claude.md 中用 @路径 的形式引用其他文件，被引用的内容会在加载时被内联展开，效果等同于把那份文件的内容直接写进 claude.md。这一语法不仅适用于 agents.md，也可以用来拆分大型指令文件——例如把 claude.md 拆成 @rules/style.md、@rules/testing.md 等多个片段，便于团队分工维护和版本审查。使用引用而非复制粘贴的好处在于：agents.md 仍然是唯一事实来源，Cursor、Codex 读到的和 Claude Code 读到的内容永远一致，不会因为手动同步而再次产生漂移。需要注意的是，引用路径通常是相对于 claude.md 所在位置解析的，跨目录引用时应写清相对路径。

怎么写出有效的 AGENTS.md

文件内容要短、要实用。开发者社区总结出的有效内容包括：

• 构建和测试命令：让智能体知道如何编译、运行和验证代码
• 代码约定：命名规范、格式化偏好、导入顺序等
• 禁止触碰的目录：明确哪些文件夹智能体不应该修改

有一个技术限制需要留意：Codex 默认读取 agents.md 的上限是 32KB。超过这个大小的内容会被截断。

更重要的是理解 agents.md 的定位——它是指导性的，不是强制性的。智能体可能遵循，也可能不遵循。对于必须严格执行的规则，应该用硬编码或 hooks 来实现。

Hooks 与硬性约束

Hooks 是指在智能体工作流的关键节点（如提交前、文件保存后、工具调用前后）自动触发的脚本。它与 agents.md 这类提示性指令的本质区别在于执行层：提示是给模型的自然语言建议，模型可能因为上下文长度、理解偏差或优先级冲突而忽略；而 hooks 是确定性的程序逻辑，一旦触发就必然执行，不符合规则的操作会直接被拒绝或回滚。因此，凡是不能妥协的约束——比如禁止提交密钥、禁止改动 migrations/ 目录、提交前必须通过 lint——都应当用 hooks、pre-commit 钩子或 CI 检查来兜底，而把风格偏好、命名习惯这类软性建议交给 agents.md。理解"提示 vs 强制"这条分界线，是设计可靠智能体协作流程的关键。

32KB 上限的含义

32KB 大致相当于 8,000 到 10,000 个英文单词，或约 1.5 万到 2 万个汉字。对于一份指令文件来说这个容量其实相当充裕，但大型单体仓库若试图把全部模块的规则塞进一个文件，很容易触顶。超过上限的部分会被静默截断——也就是文件末尾的规则会悄无声息地失效，不会报错，这比直接失败更危险。规避方式正是前文提到的层级化查找：把通用规则放根目录，把模块专属规则下沉到各子目录，既控制单文件体积，又保证就近生效。

让第二个智能体做审查

一个值得尝试的实践是让第二个智能体审查第一个智能体的工作。开发者的反馈是，这种方式能捕捉到第一个智能体遗漏的问题。

比如让 Codex 在后台跑完任务后，由 Claude Code 或 Cursor 检查修改结果。不同工具的模型和上下文窗口不同，审查视角也会有差异，这种多样性本身就是一种质量保障。

一个文件，三个工具，一套规则。在多智能体协作成为日常的今天，用 agents.md 统一规则入口，是降低协调成本最直接的做法。

异构模型审查为何更有效

不同厂商的模型在训练数据、对齐策略和解码方式上各不相同，这导致它们对同一段代码的"注意力"分布存在差异：一个模型可能对安全边界格外敏感，另一个可能更擅长发现类型或并发问题。当审查者和被审查者使用相同模型、相同上下文时，它们往往共享同一套盲点，错误容易被"一致性"掩盖。换用另一个厂商的模型作为第二审查人，相当于引入独立视角，能显著提高缺陷发现率。这与传统代码评审中"换一双眼睛"的原则一致，也与软件工程里用多种静态分析工具交叉扫描的思路相通。上下文窗口的差异同样重要：窗口更大的模型能一次性看到更多相关文件，从而发现跨文件的依赖问题。