AGENTS.md 与跨工具互操作
系列入口：如何使用 Agent。相关：规则/记忆文件分层、MCP 协议。
一、为什么会出现 AGENTS.md
团队里往往同时存在多种 AI 工具，各自只认自己的规则文件。同样一条「如何构建、如何测试、哪些目录不能动」的项目知识，被迫在多个文件里重复维护，很快就不同步：改了构建命令，却只更新了其中一处，另一个工具仍按旧说明行事，错误由此产生。
AGENTS.md 是一份放在项目里、面向 AI Agent 的开放约定，目标是成为跨工具可读的项目说明。 它的价值不在于发明新能力，而在于提供一个「写一次、处处可读」的公共位置，让无论哪个工具进入这个仓库，都能先读到同一份稳定的项目事实。它解决的是重复与漂移问题。
二、它和私有规则文件怎么并存
AGENTS.md 不是要消灭各工具的私有规则，而是分层。可以这样理解两者分工：
- AGENTS.md（公共层）：与具体工具无关、对任何 Agent 都成立的项目事实——构建与测试命令、目录结构、编码规范、需要避开的区域。追求跨工具一致。
- 工具私有文件（专属层）：只有某个工具才有的机制——特定的斜杠命令、专属 Hook、模型或工具开关。放该工具独有的配置。
一个实用原则：凡是「换了工具依然成立」的内容，放 AGENTS.md；凡是「离开这个工具就无意义」的内容，放私有文件。 私有文件可以引用或补充 AGENTS.md，而不是重复抄写公共事实，这样从根上避免两处漂移。
三、该写什么：稳定、可执行的项目事实
AGENTS.md 的内容应当是 Agent 在这个仓库里正确行事所必需、且相对稳定的信息。典型包括：
- 项目概览：这是什么、技术栈、整体架构一句话。
- 常用命令：如何安装、构建、测试、lint、运行——要准确，最好能直接复制执行。
- 目录约定：各目录职责、新代码应放在哪、模块边界。
- 编码规范：语言风格、命名、错误处理、必须遵守的约定。
- 测试要求：改动后应跑哪些测试、覆盖率或测试约定。
- 禁区与注意：不能随意改的生成代码、配置、迁移、对外接口等。
关键是写「事实与可执行命令」，而不是空泛口号。「写高质量代码」没有信息量；「提交前必须 npm test，API 改动需更新对应快照」才是 Agent 真正能遵循的指引。
四、保持精简：它不是垃圾桶
最常见的失败，是把 AGENTS.md 堆成一份又长又杂的文档，什么都往里塞。上下文越长，真正关键的信息越容易被淹没，Agent 遵守的可靠性反而下降。维护原则：
- 只放高频、跨任务复用的稳定事实；一次性的临时要求不要写进来。
- 能链接就别复制：详细文档放在原处，这里用指针引用，避免重复维护。
- 定期清理：随项目演进删掉过时条目，确保每条都仍然成立。
- 结构清晰：用标题分区，让 Agent 和人都能快速定位。
把它当成「精简的项目入口卡片」，宁可短而准，不要长而泛。
五、单一事实来源与团队维护
AGENTS.md 要真正有用，团队必须把它当作项目知识的单一事实来源之一来维护：纳入版本控制，改动走评审；当构建、测试、目录约定变化时，同步更新它，并以它为准去更新必要的私有补充。
建议明确「谁负责维护」，并在项目结构变化的 PR 里把「是否需要更新 AGENTS.md」作为一个检查项。当它始终与现实一致，团队和各种工具才能放心依赖；一旦它出现过期条目，信任崩塌后反而不如没有。让「改了约定就改 AGENTS.md」成为团队肌肉记忆。
六、和 MCP、Skill、README 的分工
这几个概念常被混淆，理清边界能避免放错内容：
- AGENTS.md：告诉 Agent「在这个项目该怎么做事」的静态说明，只读、无动作。
- MCP：提供「连接外部系统、执行工具」的动态能力（见 MCP 协议）。
- Skill：封装「可复用的操作流程/脚本包」，是带步骤和资源的能力单元。
- README：主要面向人类读者的项目介绍，语气和用途不同。
一句话：AGENTS.md 管「须知」，MCP 管「连接」，Skill 管「怎么做」，README 管「给人看」。 一个典型仓库可以四者并存、各司其职：Agent 先读 AGENTS.md 了解规矩，用 MCP 连数据，调用 Skill 完成专业流程。
六点五、一份「人人都改过、却没人信」的说明
AGENTS.md 最大的敌人不是没人写，而是写了之后逐渐失真，最后谁都不敢信。讲一个常见的团队故事。
某项目一开始认真写了 AGENTS.md：构建命令、目录约定、测试方式一应俱全，新人和各种工具都靠它快速上手。问题出在后来的几次迭代：团队把构建工具从一套换成另一套，命令全变了，却只在 README 和 CI 里更新，没人想起这份文件；接着目录做了大调整，里面写的「业务代码放 src/modules」也已不成立。半年后，一位新同事照着 AGENTS.md 跑构建，命令直接报错；更糟的是，某个 Agent 按旧的目录约定把新代码放进了一个已经废弃的位置。复盘时大家才意识到：一份过期的 AGENTS.md 比没有更危险——因为它看起来权威，会被默认信任。
这个故事点出一个根本要求：AGENTS.md 的生命力在于「始终与现实一致」，而这必须靠流程保障，不能靠记忆。 具体做法是把它纳入版本控制，在改动构建、目录、测试约定的 PR 里，把「是否需要同步更新 AGENTS.md」列为一个固定检查项；并明确一位负责人定期核对。当它长期准确，信任才能积累；一旦容许过期条目存在，整个文件的价值就开始崩塌。让「改了约定就改说明」成为和「改了代码要改测试」一样自然的肌肉记忆，这份文件才真正立得住。
还有个判断小技巧：如果你不确定某条说明还成不成立，最可靠的方式不是看文档，而是实际跑一遍那条命令、看一眼那个目录。以现实为准来校准文档，而不是反过来，这是维护者应有的基本姿态。
六点六、写多还是写少：在「够用」和「淹没」之间
AGENTS.md 的篇幅是一门平衡的艺术，新手在两个极端间反复。
一个极端是写太少：只有一句「这是某某项目，请写高质量代码」。Agent 读完依然不知道怎么构建、怎么测试、代码该放哪，等于没写，还得每次靠人临时交代。另一个极端是写太多：把架构白皮书、长篇规范、历史决策、注意事项全堆进去，洋洋洒洒几千行。后果是真正关键的几条命令被淹没在大量低相关信息里，Agent 在有限注意力下反而抓不住重点，遵守的可靠性下降，每改一处也更易顾此失彼。
健康的位置是「精简而可执行」：只保留那些跨任务高频复用、Agent 做错代价高的稳定事实，并尽量用可直接执行的命令、而非形容词。 详细的架构背景、长篇论述不必复制进来，放原处、用链接指向即可。这样这份文件既能准确指导行动，又不会因过长而稀释重点。
一个实用的自检问题是：「如果只能让 Agent 记住这一页里的十条信息，哪些是真正会影响它做对事的？」围绕这十条来组织内容，其余能删则删、能链则链。把 AGENTS.md 当成一张「项目入口卡片」而非一本「项目百科」，短而准永远胜过长而泛。
六点七、互操作的真正含义：可移植的不是配置，是约定
「跨工具互操作」这个词容易被误解，值得澄清它到底承诺了什么、没承诺什么。
它不意味着你在某个工具里的全部配置——专属斜杠命令、私有 Hook、模型选择、UI 偏好——能原封不动搬到另一个工具。这些东西依赖各工具自己的机制，天然不可移植，硬要统一只会削足适履。它真正承诺的是更高一层的东西：一份用自然语言写下的、关于「在这个项目该怎么做事」的约定，任何愿意读取它的 Agent 都能理解并遵循。 可移植的是这份项目知识与协作约定，而不是某个工具的具体功能开关。
理解这一点，你对 AGENTS.md 的期待才会准确：它统一的是「认知层」——让不同工具进入同一仓库时，对构建方式、目录边界、规范禁区有共同理解；而工具各自的「能力层」差异依然存在。于是正确的架构是：用 AGENTS.md 兜住跨工具一致的稳定事实（须知），用各工具私有文件承载其独有机制，用 MCP 解决连接、Skill 封装流程。分层清晰之后，「互操作」就不再是一个含糊的口号，而是一个边界清楚、确实可达的目标——你换工具时不必重新交代一遍项目常识，这已经能省下大量重复沟通和出错成本。
六点八、新人入职视角：这份文件如何缩短上手时间
衡量 AGENTS.md 价值有个很直观的标尺：它能让一个完全不了解项目的人（或一个全新启动的 Agent）多快开始正确地干活。从新人入职视角看，最能体会它的分量。
没有这份文件时，新人的第一周往往消耗在反复追问上：环境怎么搭、构建命令是什么、测试怎么跑、代码该放哪个目录、哪些地方是雷区。这些信息散落在不同人脑中和旧文档里，问一个人得到一个答案，既打断老员工，新人也始终提心吊胆怕踩坑。Agent 的处境其实相同——没有项目说明，它只能靠自己摸索结构，每次都可能猜偏。有了一份准确的 AGENTS.md，这些「开工必备常识」被集中、提前交付：新人（和 Agent）照着重现环境、跑通构建、按约定放置代码，大量低级摩擦直接消失。
但要达到这个效果，前提仍是内容的「可执行」与「准确」。一份写着「请遵循最佳实践」的文件帮不了任何人；而一条「npm run setup 装依赖、npm test 跑全量测试、新接口放 src/api 并补对应测试」的说明，能让第一天就进入正轨。把 AGENTS.md 当作给「下一个进入项目的智能体——无论它是人还是 AI」的入职手册来经营，你会发现它省下的不仅是几次问答，而是整个团队在重复沟通和返工上持续付出的隐性成本。
六点九、和 CI 配合：让约定在提交时被真正执行
AGENTS.md 写清了约定，但「写在纸上」和「被执行」之间仍有距离。把其中可自动化的部分接到 CI，是让约定落地的有力一步。
道理很简单：文档里说「提交前必须测试通过、代码需通过 lint」，单靠人或 Agent 自觉，总会有遗漏；而在 CI 里把这些命令设为必过的检查，约定就从「建议」变成了「门禁」——不满足就合不进来。AGENTS.md 负责把这些规则讲清楚、让人和 Agent 都知道标准，CI 负责客观、稳定地执行它们，两者一个管「说明」、一个管「强制」，形成互补。这样即使某次 Agent 自信地提交了看似没问题、实则测试失败的改动，也会在 CI 被拦下，而不是流入主干。
实践时可以让 AGENTS.md 中的命令与 CI 实际执行的命令保持一致，避免「文档让你跑 A、CI 却在跑 B」的错位；当命令变更，两处连同说明一起更新。把可读的约定与可执行的检查绑定起来，这份文件就不再只是被动的参考资料，而是嵌入工作流、能真正塑造产出质量的活规则。这也是多 Agent 协作从「相信它会照做」走向「系统保证它必须做到」的关键支撑。
六点十、避免重复维护：让各文件指向同一事实
互操作的初衷是减少重复，但如果 AGENTS.md、README、各工具私有文件、CI 配置之间彼此大段复制，重复问题只是换了个地方，迟早再次漂移。这里专门讲如何从结构上避免重复维护。
核心做法是确立清晰的「事实归属」：每条关键事实只在一个地方作为权威来源，其他地方只引用、不复写。例如构建命令的权威可以是构建脚本本身或一处统一文档，AGENTS.md 里写命令但不重复其背后的长篇说明，README 里给面向人的介绍并链接细节。当命令变化，只需改权威处，其余指向它的位置天然保持一致。判断「该由谁持有」时，问一句：这条信息最根本属于哪个层面——是项目事实、人类叙事，还是工具机制？
对 AI 相关的几份文件尤其要克制：不要在私有规则文件里把 AGENTS.md 的公共内容再抄一遍，而应让它引用公共文件并只补充本工具独有部分。这样跨工具的公共事实永远只有一份，从根上消除「改一处、漏三处」。让信息有唯一的家，让其余位置只放指针，你维护的就不再是几份会逐渐分叉的副本，而是一张以单一事实为中心、彼此呼应的网络——这才真正兑现了 AGENTS.md「一处维护、处处复用」的承诺。
七、常见问题
Q：AGENTS.md 会自动生效吗？ 取决于工具是否支持这一约定。采用该约定的工具会自动读取；尚不支持的工具，可在其私有规则文件中引用同一份内容作为过渡。
Q：需要给每个子目录都放一份吗？ 通常根目录一份覆盖全局；只有当某个子目录有强特殊约定时，才在该目录补一份局部说明，避免泛滥。
Q：它能包含密钥吗？ 绝不能。它通常会进版本控制，密钥一律走环境变量或本地、不入库的配置。
Q：和 README 内容重复怎么办？ README 面向人，AGENTS.md 面向 Agent，可共享事实但不必全文复制；详细背景链接到 README，这里只保留 Agent 行动所需的精简事实。
Q：多个子模块/子项目各自有约定，怎么组织？ 根目录放全局通用约定，仅当某个子目录有明显不同的构建或规范时，在该目录补一份局部 AGENTS.md；避免给每个目录都放，造成维护泛滥和相互冲突。
Q：这份文件应该写得多正式？ 用清晰、祈使、可执行的语言即可，不必法律文书式措辞。关键是命令准确、边界明确，让 Agent 能直接照做，而不是堆砌术语或口号。
八、维护检查清单
- 公共、与工具无关的事实放在 AGENTS.md；工具专属机制放私有文件。
- 构建/测试命令准确、可直接执行；目录与规范写清。
- 明确标注禁区（迁移、生成代码、对外接口等）。
- 内容精简、多用链接而非复制，无过期条目。
- 纳入版本控制并指定负责人，随项目变更同步更新。
- 不含任何密钥或敏感信息。
总结
AGENTS.md 是跨工具共享的项目级说明，解决多工具规则重复和漂移：把「换工具仍成立」的稳定事实——构建测试命令、目录约定、编码规范、禁区——精简地写进去，作为单一事实来源纳入版本控制并随项目更新；工具私有的机制留在各自文件，与 MCP（连接）、Skill（流程）、README（给人看）分工明确，就能做到一份说明、处处复用。