为什么我们需要文档驱动开发？
—— 重新思考 AI 时代的开发范式
系列导读：这是《用一份 .md，把想法变成产品》系列的第1篇。在这个系列中，我们不仅会讨论文档驱动开发的方法论，更会从零开始构建一个真实的博客系统。跟随卡皮巴拉的旅程，你将学会如何用文档驱动的方式，让 AI 成为你可靠的开发伙伴。
开篇：卡皮巴拉的困境
让我给你讲个故事。
有一只叫卡比的卡皮巴拉，它是一名开发者（是的，水豚也会写代码）。某天，它突然有了一个想法："我要做一个个人博客，分享我在池塘边的技术思考！"
于是，卡比打开了最新的 AI 编程助手，兴奋地输入：
"给我生成一个个人博客！"
几秒钟后，AI 哗啦啦吐出了一大堆代码。卡比激动地复制粘贴，运行……然后，懵了。
代码能跑，但这不是它想要的博客。样式是 Bootstrap 4（它想要 Tailwind），数据库是 MySQL（它只想用 Markdown 文件），评论系统用的是 Disqus（它想要更轻量的方案）。更糟糕的是，代码结构非常混乱，想改却不知道从哪里下手。
这是 AI 时代开发的第一个困境：生成容易，但不一定是你想要的。
一、当前开发模式的困境：Vibe-coding 的三次失败
让我们跟随卡比的三次尝试，看看传统的"边想边做"模式在 AI 时代遇到了什么问题。
第一次尝试：直接让 AI 生成
卡比的做法：
Prompt: "用 Next.js 做一个个人博客，要有文章列表、详情页、分类功能。"
结果：AI 生成了代码，但是……
-
使用了 Pages Router（卡比想要 App Router）
-
文章内容存在 Prisma + PostgreSQL（卡比只想用 Markdown 文件）
-
样式用的是 CSS Modules（卡比更习惯 Tailwind CSS）
-
包含了一大堆不需要的功能（RSS、Newsletter、暗黑模式……）
更要命的是，当卡比想要修改时，发现代码高度耦合，改一处牵扯一大片。最后只能推倒重来。
问题根源：AI 不知道你的真实意图，只能根据常见模式生成"看起来合理"的代码。
第二次尝试：详细描述需求
卡比吸取教训，这次写了一个超级详细的需求文档，足足 2000 字，涵盖了：
-
技术栈（Next.js App Router + Tailwind CSS + TypeScript）
-
数据存储（本地 Markdown 文件 + frontmatter）
-
功能清单（文章列表、详情、分类、标签、搜索）
-
性能要求（首屏加载 < 2s）
-
设计风格（极简、优雅、响应式）
这次 AI 生成的代码质量好多了，技术栈对了，架构也基本符合预期。
但新问题出现了：
-
无法演化：当卡比想添加"作者系统"时，发现需要大改数据结构，牵一发动全身。
-
需求理解偏差：AI 对"极简"的理解和卡比不一样，生成的页面过于简陋。
-
缺乏上下文：后续迭代时，AI 记不住之前的决策，每次都要重新解释一遍架构。
问题根源：需求文档只是"一次性输入"，没有形成可持续演化的知识体系。
第三次尝试：文档驱动开发
这次，卡比改变了策略。它没有急着让 AI 生成代码，而是先写了三份文档：