【虎鲸进化论 15】上下文工程：长周期项目的接力
本文是「虎鲸进化论」系列第 16 篇（正文第 15 篇）。上一篇：代码理解；下一篇预告：故障诊断① ------ 从单号到行号。
前言
上一篇的结尾说：读一次容易，读一个几周的项目难 ------ 上下文会淹死它。
这篇讲它怎么学会"不淹死"。先亮一个反直觉的结论：长周期任务的第一瓶颈从来不是模型智力，是上下文管理。 换句话说，这个篇目讲的不是"它更聪明了"，而是"它学会整理书桌了"。
（照例：内网细节无截图；机制与细节做模糊化处理。）
一、先看看"淹死"长什么样
上下文淹死，在工程上有三种死法（这三种我们都见过）：
死法一：忘光重来。 会话一断，之前读的一切归零。第二天它又是一个新员工，你昨天陪它读的两小时代码，白读。
死法二：读嗨了撑爆。 一个任务里疯狂读取 ------ 代码、日志、表结构一起塞 ------ 上下文塞满之后，越是关键的信息越容易被后来的垃圾挤出去，它开始丢掉亲手读出来的重要结论。
死法三：无效堆料。 为了避免忘，就什么都留着、什么都带上 ------ 每次任务背着几百页"行李"开工。结果不是记得更多，而是注意力被稀释 ------ 它开始对什么都"似曾相识"，却什么都抓不住重点。（像极了周一早会上听上周五自己讲过的方案 ------ 每个字都熟，就是接不上。）
三种死法的共同根因：把上下文当成了"仓库"，而它其实是"工作台"。
工作台只能放当下要用的工具；仓库放在另一处，用时去取。
二、分层：什么进上下文，什么留索引
想通"工作台 vs 仓库"，设计就顺了。我们后来把它所有可读的东西分成了三层：
| 层 | 内容 | 放哪 | 什么时候进上下文 |
|---|---|---|---|
| 热 | 当前任务相关资料 | 会话内 | 一直都在 |
| 温 | 项目知识库（索引、结论、口径、证据位置） | 知识库 | 按需检索，用一次取一次 |
| 冷 | 全量代码、历史日志、归档数据 | 原地 | 只通过工具"现查现用"，永不整体搬入 |
这个设计里最妙的一条是"冷层永不整体搬入"：全量代码永远待在原地，需要哪段查哪段 ------ 工具负责"取",检索负责"找",它自己永远只握着"答案"和"答案的位置"，而不是"图书馆"本身。
再说一遍第 06 篇那句话，到这一篇它终于露出完整的牙齿：索引的质量决定它的上限。 温层的检索质量高，"工作台"就永远只有当下必需品；检索质量差，它就只能一遍遍把仓库往桌上搬 ------ 然后淹死。
三、跨会话接力：写交接文档给自己
分层解决了"单次任务不淹死"，但"跨会话记得住"是另一个问题。
会话终究会断（工程限制、成本限制、人类睡觉）。断点重启之后，怎么让新的它接上旧的它？答案朴素得让人想笑：写交接文档 ------ 写给它自己的交接文档。
实际做法是"两层自动 + 一层人工"：进度摘要 由它自动生成 ------ 结构化四段（状态 / 决定 / 坑 / 悬案），落在仓库的固定目录里，而且有一条硬限制：写短。 超过一屏的交接文档，下一个它也会偷懒不读。关键决定 分层处理：普通决定自动归档；会改变路线的重大决定，由人过目后加一枚"已确认"标记 ------ 机器接力可以自动，路线不许自动。
这份"给自己的交接文档"，我们后来约定必须包含四样东西：
- 任务状态：做到哪了、下一步是什么；
- 关键决定 ：为什么选 A 不选 B（这一条最重要 ------ 决定是"上下文"里最容易蒸发、又最贵的东西）；
- 踩过的坑：试过什么、为什么不行（省得下一个它重复翻车）；
- 悬而未决：哪些结论还没验证、哪些口径还没定。
有个细节很值得玩味：它写交接文档时，假定的读者不是人，是"下一个它"。 所以文档的写法也在进化 ------ 从"给人看的作文"变成"给机器查的坐标"：短句、结构化、每个结论带证据位置、每个状态可执行。
（这和人类工作里的交接文档形成了残酷对比：人写的交接文档经常连人名都懒得改；它写的交接文档，下一班岗真的会照着干。顺便：人类的交接文档里有一句话是它写不出来的 ------ "有问题找 XX"。因为"找 XX"这件事，是个社会关系，不是一条链接。）
四、文档组织：一半给人，一半给机器
到这一步，文档在这个组里的性质彻底变了：
- 以前：文档是"给人看的" ------ 产出是给人读的，人走了文档就死了；
- 现在：文档是"任务的脚手架" ------ 一半给人读（审查、追溯），一半给机器查（接力、检索）。
两种读者的需求不一样，我们索性分开写：
- 给人看的部分：结论、理由、风险（要能通读）；
- 给机器查的部分：进度、坐标、待办（要能被检索、被续写）。
我们组的文档体系后来固化成了三件套：任务书 （要做什么、验收是什么）、进度页 （给机器接力：状态/决定/坑/悬案四段）、坑清单（共用一本，谁踩谁记）。名字都很土 ------ 但土名字有个好处：没人会疑惑"这个文档是干嘛的"。
五、腐坏问题在项目级重演
第 06 篇讲知识资产时说过：会腐坏。上下文工程把这个问题放大了一级 ------ 项目文档腐坏得比知识索引更快：任务在跑、决定在变、坑在增多，文档一天不更新就开始骗人。
我们的解法还是那一招，只是用得更狠了：让维护变成它的自己的例行公事。
它每晚收工时更新的不只是代码，还有那几份文档 ------ 这已经不是"我们要求"的流程，而是它自己排进夜间任务队列的固定项（理由也朴素：下一个接手的还是它自己，没人想给自己挖坑）。我们做的事只有一件：最初立了格式，之后偶尔抽查格式有没有跑偏。
顺带说一个反直觉的现象：文档腐坏对机器比对人类更危险。 人会怀疑文档（"这里写的可能过时了"）；机器不怀疑 ------ 它会拿着过期文档当最新事实去行动。（人性在懒这件事上救了人类：我们不去查，所以也就不会被坑 ------ 这个逻辑反过来也成立，只是不值得炫耀。）
结语（回味点）
分层解决了健忘，接力解决了断线 ------ 到这里，它可以"读长"了。
但它读的这一切，一直在"平时"。文档、索引、日志 ------ 都是"安静状态下"的世界。
而真正最痛的活，从来不在安静状态里。它在线上、在凌晨、在单号炸开的那一刻。
该把最痛的活交给它了：线上故障。
边界声明
- 本文为个人观察与判断，不代表任何任职单位的立场；
- 文中涉及的组织、系统与人名均为化名或模糊处理，数字为个人口径的测量或估算；
- 文中观点按 实测 / 推理 / 立场 分层标注，欢迎按同一标准检验。
下一篇计划聊：故障诊断① ------ 从单号到行号：一个单号进来，要走过哪五步，才能站在代码面前。
转载请注明出处：