主题
AGENTS.md
AGENTS.md 是给编码 Agent 的项目上下文与工作指令，相当于面向 Agent 的 README。普通 Markdown，没有必填字段或固定章节。作用是让 Agent 在修改前拿到明确、可执行、与项目相关的信息。
与 README.md
| 文件 | 面向对象 | 内容 |
|---|---|---|
README.md | 开发者、使用者、贡献者 | 项目介绍、快速开始、使用与贡献 |
AGENTS.md | 编码 Agent | 环境、命令、代码约定、测试、安全边界与任务规则 |
面向人的说明留在 README.md。Agent 需要、但不适合放进 README 的细节放在 AGENTS.md。
放置与优先级
根目录放全局规则。大型仓库可在应用、包或子项目目录再放局部文件。
bash
repo/
├── AGENTS.md
├── apps/
│ ├── web/
│ │ └── AGENTS.md
│ └── api/
│ └── AGENTS.md
└── packages/
└── ui/
└── AGENTS.md支持该约定的 Agent，编辑时通常读取目录树中最近的一份；离目标文件更近的优先。当前对话中的明确指令优先于文件。
各工具的自动发现、嵌套和覆盖实现可能不同。多工具共用时，在根目录规则中写明局部规则的位置与适用范围。
内容
- 项目概览与关键目录。
- 安装、开发、构建、格式化、测试等命令。
- 语言、框架、代码风格与命名。
- 测试范围、CI 检查与完成条件。
- 密钥、用户数据、生产环境、删除与发布等安全边界。
- 提交信息、Pull Request、部署和大型数据集等协作约定。
规则写成可验证行为：命令、路径、前置条件、禁止操作。
拆分
高频、全局、简短的规则留在 AGENTS.md。低频、专题或篇幅长的内容拆出，并同时写明触发条件和文件路径，例如修改 API、Schema 或接口客户端前阅读哪一份文档。
单次任务要求放 Prompt。私有路径、内网地址、个人偏好和敏感信息不进入公共 AGENTS.md。
规则
- 只记录长期稳定、且直接影响完成任务的信息。
- 使用命令式、具体表述。
- 工具专属配置单独说明；默认各 Agent 能力不同。
- 随技术栈和流程更新。