离职前写了 3 万字的交接文档

离开上一段工作前，我花了一段时间整理交接材料。最后汇总下来，正文接近三万字。

这个数字本身没有什么值得炫耀的。文档写得长，不代表交接做得好。真正让我反复修改的，是另一个问题：如果接手的人在两周以后遇到一个我没有预料到的线上问题，他能不能靠这些材料继续往下走？

如果答案只是“能找到某个操作步骤”，那还不够。系统不会只在文档覆盖过的场景里出问题。一个人离开团队后，真正需要留下的不是他的工作回忆，而是足够清楚的判断路径。

我当时负责和参与过多套内部数字化系统。有的是 Java 和 Spring Boot，有的是 .NET Core，有的是 Vue 前端加后端服务，有的还连着 Oracle、SQL Server、Nginx、IIS、Tomcat、ETL 任务、外部接口、证书、防火墙和定时任务。单独看每个系统都能写一份说明，但交接时最容易出问题的地方，往往出现在系统之间。

比如一个页面数据异常，原因可能不在页面；一个接口慢，可能是上游数据没有刷新；一个定时任务失败，后面可能还有报表、邮件和审批流程被影响。交接文档如果只按项目罗列，很容易让接手的人知道“有哪些系统”，却不知道“问题来了该从哪里判断”。

所以这篇文章不是记录我写了多少字，而是复盘我后来怎么把交接从“资料堆叠”改成“可接手的工程交付”。

我先把交接对象从项目换成场景

我最开始的写法很自然：按项目整理。

每个系统一章，里面放架构、技术栈、部署环境、代码仓库、数据库、接口、发布步骤、注意事项。这样做适合归档，也方便我自己补内容。但接手的人真正遇到问题时，脑子里通常不会先出现项目名。他会先遇到一个场景：

页面打不开
接口返回和页面显示不一致
定时任务没有执行
生产发布后用户反馈异常
测试环境和生产环境表现不同
某个外部系统的数据没有同步过来
证书、账号或网络权限即将过期

如果文档只有项目目录，接手者还要先猜这个问题属于哪个系统，再去翻对应章节。

后来我在项目目录之外，加了一层“场景入口”。它不替代项目说明，只负责把人带到正确的场景。

场景：生产发布
先看：
1. 当前系统使用的分支和构建方式
2. 目标环境部署方式
3. 是否涉及数据库变更
4. 是否需要停服务
5. 发布后最小验证路径
6. 失败时如何停止后续动作

再跳转：
项目 A 的发布说明
项目 B 的数据库说明
通用证书和网络权限说明

这层目录看起来只是换了一个组织方式，实际价值很大。它承认接手的人没有我脑子里的上下文，也不要求他先理解所有系统。遇到问题时，他可以从眼前的现象出发，再逐步走到具体项目。

文档不是项目回忆录

交接材料最容易写成流水账。

做过什么需求，改过哪些模块，参与过哪些系统，上过哪些版本。这些内容对自己有意义，因为自己记得前因后果；对后来的人未必有用。接手者需要的不是“我做过什么”，而是“系统现在怎么运行，以及出了问题怎么判断”。

所以我把很多时间线内容删掉了，改成稳定结构：

系统负责什么
核心用户是谁
关键链路从哪里开始，到哪里结束
依赖哪些数据库、接口、任务和服务器
哪些配置会影响生产行为
常见问题如何定位
哪些操作有风险
哪些事情还没结论

例如写一个定时任务，我不会只写“每天几点执行”。这个信息当然要有，但它不够。我会继续补：

任务名称：某类业务数据同步任务
触发方式：定时调度或接口触发
数据来源：上游业务库或外部接口
写入位置：本系统业务表
失败迹象：日志出现连接异常，目标表当天数据为空，页面统计不更新
是否可重跑：可以，但重跑前要确认当天是否已有部分数据写入
重跑前检查：上游数据是否就绪，目标表是否需要备份，是否会重复触发通知
重跑后验证：目标表记录数、更新时间、页面结果、下游报表

这种写法没有“我曾经参与过某某需求”那么有叙事感，但它更接近真实接手时需要的东西。

把“我知道”翻译成别人能验证的描述

很多交接失败，不是因为前任没有解释，而是解释停留在口头经验里。

“这个配置一般不要改。”

“这个接口偶尔会慢。”

这些话听起来像经验，实际缺少条件。为什么不要改？什么情况下会慢？为什么要避开某个时间？如果这些问题说不清，接手的人只能把它们当成禁忌。

我后来要求自己尽量把经验改成可验证的描述。比如不要只写“接口偶尔会慢”，而是写成：

如果接口响应超过 10 秒，先确认是否处于上游数据刷新时间窗口。
如果刷新任务正在执行，接口慢通常来自数据库锁等待或大查询。
先看任务日志，再看目标表更新时间。
不要第一时间重启服务，重启可能会中断正在执行的数据处理。

也不要只写“这个配置不要改”，而是写成：

该配置控制生产环境外部接口访问地址。
修改后会影响数据同步任务和页面查询。
变更前必须确认：
1. 新地址已完成网络放通
2. 账号权限已生效
3. 测试环境已完成最小链路验证
4. 生产切换窗口已通知业务方

这样写的好处是，后来的人不需要相信我。他可以自己检查条件，然后做判断。

我觉得这也是工程文档和普通说明文档的区别。普通说明文档告诉你“怎么做”，工程文档还要告诉你“为什么现在可以做，以及什么时候不能做”。

发布说明里最容易漏掉的是回退

内部系统的发布，经常不是单纯替换一个包。

有些系统要先构建后端，再替换前端资源；有些系统部署在应用服务器里，有些通过 Web 服务器代理；有些版本带数据库脚本，有些还会改定时任务、配置文件、接口地址或权限。只写“如何发布”，接手的人在顺利时能照做，一旦出错就只能临场判断。

我后来把发布流程拆成几个检查点，每个检查点都问一个反向问题。

构建前：
当前分支是否正确？
依赖版本是否和目标环境匹配？

发布前：
旧包和配置是否已经备份？
数据库是否需要快照或导出关键表？
是否存在正在执行的定时任务？

发布中：
服务停止是否符合预期？
新包替换后配置是否被覆盖？
启动日志是否出现错误？

发布后：
页面是否能打开？
核心接口是否能返回？
关键任务是否能执行？
业务方最关心的功能是否完成最小验证？

异常时：
现在应该继续、暂停还是回退？
已经执行的数据库脚本是否可逆？
如果不能回退，是否应该保留现场并通知相关人？

回退不一定意味着把所有东西退回原样。有时更安全的做法是停止后续动作、保留现场、确认数据状态，再决定下一步。这个判断如果不写在文档里，接手的人很容易被“尽快恢复”的压力推着做危险操作。

我在交接里刻意写了很多“不要急着做什么”。比如不要看到接口慢就先重启，不要看到数据为空就直接补跑，不要在没有确认备份的情况下执行修复脚本。这些句子看起来保守，但线上系统需要这种保守。

环境差异要写到不能再默认

同一个系统，开发、测试、生产可能使用不同数据库、不同服务器、不同端口、不同部署方式。更麻烦的是，有些系统在测试环境连的是模拟数据，生产环境连的是正式上游；有些任务在测试环境手动触发，生产环境由调度器触发；有些权限在测试环境放得很宽，生产环境则要走完整申请流程。

这些差异如果只写在脑子里，交接时一定会出问题。

所以我在每个系统里都单独列环境矩阵，但公开博客里只能抽象成下面这种结构：

环境：测试
用途：功能验证、发布前冒烟测试
部署方式：应用服务加前端代理
数据库：测试库
外部依赖：部分使用模拟地址
注意事项：不能直接代表生产接口权限

环境：生产
用途：真实用户访问
部署方式：应用服务加前端代理
数据库：生产库
外部依赖：正式上游接口和正式调度
注意事项：发布前确认备份、窗口和通知

这类表格不需要写得漂亮，重点是减少误会。接手的人至少能知道：他现在看到的问题，是环境差异造成的，还是系统本身真的坏了。

接口和数据流要画成链路，而不是列成清单

系统集成部分也很容易写坏。

如果只列接口名称、调用方、被调用方、地址和认证方式，文档看起来很完整，但排查问题时仍然不够。因为问题不一定发生在接口调用那一秒，可能发生在接口前的数据准备，也可能发生在接口后的入库、计算、缓存或展示。

我后来更愿意把它写成链路：

业务方操作
  -> 前端提交
  -> 后端接口校验
  -> 写入业务表
  -> 定时任务读取
  -> 调用外部接口
  -> 回写处理结果
  -> 页面展示状态
  -> 邮件或消息通知

然后在每一段后面写“怎么判断这一段是否正常”。

前端提交：浏览器请求是否成功，参数是否完整
后端接口：日志是否有异常，响应码是否正常
业务表：是否生成记录，状态字段是否符合预期
定时任务：是否触发，是否处理到该记录
外部接口：请求是否发出，返回是否成功
回写结果：状态是否更新，错误信息是否落库
页面展示：是否读取了正确字段，是否存在缓存

这种写法比接口清单更适合接手。因为它不要求接手的人一开始就熟悉所有模块，只要顺着链路查，就能逐步缩小范围。

未完成事项不能只写“后续跟进”

交接时最容易被美化的部分，是未完成事项。

每个系统都会有暂时绕开的技术债、等待业务确认的规则、还没有排期的优化、只在某些情况下出现的问题。如果交接文档只写已经完成的东西，接手的人很快会踩到这些坑。

我给未完成事项单独做了一类，不用很复杂，但必须能继续推进。

事项：某接口权限切换
当前状态：测试环境验证通过，生产环境等待权限生效
已尝试方法：完成测试地址联调，确认返回字段符合预期
阻塞原因：生产访问权限尚未开通
风险：旧接口账号到期后，同步任务会失败
下一步：权限生效后做一次生产最小链路验证
需要谁确认：系统负责人、接口提供方、业务联系人

这里最重要的是“已尝试方法”和“阻塞原因”。接手的人不必从零开始，也不会误以为自己碰到了一个从未出现过的问题。

我也会把不确定的地方写出来。不能确认就写“待验证”，不要包装成确定结论。文档显得不那么好看，但它更诚实。交接不是写总结报告，没必要把所有地方都整理得像已经闭环。

交接的本质是降低系统对个人记忆的依赖

写到最后，我对交接这件事的理解变了。

它不是离职前的收尾动作，也不是证明自己做过很多事。它更像一次系统韧性检查：如果某个人不在了，这些系统还能不能继续被理解、维护和演进？

三万字里真正有价值的部分，并不是系统名称、服务器清单或文档路径。这些都会变。更有价值的是那些判断方法：

遇到异常先看哪条链路
哪些操作必须先备份
哪些任务可以重跑
哪些问题不能靠重启解决
哪些配置变化会影响多个系统
哪些不确定事项需要业务确认

如果一份交接材料只能在顺利时使用，它的价值有限。真正有用的交接，应该在事情不顺利时仍然能给接手的人一条路。

我后来也意识到，交接文档不可能永远正确。系统会变，人员会变，环境会变，接口也会变。与其追求一份永不过期的文档，不如把文档写成一种可维护的结构：有入口，有链路，有风险，有验证方式，也有明确的待确认事项。

这件事对我自己的影响也很直接。后来我再做需求、排查线上问题、设计发布方案时，会更早地想一个问题：如果半年后别人接手，他需要什么信息才能继续？

能回答这个问题，说明工作没有只停留在“我会做”。它开始变成团队可以接住的东西。