问题不是文档不够多
大多数团队在交接时的第一反应是”补文档”。补完之后发现新人还是跑不起来，因为文档记录的是”做了什么”，缺少的是”为什么这样做”和”遇到新情况怎么判断”。
知识外化不是写更多文档，而是把判断力从人脑转移到系统。这需要三个层次的动作。
第一层：让决策可以被读懂
最小代价的起点。每次做非显而易见的决定，当场写三行：
情况：为什么要做这个决定
判断：为什么选这个方案而不是其他
结论：下次类似情况的触发条件和做法
不需要专门的时间。决策发生的当下写，三行的价值比事后整理的长文档高得多——事后已经记不清当时为什么排除了其他选项。
落在哪里：PR 描述、commit message、对应的方法文档。只要有地方能找到就行，不需要统一格式。
第二层：让 Agent 和提示词有契约
每个 Agent、每个重要提示，都需要一份说明：
## 说明
- 能做什么：接收 X，产出 Y
- 不能做什么：遇到 Z 类情况必须交给人判断
- 修改历史：[日期] 改了什么，为什么改
没有这份说明，Agent 就是黑盒。只有创建它的人才敢动，新人不知道改了会不会破坏什么——结果要么不敢改，要么改出问题。
做法：在提示文件顶部加说明块，每次修改时同步更新，和改代码要更新注释是同一个逻辑。
第三层：用”新人测试”暴露盲点
文档写完，创建者往往觉得”应该够了”。但创建者有盲点——他觉得是常识的东西，新人完全不知道。
做法：定期让一个不熟悉此模块的人，只靠文档和系统，独立完成一个中等复杂度的任务。
- 他卡住的地方 → 知识还没有外化
- 他问了什么问题 → 答案应该在系统里能找到
- 他做出错误判断 → 判断依据还在老人脑子里
这比自己检查文档有效得多。每次测试把暴露出来的盲点补进去，系统的可接手性就会稳步提升。
嵌入日常，不作为额外负担
三个层次如果变成”专门的文档任务”，就会没人做。有效的方式是嵌入已有的工作节点：
| 工作节点 | 附加动作 |
|---|---|
| PR 提交 | 描述里写清楚为什么这样改，而不只是改了什么 |
| Agent / 提示修改 | 更新说明块，记录改动原因 |
| 踩坑解决后 | 立刻写三行记录，落入对应文档 |
| 站会 | 问一句：这周有什么判断需要记录下来？ |
不增加新流程，只是在现有节点上多一件小事。
判断做没做到位
核心指标：新人不依赖老人，能独立处理中等复杂度的任务需要多长时间？
| 情况 | 说明 |
|---|---|
| 需要老人陪跑一个月以上 | 知识还在人身上，外化没做 |
| 两周内能独立判断常见情况 | 第一、二层基本到位 |
| 一周内能开始修改 Agent 和提示 | 三层都到位，系统成熟 |
定期用这个指标检验，而不是靠感觉判断”我们的文档应该够了”。
与知识积累的关系
知识外化解决的是传递问题——让已有的判断力可以被新人使用。
知识积累解决的是生成问题——让项目中产生的新判断力不流失。
两者都需要，缺一个体系就不完整：只积累不外化，知识堆在仓库里没人用；只外化不积累，系统越来越落后于项目实际状态。
→ 知识积累的具体做法见 knowledge-into-experience.md