#002-三份文档，构建你的产品蓝图

—— intent.md、spec.md、plan.md 的设计哲学 + 博客 v0.1 实现

系列导读：这是《用一份 .md，把想法变成产品》系列的第2篇。在上一篇中，我们理解了文档驱动开发的核心理念。这一篇，我们将真正动手，用三份文档构建博客的第一个版本。

开篇：从混沌到秩序

还记得卡比（我们的卡皮巴拉主角）吗？在上一篇中，它经历了三次失败的尝试，最后发现了文档驱动开发的力量。

现在，卡比站在一个新的起点。它手里拿着一份初步的 intent.md，但问题来了：

• 只有 intent.md 够吗？ 不够。意图很清晰，但具体要做什么功能？用户如何使用？
• 要不要直接写技术方案？ 太早了。还没想清楚"做什么"，就开始想"怎么做"，容易南辕北辙。
• 需要写多少文档？ 写太少，指导不足；写太多，维护成本高。

这时候，文档驱动开发的经典答案浮现了：三份文档，不多不少，刚刚好。

今天，我们将深入理解这三份文档的设计哲学，并基于它们，让 AI 帮我们生成博客的第一个版本：v0.1 - 一个优雅的 Landing Page。

一、为什么是三份，不是一份或五份？

1. 认知负载理论：分层思考降低复杂度

人类的大脑有个特点：不擅长同时处理多层次的复杂信息。

当你试图在一份文档里同时回答"为什么做、做什么、怎么做"，你会发现：

• 写的时候思绪混乱，不知道该聚焦哪个层面
• 读的时候抓不住重点，从宏观愿景跳到具体代码细节
• 维护的时候牵一发动全身，改个技术细节可能影响整体意图

三份文档的设计，本质上是一种认知负载的分层管理：

类比：就像盖房子，你需要三份图纸：

• 设计理念（为什么要盖这栋房子？给谁住？）→ intent.md
• 户型图（有几个房间？布局如何？）→ spec.md
• 施工图（用什么材料？如何施工？）→ plan.md

如果把这三份图纸混在一起，建筑师会疯掉。

2. 职责分离：不同文档服务不同决策点

在产品开发的不同阶段，我们需要做不同的决策：

早期阶段（立项）：

• 决策问题："这个项目值得做吗？"
• 参考文档：intent.md
• 决策者：创始人、产品负责人

需求阶段（设计）：

• 决策问题："用户需要哪些功能？"
• 参考文档：spec.md
• 决策者：产品经理、设计师

开发阶段（实现）：

• 决策问题："用什么技术方案？"
• 参考文档：plan.md
• 决策者：技术负责人、开发者

三份文档，各司其职，不越界、不缺位。

3. 演化灵活性：上层稳定，下层可变

产品开发是一个动态过程，需求会变，技术会变，但核心价值不会轻易变。

三份文档的稳定性递减：

intent.md  (最稳定，几乎不变)
    ↓
spec.md    (中等稳定，小幅调整)
    ↓
plan.md    (最灵活，经常优化)

举个例子：
卡比的博客项目，从 v0.1 到 v1.0：

• intent.md：几乎没变（核心愿景始终是"简洁、优雅、可演化"）
• spec.md：增加了功能（搜索、多作者、SEO），但核心用户旅程不变
• plan.md：改了好几次（从纯静态到增量生成，从本地搜索到 Algolia）

这种"上层稳定、下层灵活"的架构，让项目能够应对变化，而不失去方向。