AGENTS.md 指南：面向编码代理（AI Agents）的开源“项目说明书”格式。AGENTS.md 是一个面向“编码代理（AI coding agents）”的开源说明格式。它像 README 的“代理版”：为代理提供构建、测试、代码规范与注意事项等关键信息，帮助代理在你的代码库里更可靠地执行任务。据站点自述，已有大量开源项目采用该格式；其设计目标是跨多种代理与工具通用，适合团队与开源仓库快速落地。
一、AGENTS.md 是什么
1）定位：面向 AI 编码代理的说明文件，是 README 的功能补充。
2）目标：给代理一个固定、可预测的入口，集中放置“让代理高效工作”的上下文与指令。
3）形态：纯 Markdown，无强制字段；按需编写，便于长期维护与版本管理。
二、为什么需要 AGENTS.md（与 README 的关系）
1）README 面向人类读者，强调产品描述、快速上手与贡献指南。
2）AGENTS.md 面向代理，强调构建/测试命令、代码风格、CI 要求与安全要点。
3）分离的好处：让 README 保持简洁，同时给代理一个“只看这份就能干活”的专位文档。
三、核心设计与生态兼容
1）开放格式：用任何小节标题与内容结构，代理按文本解析，无专有语法。
2）多代理兼容：官方列出多款代理/工具的适配方向（如 Codex、Amp、Jules、Cursor、Factory、RooCode 等）。
3）优先级规则：在指令冲突时，离目标文件最近的 AGENTS.md 生效；显式的用户对话指令优先于通用说明。
4）Monorepo 友好：支持在子包放置“就近”的 AGENTS.md；大仓库可分层管理不同子项目的代理说明。
四、如何采用（四步走）
1）添加文件：在代码库根目录创建 AGENTS.md；必要时在子包也放一份。
2）覆盖重点：项目概览、构建与测试命令、代码风格、测试规范、安全与合规要点。
3）补充细则：提交信息与 PR 规范、数据与模型资源下载、部署步骤与常见陷阱。
4）迭代维护：把它当作“活文档”，随 CI/依赖/目录结构更新而更新。
五、最小可用模板
# AGENTS.md ## Project overview - Monorepo + PNPM workspace。主语言 TypeScript。 ## Setup & build - Install: pnpm install - Dev: pnpm dev - Test: pnpm test - Lint: pnpm lint ## Code style - TS strict mode；单引号、无分号；函数式优先。 ## Testing - CI 在 .github/workflows；提交前需本地通过全部用例。 ## PR rules - 标题：[<pkg>] <title>；提交前必须跑 lint 和 test。 ## Security - 不要提交 .env；密钥使用仓库机密或本地注入。
六、典型使用场景
1）开源仓库：让首次接触的代理“开箱可测”，自动执行构建/单测/静态检查。
2）团队协作：将“隐性约定”（编码风格、提交流程）显式化，减少代理与人协同的摩擦。
3）大仓库治理：按子项目拆分 AGENTS.md，实现就近指令与差异化流程。
4）安全与合规：把“不可上传的数据/模型”与安全红线写清楚，降低自动化操作的风险。
七、实施建议与风险提示
1）先从“最小模板”做起：仅放构建、测试、风格与 PR 规则，随后逐步细化。
2）与 CI 对齐：把 CI 的关键命令同步到 AGENTS.md，避免“代理会跑但 CI 不过”。
3）显式冲突处理：在文件顶部写明“若与用户指令冲突，以用户指令为准”。
4）声明不确定：涉及“多少项目已采用”等指标，建议标注“据站点自述”，避免数据误读。
Q&A 常见问题
Q：AGENTS.md 是否有强制字段或标准模板？
A：没有。它是通用 Markdown 说明，鼓励按项目实际需要组织章节。
Q：与 README 如何分工？
A：README 面向人；AGENTS.md 面向代理。前者讲“是什么/如何上手”，后者讲“代理如何执行构建/测试/规范”。
Q：Monorepo 如何组织多份 AGENTS.md？
A：根目录放总说明，子包放就近说明；代理通常会优先读取离目标文件最近的一份。
Q：是否支持多家代理工具？
A：据项目页介绍，旨在兼容多款代理与工具，原则上“一份文档，多代理可用”。
