本页目录

本页目录

编写 AGENTS.md

AGENTS.md 是仓库中 AI Agent 的入口文件。Agent 工具在每次会话开始时都会加载它,且上下文空间有限,因此每一行都必须言之有物。

模板:project-agents.template.md

强制要求

每个项目都必须在仓库根目录放置一个 AGENTS.md。

AGENTS.md 是规范文件名。不要把同一套规则复制到 CLAUDE.md 等兼容文件名中:重复的指令文件会逐渐不一致,还会重复占用上下文预算。

内容放在合适的文件

将各类指导放在合适的位置:

内容 归属
始终生效的命令、约定和边界 AGENTS.md
产品背景、上手介绍、截图 README.md
完整的开发工作流和工具链细节 DEVELOPMENT.md
pull request、评审和校验要求 CONTRIBUTING.md
架构不变量 ARCHITECTURE.md
仅某个工作流需要的操作步骤 独立文档或 Agent skill,并通过链接引用
Agent 工具偏好、默认模型和自主度 该工具自己的配置文件

不要把运行手册、长篇参考文档或特定任务笔记写入 AGENTS.md,而应链接到事实来源。

结构

开头用一句话说明项目是什么以及面向谁,然后按 Agent 最先需要的内容排列章节,与模板保持一致:

  1. 命令——列出环境搭建、运行、单个测试、完整测试、Lint、类型检查、构建、重新生成和完整校验所需的准确命令;项目没有的条目直接删除。
  2. 工程标准——共享指南和项目特有的例外。
  3. 目录布局——每个顶层目录各占一行,点名关键模块。
  4. 边界——必须做 / 绝不做 / 先问。
  5. 已确认的语言政策——参见语言政策。
  6. 项目约定——Agent 无法仅凭代码推断的决策。
  7. 深入文档链接——指向 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 会毫不怀疑地照做,并做出没人要求的改动。