第六篇:独立开发者的文档求生指南
第六篇：独立开发者的文档求生指南
——一个人维护多个项目，如何不被遗忘淹没
系列导读：这是《老项目如何引入文档驱动》系列的第 6 篇，也是最后一篇。前五篇我们聊了团队场景下的文档驱动实践。但很多读者反馈：我是独立开发者，一个人维护多个项目，文档驱动对我有用吗？这篇文章就是要回答这个问题。
张三的崩溃：2 天才想起来的设计
张三是一名独立开发者，同时维护 3 个客户的项目。
周一早上，客户 A 突然来消息：
“能不能加个银联支付？客户要求的，这周五上线。”
张三打开代码，傻眼了。
他完全不记得：
-
支付回调是怎么处理的
-
为什么用了这个第三方库而不是那个
-
那个奇怪的 if 判断是干什么用的
为什么？
因为这个项目，他已经 3 个月没碰了。
上次改支付模块，还是 3 个月前。当时的设计思路、踩过的坑、为什么这样权衡，全忘了。
张三花了整整 2 天，才勉强想起来当时的设计思路。
他翻 Git 提交记录，看自己 3 个月前写的代码，看 Commit Message（都是“fix bug”、“update”），看数据库表结构，看第三方文档……
客户催得急：
“怎么还没开始写代码？”
张三很焦虑：“我得先理解现有的代码啊！”
周五晚上 11 点，张三终于改完了。
客户很满意，但张三很累。
更重要的是，他意识到：这样下去不行，下次切回来，又要花 2 天回忆。
这就是独立开发者的痛点：
频繁切换项目，每次都要花 1-2 天“回忆”当时的设计。
时间都浪费在“回忆”上，而不是真正的开发。
张三决定：必须找个办法记录关键信息。
第一次尝试：写文档（完全没用）
周末，张三花了一整天，给 3 个项目各写了一份“项目文档”。
他记录了：
技术栈（Spring Boot + MySQL）、核心流程（用户下单 → 创建订单……）、注意事项（支付回调要验证签名……）
张三当时还挺满意：终于把文档补上了！
3 个月后，客户 A 又来需求。
张三打开文档，看了 5 分钟。
然后发现：完全没用。
“技术栈”？我当然知道用的 Spring Boot，这有什么用？“核心流程”？这个看代码就知道了。“注意事项”？太泛泛而谈，根本想不起来当时的具体设计。
张三发现：第一版文档完全是废话，没记录关键信息。
他还是花了 2 天，重新理解代码。
文档？白写了。
第二次尝试：用 AI 生成（更惨）
第 2 周，张三想：既然自己写不好，不如用 AI?
他让 AI 读了客户 B 项目的代码，生成“项目文档”。
AI 生成的 ：用户管理（JWT 验证）、数据管理（MyBatis）、定时任务（凌晨 3 点）……
张三看完后，崩溃了：
这写的都是什么？这些我当然知道！
AI 完全没有记录关键信息： 为什么用 JWT 而不是 Session？定时任务为什么是凌晨 3 点？
更糟的是，AI 生成的文档有 40% 是错的：
-
AI 说“定时任务每天凌晨 3 点执行”，实际是凌晨 2 点
-
AI 说“用户权限控制用了 RBAC”，实际是简单的角色判断
-
AI 说“数据导出支持 Excel 和 PDF”，实际只有 Excel
张三花了整整 1 天，修正 AI 生成的文档。
修正完后，他发现：比自己从零写还慢。
张三很崩溃：
“早知道这样，还不如自己写。AI 就是个坑！”
张三放弃了用 AI，改为手写。但手写又很慢，他又没时间。
第三次尝试：只记录关键决策（有用了！）
第 3 周，张三反思了一下，发现第一版文档为什么没用：
因为他记录的都是“显而易见的信息”（技术栈、核心流程），没有记录“容易忘记的信息”（设计决策、踩过的坑）。
张三调整了文档内容：
支付模块关键决策：
-
为什么用同步调用？（客户要求立即反馈，虽然性能稍差）
-
为什么回调用两层验证？（之前遇到过伪造回调攻击）
-
支付回调可能延迟 10 分钟（增加了主动查询，每 5 分钟查一次，别查太频繁会被限流）
这次的文档，只记录“关键决策”和“常见的坑”，不记录显而易见的信息。
2 个月后，客户 A 又来需求。
张三打开文档，看了 5 分钟。
这次，他没有花 2 天回忆，5 分钟就想起来了！
张三很兴奋：文档是真有用！
但他很快发现新问题：
文档过时了。
文档过时：误导了自己改出 bug
又过了 1 个月，客户 A 的支付突然出问题，用户投诉：“支付失败了，但钱被扣了！”
张三赶紧排查，看了一眼自己的文档：
“支付回调每 5 分钟查一次，最多查 3 次。”
张三按照文档理解的逻辑，修改了重试机制。
上线后，问题更严重了：支付更慢了，用户投诉更多了。
张三崩溃了，重新看代码，发现：
他 1 个月前已经把查询间隔改成 10 分钟了，但忘了更新文档。
文档说 5 分钟，实际是 10 分钟。
张三按照过时的文档改代码，结果改错了。
张三很崩溃：
“我本来是想用文档帮助自己，结果反而被文档误导了！”
“文档过时了，还不如没有！”
那天晚上，张三认真考虑过：要不把所有文档都删了，算了？
但删了，下次回来又要花 2 天回忆。不删，文档过时又会误导自己。
张三陷入了两难。
录语音的坑：1 小时找不到
张三想：写文档太慢，要不录语音？
改完代码后，打开手机语音备忘录，录 1 分钟：
“我刚改了支付回调的逻辑，原来是每 5 分钟查一次，现在改成每 10 分钟。为什么改？因为支付宝限流了，查太频繁会报错。这个坑我踩了 2 天才发现，记住！”
张三当时觉得：这个方法真快！1 分钟搞定！