与 README 分工
README 讲快速上手、项目介绍与贡献指南；AGENTS.md 存放代理需要的详细上下文，如构建步骤、测试和约定，避免 README 被这些内容撑乱。
价格免费
平台Web
归类AI 智能体
收录2025-01-01
复核2025-01-01
编辑评分
4.4 / 5
★★★★☆
AGENTS.md编辑总结
AGENTS.md 是一套开放的文件格式约定，把构建步骤、测试命令、代码约定这些编码代理需要、但会撑乱 README 的上下文单独放一个文件。它与 README.md 明确分工：README 面向人类贡献者讲快速上手与项目介绍，AGENTS.md 面向代理讲细节。文件在仓库根目录，格式自由，不是某家厂商的专有格式。目前兼容 Codex、Jules、Aider、goose、opencode、Zed、Warp、VS Code、Devin、Junie、Amp、Cursor、RooCode、Gemini CLI、Kilo Code、Semgrep、GitHub Copilot 的编码代理、Ona、Windsurf、Augment Code 等一批代理与工具。短板是文件本身只是一份约定，具体能读到什么程度取决于各代理实现。
AGENTS.md是什么？
AGENTS.md 是一个开放的文件格式，用来向编码代理提供项目说明。它由与 README 相同的仓库根目录承载，但内容面向的是代理而不是人：构建步骤、测试方式、代码约定等会撑乱 README、或与人类贡献者无关的细节。官网明确说明这是刻意与 README 分开的设计，而不是又一个专有文件。
按官网所述，它的定位是给代理一个清晰、可预期的指令位置，同时让 README 保持简洁、继续聚焦人类贡献者。文件的名字和格式被设计成任何人都可采用，官网也邀请正在构建或使用编码代理的团队自行采用。
实际使用时，一个 AGENTS.md 可以跨多个代理工作。包括了兼容清单，覆盖 OpenAI 的 Codex、Google 的 Jules 与 Gemini CLI、JetBrains 的 Junie、Cognition 的 Devin 与 Windsurf、GitHub Copilot 的编码代理，以及 Aider、goose、opencode、Zed、Warp、VS Code、Factory、Amp、Cursor、RooCode、Kilo Code、Phoenix、Semgrep、Ona、Augment Code 等工具。在大型 monorepo 中，可以在每个子包里再放一个 AGENTS.md，代理会自动读取目录树中最近的那个文件，最近的优先，每个子项目都能带自己的定制说明。
AGENTS.md核心功能
跨代理通用
同一份定义可被不断扩大的代理与工具生态读取，包括的兼容对象覆盖 Codex、Jules、Aider、goose、opencode、Zed、Warp、VS Code、Devin、Junie、Amp、Cursor、Gemini CLI 等。
开放格式定位
没有引入又一个专有文件，而是选了任何人都能用的名字与格式，并邀请正在构建或使用编码代理的团队自行采用，不绑定单一厂商。
内容自由编排
官网给出的常用段落包括项目概览、构建与测试命令、代码风格指南、测试说明、安全注意事项；提交信息与 PR 规范、部署步骤、大型数据集等也可以写进去。
monorepo 嵌套
每个子包内可再放一份 AGENTS.md。代理自动读取目录树中最近的文件，最近的一份优先，从而让每个子项目下发给代理的说明可以不同。
自动生成
官网说明在仓库根目录创建 AGENTS.md 后，多数编码代理可以在被要求时直接为项目生成一份初稿，省去从空白文件开始写的时间。
AGENTS.md值不值得用？
当你在做有明确构建与测试流程、且多人（或多代理）协作的代码仓库时，值得为它写一份 AGENTS.md，把命令和约定集中交代，代理不必再从 README 里猜。当你只是维护一个简单脚本或一次性小项目，写它的收益有限，不如把几条命令直接写进 README。大型 monorepo 值得用嵌套文件，但要注意子项目一多，说明的维护成本也会跟着涨。另外它只是一份约定，代理实际读到哪一步、忽略哪些内容，取决于各工具自己的实现，遇到不生效先确认该工具是否在兼容清单里。
建议选它的情况
- 仓库有固定的构建、测试、lint 命令，想让代理照着执行
- 团队同时用多种编码代理，希望一份说明通用
- monorepo 需要按子包下发不同约定
- README 已偏向人类贡献者，不想再塞代理细节
不建议选它的情况
- 只想写个临时脚本或一次性小项目，几条命令写 README 就够
- 还没有固定下来的构建与测试流程，写了也要反复改
- 所用代理不在兼容清单里，先确认它是否读取这个文件
AGENTS.md适合谁用？
多代理并用的团队
推荐团队里同时有人用 Codex、Cursor、Gemini CLI 等不同工具，一份 AGENTS.md 就能覆盖，不必为每个代理各维护一份说明。
monorepo 维护者
推荐可以在每个子包内单独放一份，代理读取目录树中最近的文件，最近的一份优先，各子项目带着自己的构建与测试约定。
个人开源仓库作者
推荐把测试命令和提交规范写进 AGENTS.md，README 继续保持面向人类贡献者的简洁，两者分开反而省事。
流程尚未固定的早期项目
有条件构建、测试方式还在频繁变动，写下的命令很快会过时，可以等流程稳定后再补，或只写最少几条。
期待开箱即用的新手
有条件它只是约定，不会自动带来能力；代理是否读取、读到多少，取决于你所用的工具是否在兼容清单中。
AGENTS.md优点和缺点
优点
- 与 README 明确分工，代理细节不再挤占人类贡献者要看的文档
- 名字与格式开放，非专有，任何团队都可以采用
- 同一份定义可被大量编码代理与工具读取
- 支持在 monorepo 子包内嵌套，最近的文件优先生效
- 官网提供可直接参照的样例与分步上手说明
缺点
- 本身只是约定，实际读取效果取决于各代理实现
- 内容需要随项目流程变化持续维护，否则命令会过时
- 未公开提供方式与支持范围的说明
AGENTS.md常见问题
AGENTS.md 和 README 到底有什么区别？＋
README.md 面向人，讲快速上手、项目介绍和贡献指南；AGENTS.md 放的是代理需要的额外上下文，比如构建步骤、测试和约定。说明这样分开是为了让 README 保持简洁、专注于人类贡献者，同时给代理一个清晰可预期的指令位置。
一份 AGENTS.md 能同时给多个代理用吗？＋
可以。包括的兼容对象包括 Codex、Jules、Factory、Aider、goose、opencode、Zed、Warp、VS Code、Devin、Junie、Amp、Cursor、RooCode、Gemini CLI、Kilo Code、Phoenix、Semgrep、GitHub Copilot 的编码代理、Ona、Windsurf、Augment Code 等，同一份定义可被这一生态读取。
里面应该写什么内容？＋
给出的常用段落有项目概览、构建与测试命令、代码风格指南、测试说明、安全注意事项。此外提交信息与 PR 规范、部署步骤、大型数据集等这类你会告诉新同事的内容，也适合放进去。
文件要放在哪里？monorepo 怎么办？＋
放在仓库根目录。如果是大型 monorepo，可以在每个子包内再放一份 AGENTS.md，代理会自动读取目录树中最近的那个文件，最近的一份优先，因此每个子项目都能带自己的定制说明。
需要自己从零写吗？＋
不一定。说明在仓库根目录创建 AGENTS.md 后，多数编码代理可以在被要求时直接为项目生成一份初稿，你在这个基础上按项目实际情况调整即可。
写好了代理就一定会照做吗？＋
它给代理提供了一个清晰、可预期的指令位置，但读取与执行的程度由各编码代理自行实现。使用前先确认你用的工具是否在兼容清单里，遇到没有生效优先排查这一点。
AGENTS.md竞品对比
| 工具 | 编辑评分 | 价格 | 核心功能 | 平台 |
|---|---|---|---|---|
| AGENTS.md本工具 | 4.4 | 免费 | 与 README 分工；跨代理通用；开放格式定位；内容自由编排 | Web |
| GitNexus | — | 未标价 | 为 AI 编码代理提供精准代码库上下文的知识图谱 | — |
| Fudge | — | 未标价 | 面向编程代理的 AI 设计参考引擎 | — |
| VibeKit | — | 未标价 | 开源 SDK,用于在安全沙箱中运行编码代理 | — |
| JFrog Boost CLI | — | 未标价 | 减少编码代理令牌浪费的本地 CLI 工具 | — |
| Nora | — | 未标价 | 专为 Web3开发设计的深度推理 AI 编码代理，提高生产力和代码安全性 | — |
