写给 AI 的入职手册，AGENTS.md

一个尴尬的故事

OpenAI的驭缰工程团队，也犯过一个很多人都会犯的错。

他们写了一个超大的AGENTS.md——把所有能想到的规范、约束、架构说明全塞了进去。大家心里想的是：信息越全，智能体表现越好，对吧？

结果惨败。问题出在四个地方：

最终的结论是：给智能体一张地图，而不是一本百科全书。

AGENTS.md的本质是什么？

AGENTS.md的定位很明确：给AI智能体的入职手册，一张地图，不是百科全书。

它要解决的核心问题：一个全新的智能体，对你的代码库一无所知，怎么在100行以内快速“上岗”？

上限：60-100行

多个独立来源指向同一个数字：

为什么不能长？

因为上下文窗口是个稀缺资源。你的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行就能左右智能体每天的工作方式——值得你认真对待。

这不是一次性的工作，而是持续的投资。