写给 AI 的入职手册，AGENTS.md
一个尴尬的故事
OpenAI的驭缰工程团队，也犯过一个很多人都会犯的错。
他们写了一个超大的AGENTS.md——把所有能想到的规范、约束、架构说明全塞了进去。大家心里想的是：信息越全，智能体表现越好，对吧？
结果惨败。问题出在四个地方：
最终的结论是：给智能体一张地图，而不是一本百科全书。
AGENTS.md的本质是什么？
AGENTS.md的定位很明确：给AI智能体的入职手册，一张地图，不是百科全书。
它要解决的核心问题：一个全新的智能体，对你的代码库一无所知，怎么在100行以内快速“上岗”？
上限：60-100行
多个独立来源指向同一个数字：
| 来源 | 实践 |
|---|---|
| OpenAI 实战 | ~100 行 |
| HumanLayer | ≤60 行 |
| deusyu 学习指南 | “小入口点，渐进式披露” |
为什么不能长？
因为上下文窗口是个稀缺资源。你的AGENTS.md越长，智能体用来理解实际任务和代码的空间就越小。这不是什么“尽量简洁”的审美偏好——这是硬约束。
HumanLayer的实践是把AGENTS.md压缩到60行以内。ETH Zurich的研究也证实了精简的价值：指令过多反而损害性能，Agent会多花14-22%的推理token，但解决率却没有提升。
怎么写？一个实用的模板
#AGENTS.md-项目导航
##这是什么
[一句话描述项目：它是做什么的、给谁用的、技术栈是什么]
##仓库结构
[关键目录和它们的职责，不超过10行]
##核心架构规则
[最重要的3-5条硬性约束。不是所有规范，是最容易违反的那几条]
##开发流程
[怎么跑测试、怎么提交、怎么部署。指向具体脚本/文档]
##代码规范
[指向lint配置、命名约定文档。不要在这里重复写]
##常见任务
[常见开发任务的入口——“加一个新API”、“修一个bug”、“加一个新页面”分别怎么开始]
##更多细节
[指向更深层的文档：docs/ARCHITECTURE.md、docs/CONTRIBUTING.md等]核心思路是“指向”，而不是“包含”。
六个写好AGENTS.md的实战技巧
1. 当目录用，不当百科用
❌坏：在AGENTS.md里写50行的架构说明
✅好：写3行概述+指向docs/ARCHITECTURE.md智能体自己能读文件，你不需要把所有信息都塞进AGENTS.md——你只需要告诉它文件在哪里，它自己会去读。
2. 写规则，不写建议
❌坏：“建议使用共享工具函数”
✅好：“禁止手写辅助函数，使用src/utils/（见Lint规则custom/no-handmade-helpers）”规则可以被机械执行，建议只能被“尽量遵守”。
3. 把“为什么”也写上
❌坏：“所有API边界必须用Zod验证”
✅好：“所有API边界必须用Zod验证（原因：智能体无法从运行时行为推断数据形状，见docs/why-zod.md）”智能体比人类更死板，也更遵守规则——尤其是当你告诉它“为什么”的时候。它能更好地在边界情况下做推理。
4. 指向可执行的约束
❌坏：“代码要有良好的日志”
✅好：“使用结构化日志（Lint：custom/structured-logging。错误信息中嵌入修复指令）”如果有一条lint规则已经在检查这个了，直接指向它。不要让智能体自己去猜什么是“良好的日志”。
5. 渐进式披露
AGENTS.md(100行入口) → docs/ARCHITECTURE.md（架构详情）→ docs/domains/PAYMENTS.md（特定域的规范）→ inline code comments（具体实现的上下文）每一层更具体，但不一次性全展示出来。就像你带新人，先给个总览，再慢慢深入。
6. 用智能体维护AGENTS.md本身
OpenAI的做法是：一个定期运行的“doc-gardening”智能体，扫描过时或废弃的文档，自动发起修复PR。
AGENTS.md也需要“垃圾回收”。规则过时了就要删，新的约束要加上。这个过程最好自动化。
三种规模的AGENTS.md
个人项目（10-30行）
#AGENTS.md
这是一个[什么]项目，用[技术栈]。
- 跑测试：npm test
- 跑开发：npm run dev
- 代码风格：eslint+prettier（已配置）
- 架构：src/下按功能分目录，每个模块自包含
- 禁止：不要用any类型，不要跳过测试
- 更多：见README.md团队项目（60-100行）
按上面的完整模板写。重点是：
- 清晰的仓库结构
- 最容易违反的3-5条硬约束
- 常见任务的入口
- 指向深层文档的链接
企业级项目（100行+配套文档体系）
AGENTS.md仍然是100行，但配套建设：
docs/ARCHITECTURE.md- 架构约束和分层规则docs/QUALITY_SCORE.md- 每个域的质量评分- 自定义linter规则（把AGENTS.md里的约束变成可执行的检查）
- doc-gardening自动化
一个关键数据：AI自动生成的AGENTS.md反而有害
ETH Zurich研究了138个agentfile（包括AI生成的和人工写的），发现了一个有意思的现象：
- LLM自动生成的agentfile，实际损害性能，成本增加20%+
- 人工编写的，也只帮助了约4%
- Agent多花14-22%的推理token处理自动生成的指令，但解决率没提升
- 代码库概览和目录列表毫无帮助——agent自己就能发现仓库结构
这条数据意味着：AGENTS.md必须人工精心编写。简短、精准、只写agent自己发现不了的关键约束。
HumanLayer的建议更直接：不要一次性写完。
检查清单
写完了？用这个清单自查一下：
- [ ] 不超过100行？
- [ ] 一句话说清了项目是什么？
- [ ] 仓库结构一目了然？
- [ ] 最重要的3-5条硬约束明确写出来了？
- [ ] 指向了更深层的文档？
- [ ] 常见任务有入口指引？
- [ ] 规则指向了对应的lint/CI检查？
- [ ] 有“为什么”的解释？
- [ ] 有定期维护的机制？
写在最后
AGENTS.md是驭缰工程里杠杆率最高的单个文件。
100行就能左右智能体每天的工作方式——值得你认真对待。
这不是一次性的工作，而是持续的投资。
