#006-文档驱动项目-第六篇:独立开发者的文档求生指南（完结篇）
第六篇:独立开发者的文档求生指南
第六篇：独立开发者的文档求生指南
——一个人维护多个项目，如何不被遗忘淹没
系列导读：这是《老项目如何引入文档驱动》系列的第 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 分钟搞定！
但 3 个月后，客户 A 又来需求。
张三想起来：我录了语音！
但问题是：语音在哪里？
他录了 20 多条语音，分散在手机备忘录、微信“文件传输助手”、电脑本地文件夹、云盘……
张三花了 1 小时，翻遍所有文件夹，终于找到那条语音。
但这 1 小时，足够他重新理解代码逻辑了。
张三很无奈：
“录语音看起来方便，实际上也是个坑。”
“找语音的时间，比重新理解代码还长。”
张三放弃了录语音，又回到写文档。但写文档又很慢，他又没时间。
临时项目的坑：突然延期了
客户 C 的活动小程序，预计运行 3 个月就下线。
张三决定：这个项目不写文档了，反正很快下线。
客户催得急，张三每天加班赶进度，根本没时间写文档。
3 个月后，活动结束了。张三松了口气：还好没浪费时间写文档。
但 1 周后，客户 C 突然来消息：
“老板说这个活动效果不错，要延期，继续运行 1 年。”
张三傻眼了。
他当时没写文档，现在要补？
但他已经完全忘记当时的设计决策了。
为什么定时任务是凌晨 2 点？为什么活动规则用了这个算法？为什么数据库字段是这样设计的？
全忘了。
张三只能硬着头皮，花了 2 天重新理解代码，然后写文档。
这 2 天，白白浪费了。
如果当初花 1 小时写个简单的文档，现在就不用花 2 天了。
张三后悔了：
“我以为临时项目不需要文档，结果被打脸了。”
客户催急：文档彻底荒废
客户 B 的管理系统，张三一开始很认真地写了文档。
但接下来 3 个月，客户 B 连续催需求：
周一：紧急 bug，必须今天修。周三：新功能，下周五上线。周五：又有紧急需求，加班赶进度。
张三每天忙到晚上 11 点，哪有时间更新文档？
文档？先欠着，等有时间再说。
3 个月后，客户 B 的需求终于不那么急了。
张三想起来：我还欠着 3 个月的文档没更新！
但这时候，他已经忘记这 3 个月改了什么了。
改了哪些核心逻辑？为什么这样改？有没有新的坑？
全忘了。
张三打开文档，和代码一对比：
完全对不上了。
文档说的流程，和实际代码已经不一样了。
张三只能硬着头皮，花了 2 天重新梳理逻辑，然后更新文档。
但 2 天后，他又有新需求了，文档又没更新。
周而复始。
张三很无奈：
“我知道要更新文档，但客户催得急，我真的没时间啊！”
“等有时间了，又忘了要更新文档。”
“最后，文档彻底荒废了，和代码完全对不上。”
3 个月后：张三找到了自己的节奏
3 个月过去了，张三也踩了不少坑。
文档过时？遇到过，改出过 bug。录语音找不到？浪费过 1 小时翻文件夹。临时项目延期？补过文档。
但张三现在找到了自己的节奏。
客户 A 的电商平台（长期项目）:
张三每次改完代码，都会花 10 分钟更新文档。
哪怕客户催得再急，这 10 分钟他也会留出来。
为什么？
因为他被坑过。文档过时了，会误导自己改出 bug。
现在，张三切换到客户 A 的项目，5 分钟就能进入状态。不用花 2 天回忆当时的设计，不用翻 Git 历史找 Commit Message。
这个时间差，太爽了。
客户 B 的管理系统（需求频繁）:
张三不追求完美了。
只记录关键决策和避坑指南，其他的？算了，能看代码就看代码。
客户 B 催得太急，张三实在没时间维护完美的文档。
但至少，关键的设计决策他记下来了。
虽然文档有些地方过时了，但核心的“为什么这样设计”，张三还记得。
这个，够用了。
客户 C 的活动小程序（临时项目）:
张三现在至少会记录 3 行关键决策。
万一延期了呢？这 3 行能救他 2 天时间。
张三被坑过一次，不想再被坑第二次。
你可能会问：这样够吗？
够了。
张三现在切换项目，从原来的 2 天缩短到 5-10 分钟。
这个时间差，足够大了。
你也是独立开发者？
那你应该理解：我们没有理想的文档时间，只有“能省则省”的策略。
但这个策略，确实有用。
张三被坑过几次，但总体来说，文档驱动让他的工作效率提升了。
至少，比完全靠记忆强太多了。
独立开发者的文档驱动，不是方法论，是求生技能。
它不完美，但够用。
这就够了。
系列完结。
前 5 篇讲团队场景，这一篇讲独立开发者。如果你也维护多个项目，张三的故事也许能帮到你。