什么是 AGENTS.md？面向编码智能体的仓库级说明文件

AGENTS.md 是一种放在代码仓库中的说明文件，用于向编码智能体（coding agent）提供它们完成工作所需的补充上下文，例如构建步骤、测试命令与代码约定。按照 AGENTS.md 官方规范的说法，README.md 是给人类看的：快速上手、项目介绍、贡献指南；AGENTS.md 则是对它的补充，承载那些如果写进 README 会让文档变得臃肿、或者对人类贡献者并不相关的细节。它要解决的问题是：让智能体有一个清晰、可预期的位置去读取指令，同时让 README 保持简洁并专注于人类贡献者。

为什么重要

在 AGENTS.md 出现之前，项目里唯一被广泛约定的说明文件是 README.md。README 的读者是人：新加入的贡献者需要知道项目做什么、怎么跑起来、怎么提交改动。但编码智能体需要的信息并不完全重合，而且往往更细碎：某个包该用哪条命令单独构建、测试套件怎么只跑一个用例、改动文件后要不要补测试、提交信息用什么格式。这些内容如果全部塞进 README，会稀释它对人类读者的价值；如果散落在各处，智能体又难以稳定地找到。

官方规范给出的取舍是：与其再引入一个专有的文件名，不如选择一个任何人都能用的名称与格式。规范明确表示，AGENTS.md 刻意与 README 分开，目的有三点——给智能体一个清晰、可预期的指令位置；让 README 保持简洁并聚焦于人类贡献者；提供精确的、面向智能体的指引，与既有的 README 和文档形成互补。规范同时说明，如果开发者正在构建或使用编码智能体并觉得这一做法有帮助，可以自行采用。

另一个重要之处在于跨工具的通用性。官方规范称，一份 AGENTS.md 可以跨多种智能体工作，并列出其智能体定义与不断增长的 AI 编码智能体与工具生态兼容，其中包括 OpenAI 的 Codex、Google 的 Jules、Factory、Aider、goose、opencode、Zed、Warp、VS Code、Cognition 的 Devin、UiPath 的 Autopilot 与 Coded Agents、JetBrains 的 Junie、Amp、Cursor、RooCode、Google 的 Gemini CLI、Kilo Code、Phoenix、Semgrep、GitHub 的 Coding agent from GitHub Copilot、Ona、Cognition 的 Windsurf 以及 Augment Code。需要说明的是，这份名单来自官方规范自身的表述，属于该规范的主张，而不是对第三方工具实际支持程度的独立验证。

工作机制

AGENTS.md 的机制并不复杂，核心是「约定文件名 + 就近读取」。官方规范给出的使用步骤可以概括为以下几点。

在仓库根目录创建文件。 在代码仓库的根目录放置一个 AGENTS.md 文件。规范提到，多数编码智能体在你提出请求时甚至可以直接帮你生成一个初稿。
写入真正影响工作的内容。 添加能帮助智能体有效处理该项目的章节。规范列举的常见选择包括：项目概览、构建与测试命令、代码风格指南、测试说明、安全注意事项。
补充额外指令。 提交信息或拉取请求（pull request）的规范、安全方面的坑、大型数据集、部署步骤——凡是你会告诉一位新同事的内容，都可以写进来。
大型单体仓库使用嵌套文件。 在大型单体仓库（monorepo）中，可以在每个子项目里再放一个 AGENTS.md。规范称，智能体会自动读取目录树中最近的那个文件，因此最近的文件优先，每个子项目都能携带为自己定制的指令。

第 4 点是这套机制里最值得注意的设计：它把「指令作用域」交给了文件系统层级。根目录的 AGENTS.md 相当于全局约定，子目录中的 AGENTS.md 相当于局部覆盖，越靠近当前工作目录的文件优先级越高。这样，一个仓库里不同技术栈、不同发布节奏的子项目可以各自维护自己的构建与测试说明，而不必在一份总文件里互相干扰。

从内容形态上看，AGENTS.md 是纯文本的说明文档，通常使用 Markdown 书写，包含标题与列表。它不引入新的配置语法，也不要求特定的运行时；智能体读取它、理解它，然后据此决定执行哪些命令。这意味着它的有效性取决于写作者是否把关键信息写清楚，而不是取决于某种自动校验机制。

典型例子

官方规范给出了一份示例 AGENTS.md 文件，其结构可以直接反映这类文件通常包含什么。示例分为三个部分。

开发环境提示（Dev environment tips）。 示例建议使用 pnpm dlx turbo run where <project_name> 直接跳转到某个包，而不是用 ls 逐个扫描；用 pnpm install --filter <project_name> 把包加入工作区，以便 Vite、ESLint 和 TypeScript 能识别它；用 pnpm create vite@latest <project_name> -- --template react-ts 创建一个带 TypeScript 检查的 React + Vite 包；并提醒检查每个包 package.json 里的 name 字段以确认名称正确，跳过顶层的那一个。

测试说明（Testing instructions）。 示例要求在 .github/workflows 目录中找到 CI 计划；用 pnpm turbo run test --filter <project_name> 运行该包定义的全部检查；在包根目录可以直接调用 pnpm test，并强调合并前提交必须通过所有测试；若要只跑某一步，可以加上 Vitest 的模式 pnpm vitest run -t "<test name>"；修掉所有测试或类型错误直到整套测试变绿；移动文件或修改导入后，运行 pnpm lint --filter <project_name> 确认 ESLint 与 TypeScript 规则仍然通过；并且即使没有人要求，也要为改动的代码添加或更新测试。

拉取请求说明（PR instructions）。 示例规定标题格式为 [<project_name>] <Title>，并要求提交前始终运行 pnpm lint 与 pnpm test。

官方规范还提到，可以在 GitHub 上查看 6 万多个示例，并列出了一些采用该文件的仓库作为参考，例如 openai/codex（面向 AI 编码智能体的通用命令行工具，Rust）、apache/airflow（以编程方式编写、调度和监控工作流的平台，Python）、temporalio/sdk-java（Temporal 的 Java SDK，用代码定义工作流编排，Java）以及 PlutoLang/Pluto（面向通用编程的 Lua 5.4 超集，C++）。这些例子说明 AGENTS.md 并不绑定某一种语言或某一种项目类型。

边界与常见误解

第一，AGENTS.md 不是 README.md 的替代品。官方规范明确把两者定位为分工关系：README 面向人类，负责快速上手、项目描述与贡献指南；AGENTS.md 承载智能体需要的额外上下文。把人类文档整体搬进 AGENTS.md，或者反过来把智能体指令塞进 README，都偏离了这一设计意图。

第二，它不是某个厂商的专有格式。规范强调，之所以选择这样一个名称与格式，是为了避免再引入一个专有文件，让任何人都能使用。但需要区分「规范的主张」与「实际支持情况」：规范列出了它所称的兼容工具生态，这份名单出自规范本身，读者不应把它当作对每个工具支持程度与支持版本的独立核实结果。

第三，嵌套文件的优先级依赖「就近读取」这一行为。规范称智能体会自动读取目录树中最近的文件，最近者优先。这意味着如果子目录里存在一个内容过时或与根目录冲突的 AGENTS.md，它可能覆盖掉根目录的全局约定。维护者需要把嵌套文件当作真实生效的配置来对待，而不是随手留下的草稿。

第四，AGENTS.md 本身不提供强制力。它是写给智能体阅读的自然语言说明，没有 schema、没有校验器，也没有规定智能体必须遵守其中每一条。写得不清楚、命令写错、或者与仓库实际状态脱节，都会直接削弱它的作用。规范给出的建议是把「你会告诉一位新同事的内容」写进去，这实际上也界定了它的合理边界：它是入职说明，不是构建系统，也不是权限控制机制。

第五，示例中的命令与工具链（pnpm、turbo、Vite、Vitest、ESLint、TypeScript、GitHub Actions）只是官方示例采用的一套具体组合，并不构成对读者的技术要求。AGENTS.md 的格式本身与这些工具无关，任何项目都可以按自己的技术栈撰写对应内容。

参考资料

AGENTS.md 官方规范