先看出事的那一刻
2026 年 7 月 28 日，E2E Review 的一次工作会话里，后端要连数据库，可这台电脑上的数据库没起来。AI 先起了一个只读内容的模拟接口顶上，用 nohup 放进了后台。
当天，它在发给站长的优先级清单里写了一条：
现在 8787 端口跑的是我 scratchpad 里的临时 bun 脚本——会话目录被清或机器重启它就没了……要么回归正式的 server/index.mjs，要么把 mock 脚本正式入库并写进 launch.json。发布前必须二选一。
这条待办只说在了聊天里。两天后，这个会话第一次被压缩成摘要，摘要里没有它；同一天，接手的 Codex 写下了项目的第一份状态文档，里面也没有它。再往后的每一版状态文档，直到两个月后出事，都没有它。
两个月后：
第 2 课从"本地和线上"讲过这个进程是怎么骗过检查的。这节课看另一件事：那条待办，从来没有离开过聊天窗口。会话被压缩、活换给了另一个 AI，它就没了；机器上的那个进程，却一直都在。
这节课要回答的是：AI 的工作台装不下、会话会结束、活会交给别的 AI。要让下一个接手的知道什么？写在哪里？
装备几个词
为什么要懂
AI 替你做了
AI 在一个会话里能连续干好几个小时：读代码、改文件、记住你一路说过的要求。
留给你的
会话会被压缩、会结束、会换成另一个 AI。哪些要写进文件、写进哪一份、交接时交代什么，要你来定。
不懂的代价
聊天里说过的事，换个会话就不存在了。最危险的不是忘了需求，而是忘了机器上还留着什么。
工作台为什么会装不下
AI 一次能摆在面前的内容是有限的：整段对话、读过的文件、你给的要求，都挤在同一个上下文窗口里。对话长到快装不下时，工具会把前面的部分压缩成一页摘要，接着往下做。
摘要留下的是大方向，丢掉的是细节。写这门课的这个会话，从 7 月一直用到现在，到写这节课时被压缩过 4 次。7 月 30 日的第一次压缩，就把"后台还跑着一个模拟接口"丢了。
摘要里留下什么，你决定不了；但你可以决定，什么不靠摘要。
按"谁会读"放进不同的文件
| 放在哪 | 写什么 | 谁会读 | 本站的例子 |
|---|---|---|---|
| 规则文件 | 长期有效的约定、禁区、常用命令 | 每个新会话开工时自动读 | .claude/CLAUDE.md：每个文件夹一份三行以内的说明，每个文件开头三行注释 |
| 方案与交接文档 | 这件事的目标、已确认的决定和理由、进度、没做完的 | 接手这件事的会话或人，开工先读 | docs/vibecoding-plan.md；自动驾驶的活交给新会话时，交代里的头一件事，就是"先完整读 docs/e2e-plan.md" |
| 提交记录 | 每一步改了什么、为什么、依据在哪 | 以后追查的人 | 第 7 篇的每个提交说明里，都写了事实的出处 |
方案文档写好之后，还要一直往里写。自动驾驶那个会话做着做着，在方案里加了一节"执行记录与写法约定"，连"素材笔记里已知的几处误读"都记了进去；后面任何一个会话接手，都不用再踩一遍。这门课也一样：每次压缩之后，都是照着方案文档接着做。
写已确认的决定时，最好连理由一起写，再加一句"勿重新讨论"。知识库 Agent 的开发计划就是这么写的：下一个会话看到理由，就不会把定好的事又翻出来商量一遍。
交接要交代的五件事
- 做到哪了：完成了什么，验证过什么。
- 定下了什么，为什么：已确认的决定和理由。
- 还没做完的：下一步具体是什么。
- 机器上还留着什么：后台进程、临时服务、开着的端口、改过的本地配置。这一条最容易漏，开场的事故漏的就是它。
- 接手的人怎么验证：跑哪个命令、看哪个页面，确认现在是好的。
深潜为什么不直接把聊天记录交给下一个＋
最省事的交接，是把整段聊天导出来丢给下一个会话。不这么做，有三个原因：
- 结论埋在过程里：几十轮来回里，哪些是试过又放弃的、哪些是最后定下的，接手的人分不清；
- 它本来就装不下：长到需要交接的对话，往往正是工作台装不下的那种，整段塞回去，又会被压缩一次；
- 里面可能有不该传下去的东西：比如你曾经贴进对话的密钥（第 11 课）。
该交接的是结论和现场，不是过程。
交接文档会说谎
7 月 21 日，知识库 Agent 要交给别人维护。交接之前做了一件事：从仓库重新克隆一份，照着 README 从头走一遍。
走下来，修掉了接手的人一定会撞上的几个坑，也发现 README 里有几句已经不是真的了。提交说明里有一句话："交接文档说谎比没文档更糟。"没有文档，接手的人会去问；文档说错了，接手的人会照着做。
紧接着还有一个小改动，标题是"启动前置条件一次报全，不让接手人来回修两趟"：原来缺了配置和资料，启动时只报第一个，补好再启动，才被告知还缺第二个。
检验一份交接文档，办法只有一个：找一个没参与过的人，或者开一个新会话，只照着文档从头做一遍。让写文档的 AI 自己通读，是读不出缺了什么的：它脑子里有前情，会自动把缺口补上。
找茬
下面是知识库 Agent 交接之前的 README（节选）。从仓库重新克隆一份、照着它走一遍时，这几处都出了问题。找出接手的人会被它误导或者卡住的地方。
这段 Markdown 里埋了 4 处问题。点击你觉得有问题的行，至少找出 3 处再揭晓。
·第 2 行低危
写的是几个小时前就改掉了的样子
衬线字体几个小时前就删了，"常驻原文对照"也早改成了点出处才出现。界面改了，README 没跟着改。接手的人照着它找东西、改样式，会以为自己看错了。
该问的话：README 里描述的界面和功能，和现在的代码对得上吗？最近几次改动之后更新过吗？
·第 5 行中危
装前端依赖，藏在一行注释里
前端要另装一次依赖，可这一步只在
npm install那行的注释里提了一句，实测很容易漏。交接时改成了装完后端自动装前端，不再靠人看注释。该问的话：照着快速开始一条条执行，能不能把整个项目跑起来？有没有哪一步只写在注释里？
·第 7 行高危
同步资料要去作者的电脑上拿
资料的来源路径写在配置里，指向作者本机的一个目录，换一台电脑就不存在。更糟的是，这个同步脚本是"镜像"式的：会把直接放进资料目录、来源里没有的文件删掉。交接时删掉了这个脚本，改成文档直接放进资料目录。
该问的话：这个命令依赖哪些只有你的电脑上才有的东西？它会不会删掉接手的人自己放进去的文件？
·第 11 行中危
"10/10"已经不是真的
最近一次实测，负样本是 9/10；而且审计发现 10 道负样本里有 6 道的主题其实在资料里，测的根本不是"会不会拒答"，结果会来回跳（第 25 课）。交接时改成写明：这批题换了资料就作废，要重写。
该问的话：文档里的这些数字，是哪一次、在什么条件下测的？现在再跑一遍还是这样吗？
查看代码与答案（4 处问题）
1 # 知识库 Agent 的 README（交接之前，7 月 21 日，节选，略有简化）
2 视觉方向「学术印刷」：暖纸底 + 陶土重音 + 衬线西文；三栏阅读器（会话 / 问答 / 常驻原文对照）。
3
4 ## 快速开始
5 npm install # 根：后端 + SDK；再 npm --prefix web install 装前端
6 cp .env.example .env # 填入模型端点与 key
7 npm run sync-corpus # 从 kb.config.yaml 的 corpus_source 同步 md/txt 到 corpus/
8 npm run dev # 同时起后端(3100) + 前端(5173)
9
10 ## 测试
11 评测 eval/cases.yaml 25 条（正 15 / 负 10）。当前达标：正样本 15/15，负样本 10/10。换模型后必跑回归。- 第 2 行 · 低危 · 写的是几个小时前就改掉了的样子：衬线字体几个小时前就删了，"常驻原文对照"也早改成了点出处才出现。界面改了，README 没跟着改。接手的人照着它找东西、改样式，会以为自己看错了。 该问的话：README 里描述的界面和功能，和现在的代码对得上吗？最近几次改动之后更新过吗？
- 第 5 行 · 中危 · 装前端依赖，藏在一行注释里：前端要另装一次依赖，可这一步只在
npm install那行的注释里提了一句，实测很容易漏。交接时改成了装完后端自动装前端，不再靠人看注释。 该问的话：照着快速开始一条条执行，能不能把整个项目跑起来？有没有哪一步只写在注释里？ - 第 7 行 · 高危 · 同步资料要去作者的电脑上拿：资料的来源路径写在配置里，指向作者本机的一个目录，换一台电脑就不存在。更糟的是，这个同步脚本是"镜像"式的：会把直接放进资料目录、来源里没有的文件删掉。交接时删掉了这个脚本，改成文档直接放进资料目录。 该问的话：这个命令依赖哪些只有你的电脑上才有的东西？它会不会删掉接手的人自己放进去的文件？
- 第 11 行 · 中危 · "10/10"已经不是真的：最近一次实测，负样本是 9/10；而且审计发现 10 道负样本里有 6 道的主题其实在资料里，测的根本不是"会不会拒答"，结果会来回跳（第 25 课）。交接时改成写明：这批题换了资料就作废，要重写。 该问的话：文档里的这些数字，是哪一次、在什么条件下测的？现在再跑一遍还是这样吗？
快测
1. 你和 AI 聊了一下午，定下了好几条规矩。明天要开新会话接着做。最稳的做法是？
你可能是这么想的：结论埋在来回的讨论里，而且一整段又长又杂，塞回去还会再被压缩一次。该交的是结论。
你可能是这么想的：会话越长越会被压缩，压缩时丢的正是细节。开场那条待办，就丢在第一次压缩里。
对了。文件不会被压缩。长期的约定进规则文件，这件事的进度进方案文档，新会话开工先读。
要留下来的，写进文件；不靠摘要，也不靠聊天记录。
查看选项与答案
- A. 把今天的聊天记录整段导出来，明天贴给新会话——结论埋在来回的讨论里，而且一整段又长又杂，塞回去还会再被压缩一次。该交的是结论。
- B. 明天接着用今天这个会话，前面说过的它都记得——会话越长越会被压缩，压缩时丢的正是细节。开场那条待办，就丢在第一次压缩里。
- C. 让它把规矩和进度写进项目里的文件，明天先读（正确）——文件不会被压缩。长期的约定进规则文件，这件事的进度进方案文档，新会话开工先读。
要留下来的，写进文件；不靠摘要，也不靠聊天记录。
2. 交接时，最容易漏掉、又最容易出事的是哪一类？
你可能是这么想的：这些通常写得最全，接手的人也最先问。
你可能是这么想的：这些写在代码和注释里，接手的人自己读得到。
对了。它们不在代码里，也不在聊天之外的任何地方。开场那个模拟接口，就这样在后台跑了两个月。
交接不只交代码，还要交现场。
查看选项与答案
- A. 项目的目标、背景和用户是谁之类的介绍——这些通常写得最全，接手的人也最先问。
- B. 代码里每个函数是做什么的、参数怎么用——这些写在代码和注释里，接手的人自己读得到。
- C. 机器上还留着的东西：后台进程、端口、本地配置（正确）——它们不在代码里，也不在聊天之外的任何地方。开场那个模拟接口，就这样在后台跑了两个月。
交接不只交代码，还要交现场。
3. 怎么检验一份交接文档写得够不够？
你可能是这么想的：写得再长，说错了也没用：README 里那句"10/10"，就写在一份很完整的文档里。
对了。知识库 Agent 交接前就是这么做的：重新克隆一份，照着 README 走一遍，才发现了那几处坑和不实的地方。
你可能是这么想的：它脑子里有前情，读的时候会自动把缺口补上，读不出缺了什么。
没参与过的人照着做一遍，是检验交接文档的唯一办法。
查看选项与答案
- A. 看文档够不够详细，章节有没有齐全——写得再长，说错了也没用：README 里那句"10/10"，就写在一份很完整的文档里。
- B. 开一个新会话，只给它这份文档，从头做一遍（正确）——知识库 Agent 交接前就是这么做的：重新克隆一份，照着 README 走一遍，才发现了那几处坑和不实的地方。
- C. 让写文档的 AI 自己通读一遍，确认没有遗漏——它脑子里有前情，读的时候会自动把缺口补上，读不出缺了什么。
没参与过的人照着做一遍，是检验交接文档的唯一办法。
判断时刻
一个功能做了一半，你要换一个 AI 工具接着做，比如从 Codex 换到 Claude Code。
你会怎么交接？
考察：最省事，丢得最多
代码里有做了什么，没有为什么、不要什么、还差什么。它会按自己的理解补全，正是第 21 课里配图变黑块的那种接力。
考察：多花十分钟，最稳
五件事都交代了，新工具不用猜。代价是要花时间写，还要核对它写的是不是真的：交接文档说谎，比没有更糟。
考察：看起来最全
信息都在，可结论埋在过程里，新工具分不清哪些是试过又放弃的；记录里还可能有你贴过的密钥。
交接的不是聊天记录，而是结论和现场：定了什么、做到哪、机器上还留着什么。写进文件，再开一个新会话照着走一遍。
三个选项各自的代价
- A. 直接让新工具读代码，自己看懂再接着做——考察最省事，丢得最多：代码里有做了什么，没有为什么、不要什么、还差什么。它会按自己的理解补全，正是第 21 课里配图变黑块的那种接力。
- B. 让旧工具写交接：做到哪、定了什么、没做完的、机器上还跑着什么、怎么验证；新工具开工先读——考察多花十分钟，最稳：五件事都交代了，新工具不用猜。代价是要花时间写，还要核对它写的是不是真的：交接文档说谎，比没有更糟。
- C. 把两边的聊天记录都导出来，交给新工具——考察看起来最全：信息都在，可结论埋在过程里，新工具分不清哪些是试过又放弃的；记录里还可能有你贴过的密钥。
交接的不是聊天记录，而是结论和现场：定了什么、做到哪、机器上还留着什么。写进文件，再开一个新会话照着走一遍。
带走
下次让 AI 做这件事时，问它
- 这次对话里定下的决定和理由，整理进方案文档；长期有效的约定，写进规则文件。
- 收工前写一份交接：做到哪了、定了什么、还没做完的、机器上还留着什么、接手的人怎么验证。
- 你在这台机器上启动过哪些后台进程、临时服务，改过哪些本地配置？全部列出来，说明要不要保留。
- 交接文档里的每一句，现在还是真的吗？和代码、和最近一次的测试结果对一遍。
自己验证
- 开一个新会话，只给它交接文档，看它能不能不问你就接着干。
- 在一个干净的目录里重新克隆一份，只照着说明文档从头走一遍。
- 收工前看一眼本机开着的端口和后台进程，确认每一个都有着落。
聊天里说过的，换个会话就没了。要留下来的，写进文件。