—— 让文档成为活的产品规范 + 博客 v0.5 搜索功能实战
系列导读：这是《用一份 .md，把想法变成产品》系列的第5篇。在前四篇中，我们建立了文档驱动的理念，定义了三份核心文档，成功实现了博客的 v0.1 到 v0.4。现在，博客已经有了文章列表、分页、分类和标签功能。但随着项目演化，一个新的问题浮现：如何让文档保持鲜活，而不是变成过时的归档文件？
开篇：文档腐化的困境
v0.4 上线两周后，卡比的博客已经发布了20多篇文章。一天晚上，卡比在浏览自己的博客时，突然意识到一个问题：
"我有这么多文章，但每次想找一篇旧文章都要翻好几页，太不方便了。我需要搜索功能！"
卡比兴奋地打开项目文件夹，准备添加搜索功能。但在动手之前，卡比想起了文档驱动开发的原则："功能变更，先更新文档。"
于是，卡比打开了 spec.md 文件，准备添加搜索功能的需求描述。但当卡比看到文档内容时，愣住了：
文档里还保留着 v0.1 的一些描述，有些功能说明和当前代码已经不一致，甚至还有一些标记为"待定"的部分从未更新过。
"糟糕，我的文档已经过时了..."
这就是文档腐化（Documentation Decay）的问题——即使你写了很好的文档，如果不持续维护，它们很快就会变成无用的文字堆积。
一、文档腐化的根源
1.1 为什么文档总是过时？
卡比陷入了思考："为什么我明明重视文档，却还是让它们过时了？"
仔细分析后，卡比发现了三个根本原因：
原因 1：更新成本高（心理门槛）
场景重现：
-
开发新功能时，卡比会想："先把代码写出来，文档等会儿再说"
-
调试 bug 时，卡比会想："这只是个小改动，不用更新文档吧"
-
赶项目进度时，卡比会想："来不及了，文档下次补"
结果："下次"永远不会来。
心理分析：
-
更新文档需要"切换上下文"（从编码思维切换到写作思维）
-
文档更新没有即时反馈（代码改完能立即看到效果，文档改完看不出什么）
-
感觉"浪费时间"（"我都已经实现了，为什么还要再写一遍？"）
原因 2：无人负责（职责不清）
场景重现：
-
个人项目：只有自己，"反正我记得"（但两个月后就忘了）
-
团队项目：大家都觉得"应该有人更新"，但没人真正负责
问题本质：
-
没有明确的"文档所有者"（Document Owner）
-
没有建立"代码更新 = 文档更新"的强制关联
-
没有制度化的检查机制
原因 3：收益不明（为什么要更新？）
场景重现：
卡比在实现分类功能时，确实更新了 spec.md，但只是简单地添加了几行描述：
"支持文章分类。用户可以按分类查看文章。"
这种描述太笼统，以至于当后来要添加"分类统计"功能时，卡比不确定这算是"新功能"还是"完善现有功能"。
问题本质：
-
文档更新质量低（敷衍了事）
-
没有意识到文档的长期价值
-
把文档当作"任务"而非"资产"
1.2 文档腐化的恶性循环
卡比画了一个循环图：
文档过时 → 开发者不信任文档 → 不参考文档开发 → 更不会更新文档 → 文档更加过时
这就像是一个自我实现的预言：一旦文档开始腐化，就很难再恢复它的权威性。
1.3 假如文档没更新会怎样？
卡比做了一个思想实验："假如我现在不更新文档，直接添加搜索功能会怎样？"
可能的后果：
-
AI 生成的代码可能与现有架构不一致
-
AI 只能看到 v0.2 的文档
-
生成的搜索功能可能不适配 v0.4 的分类和标签系统
-
需要大量手动调整
-
-
未来的自己无法理解决策原因
-
三个月后，卡比想优化搜索
-
但不记得为什么当初选择了客户端搜索而非服务端搜索
-
只能重新分析所有代码
-
-
功能扩展变得困难
-
如果要添加"搜索历史记录"功能
-
不知道搜索的数据结构是怎么设计的
-
容易引入不兼容的改动
-
关键洞察：
文档不是为了"记录已经做了什么"，而是为了"支持未来的演化"。