让三种编程Agent共用一套项目规则

同一套仓库规范，分别放进 AGENTS.md、CLAUDE.md 和 .cursor/rules，最容易出的问题是改完一份，另外两份忘了同步。作者给出的方案是：把共享规则集中到 AGENTS.md，再用各工具的专属机制补充差异。

但「三个工具都能读」不等于「任何配置下都会读」。这篇真正有用的部分，是文件优先级、加载条件，以及怎样确认规则确实进入了上下文。

AGENTS.md 能共用，为什么还会失效

按原文引用的文档，三个工具的读取方式有明显差别。

Codex 读取 AGENTS.md，先检查 ~/.codex 中的全局文件，再从仓库根目录走到当前工作目录。每层最多取一个文件，AGENTS.override.md 优先于 AGENTS.md；越靠近当前目录，规则越晚出现，可以覆盖前面的规则。合并大小受 project_doc_max_bytes 限制，默认是 32 KiB。

Cursor 支持 .cursor/rules/ 中的 .mdc 文件，通过 description、globs、alwaysApply frontmatter 描述和控制规则。放在该目录里的普通 .md 文件会被忽略。它也支持根目录和子目录中的 AGENTS.md，作为更简单的规则入口。

Claude Code 读取 CLAUDE.md 或 .claude/CLAUDE.md，也支持 .claude/rules/*.md，后者可以用 paths: frontmatter 限定路径。原文称，v2.1.277+ 可以直接读取 AGENTS.md，但前提是当前目录及其上级没有 CLAUDE.md 或 CLAUDE.local.md。除非调整 Project instructions 设置，否则新增 CLAUDE.md 会悄悄停止直接加载 AGENTS.md。

统一文件名只是第一步，真正要统一的是规则的加载结果。

共享规则放一份，工具差异怎么补

作者建议，把通用约定放进 AGENTS.md。Claude Code 有专属要求时，用导入补充，避免复制整份规则：

   @AGENTS.md

   ## Claude Code
   Use plan mode for changes under `src/billing/`.

要看的是第一行 @AGENTS.md：它负责加载共享规则，后面的内容才是 Claude Code 专属要求。原文称，共享文件会加载一次。

也可以执行 ln -s AGENTS.md CLAUDE.md 建立符号链接，但原文转述 Claude 文档的提醒：这种方式在 Windows 上处理起来比较麻烦。

Cursor 的专属文件则留给路径规则。例如，在 .cursor/rules/*.mdc 中设置 globs: src/components/**/*.tsx，让组件目录使用额外约定，不再复制通用规范。

monorepo 可以继续按目录拆分。原文明确举出的例子是 services/payments/AGENTS.md，Codex 和 Cursor 会为对应目录读取它。这里没有同样明确说明 Claude Code 的嵌套行为，不能直接把前两者的结论套过去。

规则应该写什么，怎样确认它生效

作者强调的是「短而具体」。原文引用的建议上限是：每份 CLAUDE.md 少于 200 行，Cursor 每条规则少于 500 行。这些是编写建议，不是效果保证。

优先写准确命令、偏离默认习惯的约定、代码位置，以及 Agent 已经重复犯过的错误。下面这份示例把这些要求落到了可执行动作上：

## AGENTS.md

## Commands
- Install: `pnpm install`
- Test: `pnpm test` (run before every commit)
- Lint: `pnpm lint`

## Conventions
- TypeScript strict. Named exports only.
- Never edit files in `dist/` or `generated/`.

## When unsure
- Read the nearest existing example before writing new code.
- Ask before adding a production dependency.

注意 pnpm test 后面的执行时机，以及新增生产依赖前先询问的要求：这些会影响 Agent 如何行动，比一句「保持代码质量」明确得多。构建命令也应按实际输入方式写全；已经由 linter 强制执行的风格，不必再铺成长篇说明。

写完还要检查加载状态。原文给出的入口是：

• Codex：运行 codex --ask-for-approval never "Summarize the current instructions."。
• Claude Code：通过 /context 或 /memory 查找对应文件。
• Cursor：打开 Customize → Rules，查看当前启用的规则。

这些检查能帮助发现漏加载，但规则出现在上下文里，也不代表后续每一步都会严格执行。

我的判断

我赞同把共享规范集中维护。它直接减少重复修改，也方便代码审查时判断：这次改动影响所有 Agent，还是只影响某个工具。

但这篇给出的是文档行为整理和配置建议，没有团队对照实验，也没有任务成功率数据。因此，「短规则更好」可以当作维护原则，不能包装成已经验证的效率提升。

相较于分别维护三份文件，AGENTS.md 更适合多个 Agent 共用同一套仓库规范的团队。若项目只有一个工具、已有稳定配置，迁移收益就未必明显。尤其是 Claude Code 的版本和入口文件条件，需要先核对。

规则文件说明仓库怎么工作；具体要完成什么，仍由任务提示决定。

能拿来做什么

• 在前端仓库先集中记录包管理器、测试和 lint 命令、导出约定及禁止修改的生成目录，删除重复维护的通用规则。
• 在 monorepo 中，把支付服务等局部约定放到对应目录；按实际使用的 Agent 检查是否加载，避免默认所有工具行为一致。
• 给现有 Claude Code 项目增加共享规则时，先检查已有 CLAUDE.md，采用 @AGENTS.md 导入，防止新增文件后丢失共享指令。
• 每次调整规则后，检查加载状态，再观察真实任务中的行为；把反复出现的错误补成具体约束，不断堆积的空泛要求则及时删掉。