📚 编程进阶教程站

第 30 章 · AGENTS.md 标准：给智能体的 README ​

本章目标：理解 AGENTS.md 开放标准的定位与设计哲学，掌握典型内容结构与 monorepo 嵌套规则，学会为项目编写一份高质量的智能体说明书。

23.1 AGENTS.md 是什么 ​

AGENTS.md 是一个简单、开放的格式标准，用于指导编码智能体（coding agent）在你的项目中工作。官方的定义非常精辟：

Think of AGENTS.md as a README for agents——把它当作给智能体看的 README。

它由 OpenAI Codex、Amp、Google Jules、Cursor、Factory 等团队协作发起，目前由 Linux Foundation 旗下的 Agentic AI Foundation 托管，已被 60,000+ 开源项目采用。仓库地址：agentsmd/agents.md。

text
README.md   → 写给人类：快速上手、项目介绍、贡献指南
AGENTS.md   → 写给智能体：构建步骤、测试命令、代码约定等机器执行所需的上下文

为什么要分成两个文件？因为两者受众不同：

  • 给人类的信息讲究简洁聚焦，细节多了没人读；
  • 智能体需要的是精确、可执行的指令——构建命令、测试方式、代码风格，这些写进 README 会把它变得臃肿；
  • 分离之后，智能体有了一个明确、可预测的指令入口，不必去猜该读哪个文档。

一个文件，全生态通用

AGENTS.md 的设计初衷就是避免又造一个私有格式：同一份文件可以被 Codex、Jules、goose、opencode、Zed、Devin、Cursor、Gemini CLI、GitHub Copilot 编码智能体、Windsurf 等几十种工具直接读取。

23.2 典型内容与格式约定 ​

AGENTS.md 就是纯 Markdown，没有强制 schema、没有必需字段——智能体只是解析你写的文本。官方建议覆盖这些高频主题：

常用小节内容示例
Project overview一句话说明项目是干什么的
Build and test commands安装依赖、启动开发服务器、跑测试的确切命令
Code style guidelines格式化规则、语言特性偏好
Testing instructionsCI 计划位置、如何只跑某个测试
Security considerations密钥管理、敏感目录
PR instructions提交信息格式、提交前检查清单

下面是一份真实风格的示例（改写自官方样例）：

markdown
# Sample AGENTS.md

## Dev environment tips
- 用 `pnpm dlx turbo run where <project_name>` 直接跳转到对应包，
  不要用 ls 一个个翻目录。
- 新增包时用 `pnpm install --filter <project_name>`，
  这样 Vite / ESLint / TypeScript 才能看到它。

## Testing instructions
- CI 计划在 .github/workflows 目录里。
- 在包根目录直接运行 `pnpm test`；合并前必须全绿。
- 移动文件或修改 import 后，补跑 `pnpm lint --filter <project_name>`。

## PR instructions
- 标题格式：[<project_name>] <标题>
- 提交前必须先跑 `pnpm lint` 和 `pnpm test`。

注意这些指令的共性：可执行、可验证。官网 FAQ 明确说明——只要你在文件里列出了测试命令，智能体会真的去执行它们，并在结束前尝试修复失败。所以写"跑 pnpm test"远比写"请确保质量"有效。

23.3 嵌套与优先级规则 ​

大型 monorepo 可以在子目录里放更多 AGENTS.md：

text
my-monorepo/
├── AGENTS.md                  # 根级：全仓通用的约定
├── apps/
│   └── web/
│       └── AGENTS.md          # 前端子项目专属约定
└── services/
    └── api/
        └── AGENTS.md          # 后端子项目专属约定

两条核心规则（来自官方 FAQ）：

  1. 就近优先：智能体编辑某个文件时，会自动读取目录树上离它最近的 AGENTS.md，越近的优先级越高。所以每个子项目都能给出定制化指令——OpenAI 自己的主仓库在撰写本文时有 88 个 AGENTS.md 文件；
  2. 对话优先：如果指令冲突，用户在聊天中的显式提示覆盖一切，其次才是最近的 AGENTS.md。
text
优先级（高 → 低）：
用户当前对话的显式要求  >  最近的 AGENTS.md  >  更上层的 AGENTS.md

23.4 生态支持与同类约定 ​

主流编码智能体对 AGENTS.md 的支持已经非常广泛：OpenAI Codex、Google Jules、Factory、Aider、goose、opencode、Zed、Warp、VS Code、Devin（Cognition）、Cursor、RooCode、Gemini CLI、GitHub Copilot 编码智能体、Windsurf 等。

两个实用的兼容性细节：

  • Claude Code 使用同类约定的 CLAUDE.md（内容思路一致）；很多项目直接让其中一个软链到另一个，或内容保持同步；
  • 部分工具需要一行配置开启支持，例如 Aider 和 Gemini CLI：
yaml
# .aider.conf.yml —— 让 Aider 读取 AGENTS.md
read: AGENTS.md
json
// .gemini/settings.json —— 让 Gemini CLI 使用 AGENTS.md 作为上下文文件
{
  "context": {
    "fileName": "AGENTS.md"
  }
}

已有旧文件要迁移？官方给的命令是一行重命名加软链回退：

bash
mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

23.5 与 Skills 的分工：常驻上下文 vs 按需能力 ​

学完第 16 章的 Agent Skills 后，一个自然的问题是：AGENTS.md 和 SKILL.md 有什么区别？什么时候用哪个？

维度AGENTS.mdSkill（SKILL.md）
加载时机会话开始时常驻上下文任务匹配时才按需加载（渐进披露）
定位项目级约定与事实可复用的能力包（工作流+脚本+资源）
规模保持精简，几十行以内可以很长，还能携带脚本和参考文档
作用域一个仓库/目录跟随技能目录分发，可跨项目复用

一句话记忆：AGENTS.md 告诉智能体"这个项目的规矩是什么"，Skill 告诉它"做这类事情的标准作业程序"。两者是互补而非替代关系——第 19 章你会看到 Loop Engineering 把它们一起纳入循环的积木。

23.6 编写最佳实践 ​

结合官方示例仓库中 60k+ 项目的实战经验，总结五条原则：

  1. 可执行命令优先：写确切的命令行（pnpm test），而不是抽象要求（"保证测试通过"）；
  2. 精简：它是常驻上下文，每一行都消耗 token。与 README 重复的内容删掉，只留智能体需要的增量信息；
  3. 写"新人须知"：判断标准很简单——凡是你会交代给第一天入职新同事的事项，都属于这里；
  4. 当作活文档：约定变了就更新它，过时的指令比没有指令更糟；
  5. monorepo 用嵌套：把包级别的特殊约定下沉到子目录，别在根文件里堆成百宝箱。

本章小结 ​

  • AGENTS.md 是开放标准："给智能体看的 README"，60k+ 项目采用，Linux Foundation 托管；
  • 纯 Markdown、无强制 schema，常用小节：构建/测试命令、代码风格、PR 规范、安全注意事项；
  • monorepo 支持嵌套，就近优先；用户对话中的显式指令覆盖一切；
  • 与 Skills 分工：AGENTS.md 是常驻的项目约定，Skills 是按需加载的能力包；
  • 最佳实践：可执行命令优先、精简不重复、当作活文档。

🛠️ 动手实践 ​

完成后进入下一章：综合实战：五件套打通完整工作流。