你的新同事每天入职，每天离职。他不记得昨天做了什么，不认识你的代码库，不知道你的规矩。你只有 100 行来让他上手。
一个尴尬的故事
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，解决率却没有提升。
怎么写？一个实用的模板
bash
# AGENTS.md - 项目导航
## 这是什么
[一句话描述项目：它是做什么的、给谁用的、技术栈是什么]
## 仓库结构
[关键目录和它们的职责。不超过 10 行]
## 核心架构规则
[最重要的 3-5 条硬性约束。不是所有规范，是最容易违反的那几条]
## 开发流程
[怎么跑测试、怎么提交、怎么部署。指向具体脚本/文档]
## 代码规范
[指向 lint 配置、命名约定文档。不要在这里重复写]
## 常见任务
[常见开发任务的入口------"加一个新 API"、"修一个 bug"、"加一个新页面"分别怎么开始]
## 更多细节
[指向更深层的文档：docs/ARCHITECTURE.md、docs/CONTRIBUTING.md 等]核心思路是指向。
六个写好 AGENTS.md 的实战技巧
1. 当目录用，不当百科用
bash
❌ 坏：在 AGENTS.md 里写 50 行的架构说明
✅ 好：写 3 行概述 + 指向 docs/ARCHITECTURE.md智能体可以自己读文件。你不需要把所有信息都塞进 AGENTS.md------你只需要告诉它文件在哪里。
2. 写规则，不写建议
bash
❌ 坏："建议使用共享工具函数"
✅ 好："禁止手写辅助函数，使用 src/utils/（见 Lint 规则 custom/no-handmade-helpers）"规则可以被机械执行。建议只能被"尽量遵守"。
3. 把"为什么"也写上
bash
❌ 坏："所有 API 边界必须用 Zod 验证"
✅ 好："所有 API 边界必须用 Zod 验证（原因：智能体无法从运行时行为推断数据形状，见 docs/why-zod.md）"智能体比人类更遵守规则------如果你告诉它为什么。它能更好地在边界情况下做推理。
4. 指向可执行的约束
bash
❌ 坏："代码要有良好的日志"
✅ 好："使用结构化日志（Lint：custom/structured-logging。错误信息中嵌入修复指令）"如果有一条 lint 规则已经在检查这个了，指向它。
5. 渐进式披露
bash
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 行）
bash
# 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 的建议更直接：
"与其祈祷 gpt-6.4-codex-ultrahigh_extended 来拯救我们，不如专注于如何从今天的模型中获得最大价值。"
不要一次性写完
检查清单
你的 AGENTS.md 写完了？用这个清单自查：
- 不超过 100 行？
- 一句话说清了项目是什么？
- 仓库结构一目了然？
- 最重要的 3-5 条硬约束明确写出来了？
- 指向了更深层的文档？
- 常见任务有入口指引？
- 规则指向了对应的 lint/CI 检查？
- 有"为什么"的解释？
- 有定期维护的机制？
写在最后
AGENTS.md 是驭缰工程里杠杆率最高的单个文件。
100 行就能左右智能体每天的工作方式------值得你认真对待。
这不是一次性的工作。
觉得有用？转发给你身边正在用 AI 写代码的朋友。关注「赛博虾条」，驭缰工程系列持续更新。
这是驭缰工程系列的第二篇。上一篇：《3 个人，100 万行代码，一行都没人写：OpenAI 的 Harness Engineering 实验》 下一篇：《用 Linter 驾驭 AI：机械化执行的艺术》