上周接了个活,帮一位朋友接手一个全栈项目。原开发离职前只留下一个仓库地址和一句"代码注释挺全的,有问题随时微信"。结果我光是理清环境依赖、部署脚本和那几个定时任务的数据流,就花掉整整三天。那三天里我边骂边想:全栈工程师的交接,本质上是在交接一个只存在于某个人脑子里的完整世界,而这个世界的每一层——前端状态管理、后端接口约定、定时任务、服务器上的 crontab、数据库里的历史数据补偿逻辑——全都环环相扣,缺一环就转不起来。
后来我痛定思痛,干脆用 ChatGPT 给自己生成了一份全栈工程师交接文档模板。不是网上那种两页纸的"项目名称+技术栈+部署方式"的敷衍版本,而是真正把我在交接现场遇到的所有问题都反向转化成模板字段的结构化文档。这篇文章就把这份模板的完整设计思路、每个板块为什么存在、以及我如何通过多轮提问让 ChatGPT 帮我把它打磨到可落地,原原本本拆给你看。
1. 全栈项目的交接为什么总是鸡飞狗跳
先说一个我的观察:后端工程师交接通常还好,因为后端有明确的接口文档、数据库表结构、部署拓扑,知识相对有边界。前端工程师交接也勉强能忍,因为页面就摆在那里,路由一跑就能看到全貌。但全栈工程师的交接,是把这两摊事叠在一起,再乘上一个"隐藏复杂度",难度完全不是一个量级。
1.1 知识维度太多,单人即孤岛
一个典型的全栈项目,光知识维度就能列出七八层:浏览器端的状态管理和组件通信、前后端接口的约定与异常处理、数据库的表设计与数据迁移、对象存储和消息队列这类中间件、服务器上的 Nginx 和进程守护配置、定时任务与补偿脚本、第三方服务的对接与限额。在一个没有完整文档习惯的团队里,这些知识通常只有一个人完整掌握——就是那个写全栈的老哥自己。他一旦离开,这些知识就跟着他一起离开。
更麻烦的是,很多全栈项目是"先有项目,后有团队"。代码是写给自己用的,注释也常常是写给当时的自己看的。三个月后接手的人看着那些注释,往往需要先把注释本身当成谜面来解。我见过最离谱的情况是,代码里写着"此处勿动",接手人找了半天也没注释为什么不能动,最后发现是这个接口返回的数据格式被另一个隐去调用方截胡了。
1.2 知识诅咒:不是不想写,是不知道从哪里写起
我跟很多做全栈的朋友聊过交接文档这件事,发现一个共性:大部分人不写交接文档,不是因为懒,而是因为"知识诅咒"太严重。你每天都在这个系统里游泳,你觉得所有东西都是理所当然的——Nginx 里那个奇怪的 location 规则?那是因为证书续期脚本有个 bug,绕一下;数据库里那个冗余字段?是因为某个统计报表直接查太慢,特意反规范化存了一份。
这些信息在写代码的人看来是"背景知识",根本不会想起来要写进文档。但对接手的人来说,每一个"理所当然"背后都可能藏着一整晚的排查时间。所以交接文档的核心价值从来不是记录"系统是什么",而是记录"系统为什么长成现在这样"。
1.3 传统交接文档的三宗罪
网上能搜到的交接文档模板,我基本都翻过,发现它们大多犯三个毛病:
- 只写结果,不写原因。比如"数据库用了 MySQL 8.0",但不写"为什么从 5.7 升上来,因为某个版本后 JSON 字段的排序行为变了"。接手人看到结论,却无法判断哪些结论是必须坚持的,哪些只是历史遗留。
- 只写正向流程,不写坑。部署文档告诉你跑
docker-compose up -d就能起服务,但不告诉你第一次启动前必须手动创建某个目录,否则容器会以非预期的方式挂掉。 - 只有静态结构,没有运行时状态。文档描述了代码仓库里的世界,但真实系统还有一堆运行时的"临时安排"——Cron 里挂着谁的手动任务、生产环境和预发布环境的配置差异、某个第三方平台的 API Key 只在这个账号下有效。
所以我在设计模板时,给自己定了一条铁律:每一个板块都必须能回答"接手人读到这里时,会在这个环节踩什么坑"这个问题。回答不了,这个板块就是废的。
2. 让 ChatGPT 生成交接文档骨架:我的设计思路与最终模板结构
我的做法不是一句"帮我写个交接文档模板"就完事。ChatGPT 在没有任何上下文的时候,给出来的东西大概率是网上模板的重排版。为了让它产出对全栈场景有用的结构,我先把自己的真实痛点喂给它:前端构建工具的版本陷阱、后端多环境配置的一致性、服务器上各种"只有我知道"的临时任务。然后让它给一个承接这些痛点的结构。
2.1 从痛点反推模板结构
完整对话过程后面会讲,这里先给结论。经过三轮迭代后,最终采用的模板骨架如下:
# 全栈项目交接文档 ## 0. 交接总览 - 项目一句话简介 - 当前线上版本与运行状态 - 交接人与接手人 - 核心风险提示(一句话版) ## 1. 项目概述与角色边界 - 业务背景与用户群体 - 系统由哪几个子系统组成 - 当前团队每个角色的职责边界 ## 2. 环境与依赖总览 - 本地开发环境要求(精确到小版本) - 前端构建链路(Node 版本、包管理器、构建命令) - 后端运行时(语言版本、依赖管理、系统依赖) ## 3. 代码仓库与分支策略 - 仓库地址与权限说明 - 分支模型与发布流程 - 代码规范与提交规范 ## 4. 架构与核心链路(在文档中补充手绘图或文字链路) - 整体架构图(标注核心组件) - 核心业务流程时序(从用户点击到落库到异步回调) - 关键设计决策记录(ADR 摘要) ## 5. 数据库与数据资产 - 数据库连接与权限(密码置为占位符) - 所有表/集合清单与用途 - 数据迁移与备份策略 - 历史数据补偿脚本列表 ## 6. 部署链路与运维手册 - 服务器清单与环境拓扑 - 从裸机/空环境部署到线上可用的完整步骤 - 常用运维命令速查 - 日志查看方式与常见错误码 ## 7. 外部依赖与第三方服务 - 对接的第三方服务列表 - 各服务的账号权限与额度 - 回调/Webhook 配置 - 扣费与限额预警方式 ## 8. 业务状态与未完成事项 - 当前迭代进度 - 已知缺陷与临时方案 - 技术债清单与改进建议 ## 9. 交接验收单 - 接手人按文档复现环境的记录 - 各项检查是否通过 - 遗留问题与处理方案这套结构跟通用模板最核心的区别在两点:一是设置了"架构与核心链路"和"业务状态与未完成事项"这两个独立板块,把"系统设计意图"和"项目当前真实状态"显式地单独列出来;二是在"环境与依赖"、"部署链路"里强调了"完整路径",而不是只给一个 install 命令了事。后面逐个拆解。
2.2 为什么是这九个板块
我把每个板块的存在理由在表格里列一下,方便你对照判断自己项目需要哪些、可以砍掉哪些:
| 板块 | 解决的核心问题 | 没有它会发生什么 |
|---|---|---|
| 交接总览 | 接手人 10 分钟内建立全局认知 | 接手人像盲人摸象,花几天才拼出全貌 |
| 项目概述与角色边界 | 明确系统范围和职责归属 | 什么事都来问你,交接期被无限拉长 |
| 环境与依赖总览 | 让接手人能在自己电脑上跑起来 | 卡在装环境阶段,连代码都看不了 |
| 代码仓库与分支策略 | 让接手人知道怎么提交、怎么发版 | 第一个 commit 就破坏了发布流程 |
| 架构与核心链路 | 把"系统为什么长这样"记录下来 | 接手人不敢改任何有历史包袱的代码 |
| 数据库与数据资产 | 让接手人理解数据从哪来到哪去 | 查个报表字段都不知道去哪张表 |
| 部署链路与运维手册 | 让接手人能独立发布和排障 | 生产环境一挂,全家等着你救火 |
| 外部依赖与第三方服务 | 让接手人知道系统有哪些外部依赖 | 某个 Webhook 断了一周没人发现 |
| 交接验收单 | 确认接手人真的读懂了、跑通了 | 文档写完即吃灰,等于白写 |
需要说明的是,这个九板块结构主要面向"前后端 + 部署一人扛"的全栈项目。如果你维护的是微服务架构或者纯后端系统,可以适当裁掉前端构建部分,加上服务间调用矩阵。模板是骨架,血肉要按项目实际填充。
3. 核心板块逐个拆解:真正拉开交接质量差距的地方
这一节我把模板里最容易被忽略、但又最容易坑到接手人的几个板块,用真实场景展开讲讲。模板的完整文档里这每个板块都有对应的示例内容,但篇幅所限,我挑四个最关键的来拆。
3.1 环境与依赖总览:版本要精确到小版本,命令要给全
环境这块写不细,交接文档基本就废了一半。前端项目尤其典型:Node 14.18和Node 14.19在某些依赖下行为都不同,更不用说Node 16和Node 20天差地别。所以模板里我要求所有版本必须写成三项:主版本.次版本.修订版本,外加一句"为什么锁这个版本"。
### 环境版本要求(示例) - Node.js:v16.20.2(必须用 16.x,项目用了 node-sass,高版本 Node 无法编译) - 包管理器:pnpm@7.33.7(版本不能高于 8,v8 更改了依赖解析规则,会装出不同的依赖树) - Java:Temurin 17.0.9(JDK 17,不能换 21,部分旧版 FastJSON 在 21 上反射会报错) - MySQL:8.0.36(注意 SQL 模式,生产环境开了 ONLY_FULL_GROUP_BY,本地也要开)注意看每一行,版本后面都跟了原因。这份信息才是环境文档的价值所在。否则接手人本地装了个最新版 Node,一启动就报错,他根本不知道是版本问题,会以为是自己环境没配好,白白浪费半天。
部署部分也一样,不能只写yarn build然后再说"下一步在服务器上把 dist 目录放到 Nginx 下即可"。中间缺的细节太多了。我通常在模板里直接放一段完整脚本:
# 前端构建产物部署到服务器的完整流程 set -e # 1. 本地构建(务必先切到 main 分支并拉取最新代码) git checkout main && git pull origin main yarn install --frozen-lockfile yarn build # 2. 上传构建产物(国内服务器建议用 rsync,避免 scp 断点续传问题) rsync -avz --delete dist/ root@120.xx.xx.xx:/var/www/myapp/ # 3. 服务器上无需重启 Nginx,但需要重新加载 ssh root@120.xx.xx.xx "nginx -t && nginx -s reload" # 4. 验证(确认静态资源能访问,注意缓存问题,必要时手动清一下 CDN) curl -I https://myapp.example.com/这段脚本每一步都有注释,连"为什么用 rsync 而不是 scp"这种细节都在里面。传递信息的时候顺带把决策理由带出来,接手人就能理解你的操作习惯,而不是机械敲命令。这也是 ChatGPT 在我的提示词指导下生成、我再根据实际部署场景手动修正后的效果。
3.2 部署链路与运维手册:从裸机到线上可用的无断点路径
我见过的交接文档,部署部分写"docker-compose up -d"就算完事。但真正在交接现场,问题往往出在 docker-compose 之前:服务器没装 Docker、镜像拉不下来、.env 文件不存在、数据卷目录没创建、首次启动时数据库没有初始化数据。
所以模板里我把部署链路分成三段来写,每一段都要求写到"中间不能有任何'你懂的'步骤":
- 服务器基础环境:操作系统版本、已安装的运行时和版本、防火墙开放了哪些端口、来了一个新服务器要装哪些东西、有什么历史包袱不能动。
- 应用部署:构建命令、启动命令、环境变量清单、数据卷挂载点、首次启动和日常重启的差别。
- 发布后检查:健康检查接口、日志位置、错误排查命令速查。
运维部分也别只写"看日志tail -f"。模板里我建议列一个常见错误速查表,比如:
| 现象 | 可能原因 | 排查命令 | 处理办法 |
|---|---|---|---|
| 502 Bad Gateway | 后端服务挂了或端口变了 | systemctl status myapp/ `ss -tlnp | grep 8080` |
| 前端资源加载 404 | 构建产物路径和 Nginx 配置不匹配 | ls /var/www/myapp/dist | 检查构建配置base字段 |
| 数据库连接超时 | 连接池满或网络问题 | SHOW STATUS LIKE 'Threads_connected' | 调整连接池上限或重启数据库 |
| OOM 导致服务退出 | 服务器内存不足 | `dmesg | grep -i oom` |
这四行只是示例,但就是这种"现象-可能原因-排查命令-处理办法"的速查结构,能让接手人在没有你的时候,也能顺着链路自己排查。我在 ChatGPT 的返回基础上补了ss -tlnp和dmesg这类细节,因为模型不知道你服务器的系统版本和中间件组合,这些只能靠人补。
3.3 数据库与数据资产:写清楚每一张表是干什么的
数据库这块,常见的交接文档就是一张表名列表:user、order、product。但接手人拿到这张列表,依然不知道用户在哪张表、订单状态用什么字段表示、某个字段为什么找不到索引。
模板里我给了一份表清单模板,要求每张表至少写出三点:表用途、关键字段、与其他表的关系。比如:
### 核心表清单(节选) - `users` - 用途:前台用户账号信息,包含手机号和微信 unionid - 关键字段:id(主键)、phone(手机号,唯一索引)、wx_unionid(微信登录用,可为空)、status(1 正常 2 封禁) - 关联关系:1:N `user_address`;1:N `orders` - `orders` - 用途:订单主表,每次支付成功生成一条记录 - 关键字段:id、user_id、status(10 待支付 20 已支付 30 已发货 40 已完成 50 已取消)、total_amount(单位分)、channel(1 微信 2 支付宝) - 关联关系:N:1 `users`;1:N `order_items`除了表结构,数据迁移和备份策略也是全栈项目里没人写但特别重要的东西。比如有没有定时任务在同步生产数据到预发布环境、数据库备份是每天几点跑、备份文件保留几天、出问题时怎么回滚到某个时间点。这些我都要求写进模板,因为只有原开发知道哪条迁移脚本是"跑完不能重跑"的,哪张表是"删了就没法恢复"的。
3.4 外部依赖与第三方服务:把看不见的耦合显式化
全栈项目最大的隐形风险,就是第三方服务。微信支付回调、短信服务商的模板 ID、对象存储的 Bucket 名称和访问密钥、地图服务的每日免费配额,这些东西没有写进文档的话,接手人根本不知道项目里哪些功能其实是"外包"给了一家外部公司在做。
我让 ChatGPT 在模板里给了一份第三方服务清单,字段包括:服务名称、用途、对接方式(API/回调/SDK)、当前账号、限额与费用、故障联系人/通道。我还额外加了一条要求:每一项都要标注"如果这个服务挂了,系统的哪部分功能会怎样受影响"。比如:
| 服务 | 用途 | 对接方式 | 限额 | 挂了会怎样 |
|---|---|---|---|---|
| 微信支付 | 用户下单支付 | 服务端调用 JSAPI 下单 | 无硬限制 | 用户无法支付,订单一直停在"待支付" |
| 阿里云 OSS | 商品图片存储 | SDK 直传 | 按量付费 | 图片无法上传和访问,前端大量图片裂开 |
| 极光推送 | 订单状态变更通知 | 服务端 REST API | 免费版 10 万条/日 | 用户收不到订单状态推送 |
| 高德地图 | 门店地址定位 | Web 端 JS SDK | 个人版日配额 1 万 | 门店地图无法加载,但不可直接报错影响主流程 |
模板里这份表的示例内容是 ChatGPT 生成的通用版本,但我在实际项目中会让它先在《项目概述》里读到我写的项目业务描述,再让它把对应的第三方服务列出来。模型未必知道你用了哪些服务,但你可以在提示词里给它线索。
4. 把半成品模板变好用:我调教 ChatGPT 的完整提示词与迭代过程
这一节重点说说我是怎么跟 ChatGPT 配合的。很多人跟 AI 协作时犯的最大错误,是把 AI 当成一个"一次成型"的工具,第一版不满意就觉得这玩意不行。我自己的经验是:ChatGPT 更适合当一块需要反复打磨的璞玉,你和它来回磨几个回合,它才真正懂你要什么。
4.1 第一轮:先给框架,用业务背景约束方向
我第一轮没有直接说"给我写个交接文档模板",而是先给了它一个背景设定和一个明确要求:
你是一名有 10 年经验的全栈工程师,正在从一家公司离职。你负责的是一个典型的全栈 Web 项目:Vue3 + Node.js + MySQL,同时管理一台云服务器,部署用 Nginx + PM2。接手人是有 3 年后端经验、但对前端构建和服务器运维不太熟的工程师。 请给我一份交接文档的完整大纲。注意以下约束: 1. 大纲要确保接手人跟着文档就能把项目在本地跑起来。 2. 要包含"原开发脑子里才知道"的信息,比如环境版本坑、部署的隐藏步骤、第三方服务的账号注意事项。 3. 不要套用网上的通用模板,要结合全栈项目的特殊性。 4. 每个章节要说明"这一章为什么要写、用来解决什么问题"。这一轮的结果基本就是前面展示的九板块骨架。ChatGPT 给的第一版其实已经比网上的通用模板强不少,至少分了"环境与依赖""部署链路""第三方服务"这些对全栈项目真正要命的模块。但第一版有个问题:它给的"说明"太概念化,比如"环境与依赖:确保接手人了解项目所需环境",这种话放到哪篇文章里都对,放到你项目里却不痛不痒。
4.2 第二轮:逐章节让 AI "把自己当接手人"来反向审查
我发现 ChatGPT 生成的模板有一个通病——它总是倾向于写出"标准操作流程",而不是"真实踩坑记录"。原因很简单:模型训练数据里的文档大多是理想化的,没人把坑写进公司文档。所以第二轮我换了个策略,直接让它扮演接手人来批评这份模板:
现在请切换角色:你是一个刚入职的接手人,对项目完全不了解,拿着这份大纲准备开始工作。 请从"你一定会遇到但大纲里完全没有覆盖"的角度,逐章节指出这份交接大纲的缺陷和遗漏。 用具体场景描述你的顾虑,比如: - 接手后第一天你想怎么把项目跑起来?会遇到什么障碍? - 第一次部署时你敢不敢直接在生产环境操作?哪里会卡住? - 你读代码时,最希望哪些曾经的项目背景被记录? 请给出"补充问题清单",并基于清单更新大纲。这一轮效果非常明显。ChatGPT 自己就指出了好几个我之前没注意到的遗漏:数据库账号密码的交接方式、证书续期脚本的存在性、跨环境的配置差异、以及"如果有定时任务,它们跑在哪里、由谁触发"这种运行时认知。于是我把这些全部融进了上一节的模板结构里。这也是为什么最终模板会有一个独立的"业务状态与未完成事项"板块——因为在 AI 扮演接手人问出"现在这个项目有哪些已知问题是我接下来要面对的"这个问题之后,我意识到这是交接文档里最不该缺的一块。
4.3 第三轮:把它生成的板块逐段扩写、注入你的专属上下文字段
框架定下来之后,剩下的工作就是逐板块扩写。我通常会给它提供一小段"真实上下文",比如我的技术栈、服务器地址(脱敏)、第三方服务列表、项目的业务类型,然后要求它在这个上下文内扩写某个章节的具体字段和示例。拿"部署链路"来举例:
项目背景:Vue3 + Vite 前端,Node.js (Express) 后端,用 PM2 守护进程。 服务器信息:单台 CentOS 7,Nginx 反向代理端口 80/443,已配好 SSL 证书。 部署方式:本地构建后 rsync 到服务器,后端代码用 git pull + pm2 reload 更新。 请把交接文档中的"部署链路与运维手册"这一节扩写成可直接执行的步骤, 要求: 1. 每一步都写完整的命令,不要省略任何中间过程。 2. 在容易踩坑的地方(如目录权限、防火墙端口、PM2 日志等)加上警告提示。 3. 额外增加一个"首次部署 vs 日常更新"的对比说明。这个案例中,ChatGPT 会生成一份相当完整的部署手册,带有 rsync、nginx -t、pm2 reload 这类真实命令和注意事项。我拿回来后只需要按照自己服务器的实际情况微调路径、端口,填入真实的域名和 IP(脱敏),就变成了一份可以直接给人用的运维文档。你会发现 AI 的价值在这里不是"替你写文档",而是"帮你把零散的经验整理成结构化的初稿",你再做的只是校验和注入只有自己知道的细节。
4.4 一套实用的小经验:不要直接问"给我模板",要问"给我一个能从零开始做事的清单"
我最后总结几条用 AI 生成这类文档的经验,你可以直接抄:
- 不要只给一句话让它自由发挥。你需要先写明项目背景、接手人的技术背景、你最担心哪些环节,AI 才能生成有针对性的结构。越是模糊的请求,越容易得到一个"看着都对,实际没用"的结果。
- 至少做两轮反向审查。第一轮让它扮演接手人挑刺,第二轮让它把"交接文档里可能存在的模糊表述"全找出来。你会发现它特别擅长挑出"很简单""正常运行"这类话病,然后逼你把话说明白。
- 把生成内容当草稿,不当成品。AI 能帮你整理框架、补全字段、优化表达,但只有你知道服务器上那个"不要重启的数据库节点"是哪台,哪些第三方账号在财务那边还没走完流程。把 AI 当实习生,别把它当神仙。
5. 交接文档里的暗坑与我在真实交接中总结的教训
结构对了、内容填了,交接文档就算完成了吗?远远没有。我在过去几年经历过大大小小十几次交接,有作为原开发的,也有作为接手人的,有些坑只有到现场才能真正暴露出来。这一节把这些教训记下来,算是给前面模板做一层"防护网"。
5.1 暗坑一:文档里写"很简单"的地方,往往最复杂
我在模板审阅规则里专门加了一条:禁止使用"很简单""不需要管""默认就好"这类描述。理由很简单,凡是原开发愿意写"很简单"的地方,要么是真的简单,要么是他自己也没完全想清楚、嫌麻烦不想展开。对接手人来说,这句话同时充当了"此处不需要深究"的暗示——当项目出问题时,他大概率会直接跳过这个区域,绕一圈才发现问题就出在这里。
所以我给自己定了个规矩:凡是文档里出现这类模糊表述,一律把它当成"待补充线索",追问自己一句"如果接手人在这里犯了错,会导致什么后果"。如果后果严重,就必须展开写;如果确实简单,就改成可验证的具体操作,比如"这里无需手动处理,执行bash scripts/init.sh会自动创建所需目录"。
5.2 暗坑二:环境配置文档缺首尾,只覆盖中间一段
很多人写环境配置的时候,默认接手人会做环境安装前的准备和安装后的验证。比如写下"npm install安装依赖",但不写"如果你的 Node 是 18 而不是 16,会编译失败,需要先安装 nvm 并切换到 16.20.2"。接手人安装完依赖开始跑项目,报错了,又回头排查依赖、排查代码,绕了一大圈,最后发现是 Node 版本不对——这种时间浪费完全是文档作者可以避免的。
解决的办法很简单,在模块开头写一句"前置条件",模块末尾写一句"如何验证已就绪"。比如:
## 本地环境搭建 前置条件: - 已安装 Node v16.20.2(推荐用 nvm 管理) - 已安装 pnpm@7 - 已安装 Docker(用于启动 MySQL 和 Redis) 完成后验证: 运行 `pnpm dev`,浏览器打开 http://localhost:5173,能看到登录页并成功登录。加上首尾之后,接手人每个环节都能自我验证,卡住了也知道是哪一步的问题,可以带着具体报错来问你。
5.3 暗坑三:文档写完不算完,一定要让接手人按文档走一遍
这是我从一次失败的交接里得到的最惨痛教训。当时我自认为文档写得已经很细了,结果接手人跑本地环境时还是卡住了——因为模板里我写了"启动后端前先执行 schema 迁移",但我没有说明这个迁移脚本需要连数据库,而本地数据库默认没有建好账号。这个"默认"对我来说是常识,对接手人来说却是黑洞。
从那以后,我把这条规则写进了交接流程:交接文档的验收标准不是"文档写完了",而是"接手人仅凭文档,从零开始把项目在本地跑起来,并且成功部署一次到测试环境"。这个过程里只要出现任何一次他需要问你的情况,说明文档还有缺口,要当场记录、当场补齐。这也是模板里为什么要有"交接验收单"板块的原因——每一项检查,接手人和交接人双签确认,才算真正完成了交接。
5.4 暗坑四:账号密码的交接安全问题
最后提醒一个安全话题。交接文档里不可避免要涉及服务器密码、数据库账号、第三方服务的 API Key。这些东西直接写在正文里既不安全,也容易被随手转发。我的做法是:正文里统一写占位符(比如<服务器密码,见加密压缩包>),把真正的账号密码单独整理成一个加密压缩包,当面通过加密渠道移交(比如加密压缩包发一个渠道,密码走另一个渠道),交接完成后原开发修改相关密码。
在第 7 章节"外部依赖与第三方服务"的模板里,我给 AI 的提示词也加了"不要把真实密钥写入正文"的约束。安全这个事,多谨慎都不为过。接手人如果遇到你交接完就联系不上的情况,唯一能信任的就只有你留下的文档——如果文档里的密码集体失效,那才是真正的灾难。
6. 把模板变成你自己的:一份拿来即用的完善清单
前面讲了这么多,最后放一份我自己每次交接前都会过一遍的清单。这份清单是在 ChatGPT 生成模板后,经过我两次真实项目的检验、调整出来的最终版。你不需要照搬全抄,但建议把它当底稿,按团队现状增删。
交接文档自查清单
- [ ] 是否有一句话说明项目是干什么的、当前处于什么阶段?
- [ ] 接手人的技术栈和项目差距最大的部分,是否有专门的说明?
- [ ] 本地环境从零到能运行,是否有覆盖"前置条件—操作步骤—验证方法"完整链路?
- [ ] 所有软件版本是否精确到修订版本,并标注了为什么锁这个版本?
- [ ] 是否有一份"常见错误与解决方案"速查表?
- [ ] 生产环境的部署流程是否具备可复制性,新人照着做也能成功?
- [ ] 是否有"首次部署"和"日常更新"的对比说明?
- [ ] 数据库的每张核心表是否有用途和关联关系说明?
- [ ] 是否有完整的数据备份、恢复、迁移脚本清单?
- [ ] 所有第三方服务是否记录了用途、账号、限额、挂了会怎样?
- [ ] 是否记录了当前项目的已知缺陷、临时方案和技术债?
- [ ] 交接文档里的账号密码是否使用了占位符,敏感信息单独加密保存?
- [ ] 是否设置了一个"交接验收单",并真的让接手人按文档走了一遍?
- [ ] 是否约定了交接期内的过渡期支持和联系方式?
我每次写交接文档,基本就是把这份清单过一遍,再往模板里填内容,填不上的地方就说明那个领域我还没有处理好,需要补课。这个过程本身也是一种对项目健康状况的体检。
最后说一点掏心窝的话。我在刚开始写交接文档时,总觉得"这玩意是给别人看的,又不是给我的,差不多就行了"。直到有一次,我把自己负责的项目交接给别人后三个月,又被调回去处理遗留问题。当时我拿到自己当初那份写得还算仔细的交接文档,重新捡起自己写的代码,居然靠那份文档十分钟就恢复了对整个系统的记忆。那一刻我才真正明白:交接文档不只是写给接手人的,也是写给未来的自己的。把这个文章里提到的那份由 ChatGPT 辅助生成的模板基于你自己的项目填一遍,你会发现它给你省下的时间,远比写它所花的时间多得多。