AGENTS.md

由 OpenAI Codex、Amp、Google Jules、Cursor、RooCode 及 Factory 联合推出的 AGENTS.md，是一套开放且供应商中立的编程智能体（Agent）指导文件标准。作为一种简单的开放格式，它已被超过 2 万个开源项目采用，相当于为 AI 编程智能体提供了专属的 “README”—— 一个专门且可靠的信息载体，用于传递项目上下文与操作指令，帮助智能体更高效地在项目中开展工作。

为什么需要 AGENTS.md？—— 区分人类与智能体的文档需求

我们熟悉的 README.md 文件，核心服务对象是人类开发者，内容聚焦快速入门、项目描述、贡献指南等人类关注的核心信息。而 AGENTS.md 的价值，在于通过补充 AI 编程智能体所需的额外细节，解决 “人类文档” 与 “智能体需求” 的错配问题：

智能体在处理项目时，需要更具体的技术细节支撑，例如构建步骤、测试命令、代码规范等 —— 这些内容若写入 README，会让文档显得冗长杂乱，且对人类贡献者而言并非核心信息。因此，AGENTS.md 的设计逻辑是 “分开承载，各取所需”：

1. 为智能体提供清晰、固定的指令获取位置，避免其在海量文档中筛选关键信息；
2. 保持 README 的简洁性，让人类开发者能快速找到自己需要的内容；
3. 以 “智能体为中心” 提供精准指导，与现有 README、项目文档形成互补，而非替代。

更重要的是，AGENTS.md 并非某一厂商的专有文件，而是采用全行业通用的名称与格式，任何开发或使用编程智能体的团队，都可免费采用，无需担心兼容性问题。

AGENTS.md 的核心优势：跨智能体兼容，适配多样场景

AGENTS.md 的一大关键特性是 “生态兼容性”—— 其定义的指导格式，能与当前不断增长的 AI 编程智能体及工具生态系统无缝适配。无论你使用的是 OpenAI Codex、Google Jules，还是 Cursor、Aider 等工具，只要项目中包含 AGENTS.md，智能体都能识别并读取其中的指令，无需针对不同工具单独调整文档格式，大幅降低了多工具协作的成本。

同时，它还能灵活应对 “大型单一仓库” 的复杂场景：对于包含多个子项目的仓库，可在每个子项目包中嵌套放置 AGENTS.md 文件。智能体会自动读取目录树中 “最接近编辑文件” 的 AGENTS.md，遵循 “就近优先” 原则，让每个子项目都能提供定制化指令。例如，OpenAI 的主仓库目前已包含 88 个 AGENTS.md 文件，覆盖不同子项目的个性化需求。

如何使用 AGENTS.md？—— 四步搭建智能体指导文档

使用 AGENTS.md 的流程简单清晰，无需复杂配置，具体可分为四个步骤：

1. 创建 AGENTS.md 文件

在项目仓库的根目录下新建名为 “AGENTS.md” 的文件即可。若你使用的编程智能体支持自动生成功能，甚至可直接请求智能体生成一份基础模板，减少手动编写的工作量。

2. 补充核心内容模块

根据项目需求，添加帮助智能体高效工作的关键信息，常见模块包括：

• 项目概述：让智能体快速了解项目定位、核心功能与技术栈；
• 构建和测试命令：例如编译指令、单元测试执行命令等，帮助智能体完成代码验证；
• 代码风格指南：明确代码格式、命名规范等，确保智能体生成的代码符合项目标准；
• 测试指令：详细说明测试范围、测试环境配置及异常处理方式；
• 安全注意事项：如敏感数据处理规则、权限控制要求等，规避安全风险。

3. 添加个性化补充指令

除核心模块外，任何你会告知新团队成员的信息，都可写入 AGENTS.md，例如：

• 提交信息规范、拉取请求（PR）审核流程；
• 大型数据集的获取路径与使用说明；
• 项目部署步骤、环境变量配置要求等。

4. 处理大型仓库的子项目（可选）

若项目是包含多个子模块的大型仓库，可在每个子项目的目录下单独创建 AGENTS.md。智能体会自动识别并优先读取 “距离当前编辑文件最近” 的文档，确保子项目的特殊指令能被精准执行。

常见问题（FAQ）：解答使用中的关键疑问

在实际使用 AGENTS.md 的过程中，开发者常面临一些操作疑问，以下是官方给出的权威解答：

1. AGENTS.md 有必填字段吗？

没有。它本质是标准的 Markdown 文件，你可根据需求自定义标题与内容，智能体会自动解析你提供的所有文本，无需遵循固定模板。

2. 若不同 AGENTS.md 的指令冲突怎么办？

遵循 “就近优先” 原则：距离当前编辑文件最近的 AGENTS.md 指令优先生效；若用户在与智能体的聊天中给出明确提示，该提示将覆盖所有文档中的指令。

3. 智能体会自动执行 AGENTS.md 中的测试命令吗？

会。若你在文档中列出了测试命令，智能体在完成代码编写、修改等任务后，会主动尝试执行相关程序检查，若测试失败，还会尝试修复问题。

4. AGENTS.md 可以后续更新吗？

当然可以。它是动态更新的文档，随着项目迭代（如构建流程变更、测试规则调整），你可随时修改其中的内容，确保指令与项目现状保持一致。

5. 如何将现有文档迁移到 AGENTS.md？

若你之前已有类似的智能体指导文档（如 AGENT.md），可通过以下命令重命名并创建符号链接，确保向后兼容：

mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

6. 如何为特定工具配置 AGENTS.md？

• Aider 配置：在项目根目录的.aider.conf.yml文件中添加以下内容：

read: AGENTS.md

• Gemini CLI 配置：在.gemini/settings.json文件中设置上下文文件名称：

{ "contextFileName": "AGENTS.md" }

关于 AGENTS.md：源于协作，服务全社区

AGENTS.md 并非单一机构的成果，而是 AI 软件开发生态系统集体协作的产物 ——OpenAI Codex、Amp、Google Jules、Cursor、Factory 等团队共同参与了标准的制定与打磨。

其核心目标是维护并发展这一开放格式，让整个开发者社区受益，无论你使用的是哪款编程智能体、身处哪个技术领域。随着 AI 编程工具的普及，AGENTS.md 有望成为项目文档的 “标配”，进一步降低人机协作的门槛，提升开发效率。