编写 AGENTS.md
AGENTS.md 是仓库中 AI Agent 的入口文件。Agent 工具在每次会话开始时都会加载它,且上下文空间有限,因此每一行都必须言之有物。
强制要求
每个项目都必须在仓库根目录放置一个 AGENTS.md。
AGENTS.md 是规范文件名。不要把同一套规则复制到 CLAUDE.md 等兼容文件名中:重复的指令文件会逐渐不一致,还会重复占用上下文预算。
内容放在合适的文件
将各类指导放在合适的位置:
| 内容 | 归属 |
|---|---|
| 始终生效的命令、约定和边界 | AGENTS.md |
| 产品背景、上手介绍、截图 | README.md |
| 完整的开发工作流和工具链细节 | DEVELOPMENT.md |
| pull request、评审和校验要求 | CONTRIBUTING.md |
| 架构不变量 | ARCHITECTURE.md |
| 仅某个工作流需要的操作步骤 | 独立文档或 Agent skill,并通过链接引用 |
| Agent 工具偏好、默认模型和自主度 | 该工具自己的配置文件 |
不要把运行手册、长篇参考文档或特定任务笔记写入 AGENTS.md,而应链接到事实来源。
结构
开头用一句话说明项目是什么以及面向谁,然后按 Agent 最先需要的内容排列章节,与模板保持一致:
- 命令——列出环境搭建、运行、单个测试、完整测试、Lint、类型检查、构建、重新生成和完整校验所需的准确命令;项目没有的条目直接删除。
- 工程标准——共享指南和项目特有的例外。
- 目录布局——每个顶层目录各占一行,点名关键模块。
- 边界——必须做 / 绝不做 / 先问。
- 已确认的语言政策——参见语言政策。
- 项目约定——Agent 无法仅凭代码推断的决策。
- 深入文档链接——指向
DEVELOPMENT.md、CONTRIBUTING.md和ARCHITECTURE.md。
命令放在最前面,因为 Agent 一上手就要用到。同时列出小范围命令(如只跑单个测试文件)和完整检查(提交前运行 mise run check),避免 Agent 每次小改都去跑最慢的全量命令。
写可验证的规则
每条规则都必须明确说明 Agent 可以执行、评审者可以核对的行为。点名命令、路径或条件。
可验证:
- 改动 `src/auth/` 下的文件时,运行 `mise run test -- src/auth/token.test.ts`。
- 绝不手改 `src/generated/` 下的文件;用 `mise run codegen` 重新生成。
- 新增依赖或改动 `ARCHITECTURE.md` 中的不变量前先问。
不可验证,因此无用:
- 处理认证代码时要小心。
- 确保一切正常。
- 遵循最佳实践。
嵌套文件
只有子目录树确实存在差异时,才在其中增加嵌套的 AGENTS.md:
- 它使用不同的包管理器、测试运行器或运行时。
- 它包含只能重新生成、不能手改的生成代码。
- 其中的数据库迁移或部署等操作需要额外审批。
- 它有不适用于别处的 UI 或设计系统规则。
嵌套文件只记录自己的差异,其余一切沿用根文件。绝不在嵌套文件里重述根文件的规则。
保持精简
每次任务开始时都会加载该文件,文件越长,每次运行消耗的上下文就越多。
- 把最重要的规则放在最前面。
- 链接到详细文档,不要复制内容。
- 能用工具检查的就不要靠文字叮嘱:Lint 工具、prek 或 CI 已经强制执行的规则不必再写一遍。
- 把特定子系统的指引放进子目录的嵌套文件,不要让根文件不断膨胀。
根文件应能一口气读完。如果篇幅过长,应把细节拆到链接文档,并删掉已由工具强制执行的规则。
绝不写入的内容
- 敏感凭据、令牌或内部主机名。
- 仓库里已有文档的副本。
- 详尽的目录清单——下一次重构就会过期。
- 应该留在 issue 或 pull request 里的临时任务笔记。
- 要求无条件跳过校验的指令。
保持更新
命令、目录布局、边界或约定发生变化时,在同一个变更中更新 AGENTS.md。
过时的指令比缺失的指令更糟:Agent 会毫不怀疑地照做,并做出没人要求的改动。