跳到主要内容

AGENTS.md 与跨工具互操作

进阶

你已经了解了 CLAUDE.md——Claude Code 的项目说明文件。但你的仓库很可能不止被一个代理触及：队友在用 Codex，CI 用了一个编码机器人，还有人在 Cursor 里打开了这个仓库。AGENTS.md 就是这些工具一致同意会去读取的开放标准，因此你只需编写一次项目说明，而不必为每个工具维护一个不同的文件。

What you'll learn
  • AGENTS.md 是什么、由谁来管理
  • 为什么 Claude Code 读取 CLAUDE.md 而不读 AGENTS.md
  • 在各工具间保持单一可信来源的三种可靠方法
  • 嵌套和全局的 AGENTS.md 文件如何合并
  • 什么内容应该放进文件——什么应该排除在外

AGENTS.md 是什么​

AGENTS.md 是位于仓库根目录的一个纯 Markdown 文件——可以把它看作一份写给代理而不是写给人类的 README。它告诉编码代理如何构建、测试和参与该项目。这种格式没有必填字段：代理只是直接读取其中的文字。

它是一个开放标准，由 Linux 基金会下属的 Agentic AI Foundation（AAIF） 管理，截至 2026 年中，已被 6 万多个开源项目使用，并被 30 多个工具读取——包括 OpenAI Codex、Google 的 Jules 和 Gemini CLI、Cursor、Windsurf、Devin、Zed、Warp、Aider、goose、Amp，以及 GitHub Copilot 的编码代理。

What you'll learn
  • AGENTS.md 是一种约定，而不是运行时：每个工具自行决定如何发现、合并和注入该文件。
  • 没有强制的 schema——清晰的文字胜过僵化的结构。
  • 它是对你的 README 的补充；并不取代它。

Claude Code 的那个坑​

人们容易踩的地方在于：Claude Code 读取 CLAUDE.md，而不是 AGENTS.md。 如果你的仓库里只有一个 AGENTS.md，Claude Code 默认会忽略它。这不是一个 bug——它早于这个标准出现——但它意味着一个多工具的仓库需要一套刻意的同步策略，否则你的说明会悄悄地相互偏离。

Watch out
  • 不要假设 Claude Code 会回退到 AGENTS.md——它不会自动读取它。
  • 两个手工维护的文件（CLAUDE.md 和 AGENTS.md）会发生偏离。选定一个单一可信来源。
  • 在依赖任何回退说法之前，先在官方内存文档中确认当前行为。

保持单一可信来源​

有三种模式能在不重复内容的情况下让 CLAUDE.md 和 AGENTS.md 保持同步。根据你团队的平台来选择。

Guided walkthrough1 of 3
  1. 把 CLAUDE.md 做成指向 AGENTS.md 的符号链接。Claude Code 会跟随符号链接并逐字节读取目标文件——只有一个真实文件，零合并逻辑。注意事项：在 Windows 上，创建符号链接需要开发者模式或管理员权限，因此跨平台团队可能更倾向于导入方法。

把 CLAUDE.md 符号链接到共享标准文件（macOS / Linux）

ln -s AGENTS.md CLAUDE.md

或者保留一个仅一行、用于导入它的 CLAUDE.md

@AGENTS.md
Pro tip
  • 当你整个团队都在 macOS/Linux 上时，使用符号链接——它需要维护的东西最少。
  • 当团队里有 Windows 贡献者时，使用 @import。
  • 无论你选择哪一种,都把它提交进仓库,这样整个团队都能获得相同的行为。

嵌套和全局文件如何合并​

更完善的代理会以分层方式处理 AGENTS.md——和 CLAUDE.md 内存层级 是同一套心智模型。以 Codex 为例，它会从你主目录中的全局文件出发，向下经过 Git 根目录直到你当前的文件夹，一路拼接：

越靠近实际工作的文件越占上风，因为它们最后被拼接，会覆盖更早的指引。因此 services/payments/AGENTS.md 会继承仓库根目录的说明，并加入仅在该服务内部适用的规则——把专门的指引尽量放在离专门代码最近的地方。

互操作一览
按 Enter 或空格键翻转卡片。使用左右方向键在卡片之间切换。已显示术语。
1 / 5

该往里放什么​

和一份好的 CLAUDE.md 是同样的纪律——这个标准只是建议了几个常见的小节：

  • 项目概览——这是什么，两句话讲清。
  • 构建与测试命令——如何运行、测试和检查代码风格。
  • 代码风格——代理无法推断的约定。
  • 测试说明——“完成”意味着什么。
  • 安全注意事项——永远不要触碰或提交什么。
  • 提交 / PR 指南——消息格式、分支规则。
Watch out
  • 代理会逐字遵循该文件——过时或一厢情愿的说明会实实在在地造成伤害，和 CLAUDE.md 完全一样。
  • 保持简短且真实；描述项目当下的实际运作方式。
  • 永远不要提交机密信息；引用大型文档，而不是把它们粘贴进来。

自我检验​

自我检验

0/3
  1. Claude Code 会自动读取 AGENTS.md 吗？
  2. 你的团队完全在 macOS 和 Linux 上。在 Claude Code 和 Codex 之间共享一份说明文件、维护成本最低的方式是什么？
  3. 当代理合并一个全局、一个仓库根目录和一个子目录的 AGENTS.md 时，发生冲突时哪一个占上风？
Key takeaways
  • AGENTS.md 是由 Linux 基金会管理、被 30 多个编码代理读取的开放标准——一份写给代理的 README。
  • Claude Code 读取 CLAUDE.md，而不是 AGENTS.md，因此多工具仓库必须让二者保持同步。
  • 在 Mac/Linux 上把 CLAUDE.md 符号链接到 AGENTS.md，或为跨平台团队使用一行 @AGENTS.md 导入。
  • 嵌套文件按 全局 → 根目录 → 子目录 合并，离得最近的文件占上风。
  • 像填写一份出色的 CLAUDE.md 那样填写它：概览、构建/测试命令、约定、安全和护栏——简短且真实。

下一步​

来源与延伸阅读​