#001-为什么我们需要文档驱动开发？

为什么我们需要文档驱动开发？

—— 重新思考 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 生成代码，而是先写了三份文档：

intent.md：为什么要做这个博客？核心价值是什么？
spec.md：博客需要哪些功能？用户如何使用？
plan.md：用什么技术实现？架构如何设计？

有了这三份文档后，卡比再让 AI 生成代码。这次的体验完全不同：

✅ 代码完全符合预期（因为 AI 有了清晰的参考）
✅ 需要修改时，先更新文档，再生成代码（保持一致性）
✅ 后续迭代时，AI 能理解历史决策（文档是记忆）
✅ 新功能可以无缝融入（因为架构是可演化的）

这就是文档驱动开发的力量。

二、什么是文档驱动开发？

核心定义

文档驱动开发（Document-Driven Development）的核心理念是：

Documentation is the source of truth.

文档是产品的单一真实来源（Single Source of Truth），代码是文档的实现，而非反过来。

这听起来和传统的"先写文档再写代码"没什么区别？其实不然。关键在于三个不同：

1. Living Documents vs. Static Docs

传统文档（静态文档）：

写完就扔在一边，几乎不更新
和代码脱节，没人相信文档
文档是负担，是"必须完成的任务"

文档驱动中的文档（活文档）：

随着项目演化而持续更新
文档和代码同步提交，始终一致
文档是生产力工具，是"思考的外化"

一个真实的对比：

传统模式下，当你问："这个功能为什么这么设计？"，可能的回答是："不知道，当时的人已经离职了，代码里也没注释。"

文档驱动模式下，答案在 intent.md 里写得清清楚楚："因为我们的目标用户是技术博主，他们需要一个极简的写作环境，所以我们放弃了复杂的富文本编辑器，选择 Markdown。"

2. 迭代 + 规范 = 可控演化

文档驱动开发不是瀑布模型的复活，而是敏捷开发的增强版。

敏捷开发强调：

快速迭代，小步快跑
拥抱变化，响应需求
工作软件优于详尽文档

文档驱动开发在此基础上补充：

每次迭代前，先更新文档（明确意图）
拥抱变化，但变化要有文档支持（可追溯）
工作软件 + 清晰文档 = 可持续演化

公式：

敏捷开发 = 快速迭代 + 拥抱变化
文档驱动 = 敏捷开发 + 意图明确 + 可追溯演化

3. 从"记录"到"设计"

传统文档是记录：代码写完了，补一份文档交差。

文档驱动是设计：文档是思考的过程，写文档的过程就是设计的过程。

举个例子：

传统模式：

1. 写代码（边写边想，遇到问题现场决策）
2. 写完了，补一份 README
3. 过几个月，README 过时了，没人更新

文档驱动：

1. 写 intent.md（为什么做？核心价值？）
2. 写 spec.md（做什么？功能清单？）
3. 写 plan.md（怎么做？技术方案？）
4. 基于文档生成代码
5. 发现问题 → 回溯到对应文档 → 修正文档 → 重新生成代码

在这个过程中，文档不是负担，而是思考的脚手架。

三、AI 时代为什么需要文档驱动？

1. AI 擅长模式识别，不擅长心智解读

AI 本质上是一个超级模式匹配器。你给它一个 Prompt，它会在海量训练数据中寻找最匹配的模式，然后生成代码。

问题是：你脑子里的想法，AI 读不到。

当你说"我想要一个简洁的博客"，AI 会生成一个它认为"简洁"的博客。但你的"简洁"可能是：

没有侧边栏
只有黑白两色
只显示标题和日期，没有摘要

而 AI 的"简洁"可能是：

有侧边栏，但只有三个按钮
浅灰色背景 + 深灰色文字
显示标题、日期、作者、标签、阅读时间

解决方案：把你的意图写成文档，AI 就能精确理解。

2. 规范是人机协作的通用语言

把 AI 想象成一个非常聪明但没有心智的"字面主义者"。你说什么，它就理解成什么。

传统协作（人和人）：

可以靠"默契"理解对方
可以通过"追问"澄清需求
可以从"语气"判断优先级

AI 协作（人和机器）：

没有默契，只有规则
不会追问，只会按字面理解
不懂语气，只看明确指令

文档就是这个"通用语言"。它把人类模糊的意图，转化为机器可理解的结构化信息。

3. 生成容易，演化难——演化才是核心竞争力

这是本系列的核心命题：

生成是廉价的，可控的演化才是稀缺的。

现在，让 AI 生成一个初版代码非常容易。但是：

一个月后，你想加新功能，AI 还能保持架构一致吗？
三个月后，你发现初期的技术选型有问题，能平滑迁移吗？
半年后，新同事接手项目，能快速理解设计思路吗？

没有文档：每次迭代都像在沼泽里行走，不知道下一步会踩到什么。

有文档：每次迭代都有清晰的路径，知道从哪里来，要到哪里去。

真实案例：

卡比的博客经过 6 个月，从 v0.1 演化到 v1.0：

v0.1：静态 Landing Page
v0.2：添加 Markdown 文章渲染
v0.3：文章列表 + 分页
v0.4：分类和标签系统
v0.5：搜索功能
v0.8：多作者支持 + SEO 优化
v1.0：性能优化 + 国际化

每一次演化，卡比都是先更新文档，再让 AI 生成代码。

结果：v1.0 的代码库依然清晰、一致、易维护，就像是一次性设计出来的一样。这就是"可控演化"的力量。

四、文档驱动的三个适用场景

文档驱动开发不是万能的，但在以下三个场景特别有效：

1. 从零到一：新项目启动

典型场景：你有一个新点子，想快速验证可行性。

为什么适合文档驱动：

早期方向不明确，容易走偏（文档帮你明确意图）
AI 生成代码速度快，但容易生成"看起来对实际不对"的代码（文档是质量保障）
需要快速迭代，但不能失控（文档提供可追溯性）

卡比的博客就是这个场景：

用一周时间写清楚三份文档
然后用两周时间完成 v1.0
整个过程完全可控，没有返工

2. 功能迭代：现有系统扩展

典型场景：产品已经运行一段时间，现在要加新功能。

为什么适合文档驱动：

新功能容易破坏现有架构（文档作为参考，保持一致性）
需求可能和老功能冲突（在文档层面就能发现问题）
新人不熟悉历史决策（文档是知识库）

案例：

v0.4 添加"分类和标签"时，卡比先更新了 spec.md 和 plan.md
AI 基于文档生成的代码，完美融入了现有架构
没有破坏性改动，没有技术债务

3. 遗留重构：技术债务清理

典型场景：老项目堆积了大量技术债，需要重构。

为什么适合文档驱动：

老代码的设计意图已不可考（通过文档重建意图）
重构容易破坏现有功能（文档作为功能清单）
需要渐进式迁移（文档规划迁移路径）

注意：这个场景比较复杂，本系列不会深入展开。但核心思路是：先把现状文档化，再用文档指导重构。

五、项目启动：写下第一份 intent.md

理论讲完了，让我们动手实践。

在接下来的系列文章中，我们会从零开始构建一个真实的个人博客。第一步，就是写下这个项目的 intent.md（意图文档）。

什么是 intent.md？

intent.md** 是项目的"宪法"**，它回答三个核心问题：

为什么做？（Why）
为谁做？（Who）
成功是什么样？（Success Criteria）

注意：intent.md** 不回答"怎么做"**。它只关注意图，不关注实现。

博客项目的 intent.md

让我们看看卡比为这个博客项目写的 intent.md：

# 个人技术博客 - 项目意图文档

## 项目愿景

构建一个简洁、优雅、易于维护的个人技术博客，用于分享技术见解和方法论实践。

这不仅是一个博客，更是**文档驱动开发方法论的实践案例**。通过这个项目，展示如何用 .md 文件驱动整个产品从想法到交付的全过程。

## 目标用户

### 主要用户：我自己（内容创作者）
- 需要一个专注写作的环境，没有复杂的后台管理
- 希望文章内容完全由自己掌控（Markdown 文件存储）
- 需要快速发布（写完文章推送到 Git 就自动部署）

### 次要用户：技术社区读者（内容消费者）
- 希望快速找到感兴趣的文章（搜索、分类、标签）
- 期望良好的阅读体验（加载快、排版好、响应式）
- 可能想要评论和互动（但不是核心需求）

## 核心问题

### 为什么不用现成的博客平台？

- **Medium / 掘金 / CSDN**：平台规则可能变化，内容不完全属于自己
- **WordPress / Ghost**：功能太重，维护成本高
- **Hexo / Hugo**：静态生成器不错，但主题定制复杂

### 我真正需要什么？

1. **完全掌控**：内容、设计、技术栈都由我决定
2. **简单维护**：不想花时间折腾后台，专注写作
3. **可持续演化**：能根据需求逐步添加功能，不被架构限制
4. **方法论实践**：用这个项目证明文档驱动开发的有效性

## 成功标准

### 功能标准
- ✅ 能够快速添加新文章（从写作到发布 < 5分钟）
- ✅ 文章渲染美观（代码高亮、数学公式、图片优化）
- ✅ 搜索友好（SEO 优化、sitemap、结构化数据）
- ✅ 可扩展架构（未来可添加评论、多作者、国际化等）

### 性能标准
- ⚡ 首屏加载时间 < 2秒
- ⚡ Lighthouse 分数 > 90
- ⚡ 移动端体验优秀

### 代码标准
- 📝 代码总量 < 5000 行（保持简洁）
- 📝 测试覆盖率 > 80%
- 📝 所有功能都有完整文档支持

### 文档标准（这是关键！）
- 📄 每个版本都有对应的 intent.md、spec.md、plan.md
- 📄 文档和代码同步演化，始终保持一致
- 📄 任何人看文档就能理解设计决策

## 非目标

明确我们**不做什么**同样重要：

- ❌ 不做社交功能（关注、点赞、私信）
- ❌ 不做付费订阅（这不是商业博客）
- ❌ 不做复杂的后台管理（文件系统就是后台）
- ❌ 不追求功能全面（只做必需的）

## 时间线

- **Week 1-2**：v0.1 - v0.2（基础架构 + 文章渲染）
- **Week 3-4**：v0.3 - v0.4（列表、分类、标签）
- **Week 5-6**：v0.5 - v0.8（搜索、性能优化）
- **Week 7-8**：v1.0（完整交付 + 文档整理）

---

**最后更新**：2025-01-15
**文档版本**：v1.0
**负责人**：卡比（Capybara Dev）