> For the complete documentation index, see [llms.txt](https://zhouhao4221.gitbook.io/haiqing-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zhouhao4221.gitbook.io/haiqing-docs/05-workflow/knowledge-transfer.md).

# 知识外化实践：让项目可以被任何人接手

## 问题不是文档不够多

大多数团队在交接时的第一反应是"补文档"。补完之后发现新人还是跑不起来，因为文档记录的是"做了什么"，缺少的是"为什么这样做"和"遇到新情况怎么判断"。

知识外化不是写更多文档，而是**把判断力从人脑转移到系统**。这需要三个层次的动作。

***

## 第一层：让决策可以被读懂

最小代价的起点。每次做非显而易见的决定，当场写三行：

```
情况：为什么要做这个决定
判断：为什么选这个方案而不是其他
结论：下次类似情况的触发条件和做法
```

不需要专门的时间。决策发生的当下写，三行的价值比事后整理的长文档高得多——事后已经记不清当时为什么排除了其他选项。

**落在哪里**：PR 描述、commit message、对应的方法文档。只要有地方能找到就行，不需要统一格式。

***

## 第二层：让 Agent 和提示词有契约

每个 Agent、每个重要提示，都需要一份说明：

```markdown
## 说明
- 能做什么：接收 X，产出 Y
- 不能做什么：遇到 Z 类情况必须交给人判断
- 修改历史：[日期] 改了什么，为什么改
```

没有这份说明，Agent 就是黑盒。只有创建它的人才敢动，新人不知道改了会不会破坏什么——结果要么不敢改，要么改出问题。

**做法**：在提示文件顶部加说明块，每次修改时同步更新，和改代码要更新注释是同一个逻辑。

***

## 第三层：用"新人测试"暴露盲点

文档写完，创建者往往觉得"应该够了"。但创建者有盲点——他觉得是常识的东西，新人完全不知道。

**做法**：定期让一个不熟悉此模块的人，只靠文档和系统，独立完成一个中等复杂度的任务。

* 他卡住的地方 → 知识还没有外化
* 他问了什么问题 → 答案应该在系统里能找到
* 他做出错误判断 → 判断依据还在老人脑子里

这比自己检查文档有效得多。每次测试把暴露出来的盲点补进去，系统的可接手性就会稳步提升。

***

## 嵌入日常，不作为额外负担

三个层次如果变成"专门的文档任务"，就会没人做。有效的方式是嵌入已有的工作节点：

| 工作节点         | 附加动作                  |
| ------------ | --------------------- |
| PR 提交        | 描述里写清楚为什么这样改，而不只是改了什么 |
| Agent / 提示修改 | 更新说明块，记录改动原因          |
| 踩坑解决后        | 立刻写三行记录，落入对应文档        |
| 站会           | 问一句：这周有什么判断需要记录下来？    |

不增加新流程，只是在现有节点上多一件小事。

***

## 判断做没做到位

核心指标：**新人不依赖老人，能独立处理中等复杂度的任务需要多长时间？**

| 情况                 | 说明           |
| ------------------ | ------------ |
| 需要老人陪跑一个月以上        | 知识还在人身上，外化没做 |
| 两周内能独立判断常见情况       | 第一、二层基本到位    |
| 一周内能开始修改 Agent 和提示 | 三层都到位，系统成熟   |

定期用这个指标检验，而不是靠感觉判断"我们的文档应该够了"。

***

## 与知识积累的关系

知识外化解决的是**传递**问题——让已有的判断力可以被新人使用。

知识积累解决的是**生成**问题——让项目中产生的新判断力不流失。

两者都需要，缺一个体系就不完整：只积累不外化，知识堆在仓库里没人用；只外化不积累，系统越来越落后于项目实际状态。

→ 知识积累的具体做法见 [knowledge-into-experience.md](/haiqing-docs/01-thinking/knowledge-into-experience.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://zhouhao4221.gitbook.io/haiqing-docs/05-workflow/knowledge-transfer.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.