AGENTS.md

AGENTS.md 是为编码 Agent 提供项目上下文与工作指令的约定文件，可视为面向 Agent 的 README。

它使用普通 Markdown，没有必填字段或固定章节。重点是让 Agent 能在开始修改前，获取明确、可执行且与项目相关的信息。

与 README.md 的区别

文件	面向对象	内容重点
README.md	开发者、使用者、贡献者	项目介绍、快速开始、使用与贡献说明
AGENTS.md	编码 Agent	环境、命令、代码约定、测试、安全边界与任务规则

两者互补：README.md 保持面向人的简洁说明；AGENTS.md 承载对 Agent 有必要、但不适合放入 README 的细节。

放置与优先级

在仓库根目录放置 AGENTS.md，记录全局规则；大型仓库可在应用、包或子项目目录增加局部 AGENTS.md。

repo/
├── AGENTS.md
├── apps/
│   ├── web/
│   │   └── AGENTS.md
│   └── api/
│       └── AGENTS.md
└── packages/
    └── ui/
        └── AGENTS.md

对于支持该约定的 Agent，编辑文件时通常读取其目录树中最近的 AGENTS.md；离目标文件更近的规则优先。用户在当前对话中给出的明确指令优先级更高。

不同 Agent 对自动发现、嵌套规则和覆盖关系的实现可能不同。需要跨工具使用时，应在根目录规则中明确局部规则的位置与适用范围。

应包含的内容

• 项目概览与关键目录。
• 安装、开发、构建、格式化、测试等可执行命令。
• 语言、框架、代码风格与命名约定。
• 测试范围、CI 检查与完成条件。
• 密钥、用户数据、生产环境、删除与发布等安全边界。
• 提交信息、Pull Request、部署和大型数据集等协作约定。

规则应描述可验证的行为，例如指定命令、路径、前置条件和禁止操作，避免只写“保持代码质量”之类无法执行的要求。

规则拆分

AGENTS.md 适合存放高频、全局、简短的规则。低频、专题或篇幅较长的内容应拆分为独立文档，并写明触发条件和文件路径。

## 任务规则

- 修改前端页面或组件前，阅读 `docs/agent-rules/frontend.md`。
- 修改 API、Schema 或接口客户端前，阅读 `docs/agent-rules/api.md`。
- 涉及认证、权限、Token、支付、Webhook 或用户数据时，
  必须阅读 `docs/agent-rules/security.md`。
- 修改 CI/CD、Docker、环境变量或发布流程前，
  阅读 `docs/agent-rules/deployment.md`。

不要只写“详见某文档”；应同时给出何时读取、读取哪个文件。私有路径、内网地址、个人偏好与敏感信息不应提交到公共 AGENTS.md。

编写原则

• 记录长期稳定的项目规则，不写单次任务的临时要求。
• 保持简洁，优先写对完成任务有直接影响的信息。
• 使用命令式、具体的表述，避免模糊口号。
• 不假设所有 Agent 具备相同能力；工具专属配置应单独说明。
• 将 AGENTS.md 视为持续维护的项目文档，随技术栈和流程更新。

参考

• AGENTS.md