#004-从 v0.2 到 v1.0 的完整演化

从 v0.2 到 v1.0 的完整演化

—— 文档驱动的可控迭代实践

系列导读：这是《用一份 .md，把想法变成产品》系列的第4篇。在前三篇中，我们建立了文档驱动的理念，定义了三份核心文档,并成功实现了博客的 v0.1 和 v0.2。这一篇，我们将经历一个更完整的演化过程，见证文档如何驱动产品从简单原型走向可用系统。

开篇：卡比的新旅程

v0.2 上线后，卡比的博客已经可以渲染单篇 Markdown 文章了。访问 /posts/hello-world 能看到精美排版的内容，代码高亮正常，SEO 标签完整。

但卡比很快意识到一个问题："只有一个文章详情页，但没有入口，读者怎么发现我的文章？"

于是，卡比列出了接下来需要的功能：

文章列表页：让读者能浏览所有文章
分页功能：避免列表过长影响性能
分类系统：按主题组织文章
标签功能：多维度查找内容
搜索功能：快速定位文章
RSS 订阅：支持读者订阅更新

看着这个列表，卡比感到有些焦虑。"这么多功能，从哪里开始？优先级怎么定？万一做到一半发现方向错了怎么办？"

这时，卡比想起了文档驱动开发的核心理念："不要一次做太多，要渐进式演化。"

卡比决定：先规划版本路线，然后一步一步来。

一、版本规划：从混乱到清晰

1.1 先问自己三个问题

卡比没有急着动手，而是先整理思路：

问题 1：v1.0 的最小可用版本是什么？

回答：一个完整的博客系统，能够让读者浏览、发现、阅读文章

问题 2：从 v0.2 到 v1.0 需要哪些关键能力？

文章发现：列表页、分页
内容组织：分类、标签
功能增强：搜索、RSS（可选）

问题 3：这些功能的依赖关系是什么？

列表页 → 依赖：文章读取逻辑（v0.2 已有）
分页 → 依赖：列表页
分类/标签 → 依赖：文章读取逻辑（需扩展文章元信息）
搜索 → 依赖：列表页、分类/标签

1.2 版本规划表

基于以上分析，卡比制定了清晰的版本规划：

版本	核心功能	文档变更重点	预期完成时间
v0.3	文章列表 + 分页	spec.md: 新增列表功能 plan.md: 数据读取优化	1 天
v0.4	分类和标签系统	spec.md: 新增分类/标签筛选 plan.md: 文章元信息扩展	1 天
v0.5	搜索功能（计划中）	spec.md: 搜索交互设计 plan.md: 搜索算法选型	1 天
v0.8	性能优化 + SEO	plan.md: 缓存策略、构建优化	1 天
v1.0	完整交付	所有文档的最终版本	-

关键原则：

✅ 每个版本只做一件核心的事
✅ 每个版本都是可用的（不是半成品）
✅ 版本之间有清晰的依赖关系
✅ 文档先于代码更新

1.3 更新 intent.md

虽然核心意图没变，但卡比决定在 intent.md 中增加版本规划：

版本演化路线（v0.2 → v1.0）

短期目标（v0.3 - v0.4）

v0.3：实现文章发现机制（列表 + 分页）
v0.4：建立内容组织体系（分类 + 标签）

中期目标（v0.5 - v0.8）

v0.5：增强用户体验（搜索）
v0.8：优化性能和 SEO

长期目标（v1.0）

完整、可维护、可演化的博客系统
完善的文档支持后续扩展

为什么要更新 intent.md？

记录决策过程：为什么选择这个顺序？
给未来的自己（或团队）提供上下文
避免迷失方向：时刻提醒自己"做到哪一步了"

二、v0.3 实现：文章列表 + 分页

2.1 阶段 1：需求澄清

卡比先让 AI 帮忙澄清细节：

卡比的提问：

我的博客目前是 v0.2（已实现单篇文章渲染）。

现在想在 v0.3 添加文章列表页和分页功能，请帮我澄清以下问题：

【当前状态】

已实现：单篇文章详情页
文章存储：Markdown 文件
已有功能：读取单篇文章、解析文章信息、内容渲染

【初步想法】

首页显示文章列表（标题、摘要、日期）
按发布日期倒序排列
支持分页（每页 N 篇）

【需要你帮我思考的问题】

列表页应该放在哪个位置？（首页还是独立页面？）
每页显示多少篇文章合适？
分页路由如何设计？
是否需要"加载更多"按钮？（还是只用页码导航？）
摘要从哪里获取？（文章元信息还是正文前 N 个字？）
是否需要显示封面图？
性能考虑：如果有 100 篇文章，会不会影响构建时间？

请逐一分析，并给出建议。

AI 的回应（精简版）：

很好的问题！让我逐一分析：

路由建议：首页作为列表页
- 理由：这是博客的标准做法，用户期望首页看到文章
- 原来的欢迎页面可以保留在关于页面或直接合并到列表页顶部
每页文章数：建议 10 篇
- 理由：平衡加载速度和浏览体验
- 移动端可以考虑减少到 5-8 篇
分页路由：建议使用页码路径
- 理由：SEO 友好，URL 更清晰
- 首页是第一页，第二页、第三页用独立路径
导航方式：页码导航优于"加载更多"
- 理由：博客通常内容稳定，不像社交媒体需要无限滚动
- 页码导航 SEO 更友好，用户可以直接跳转到任意页
摘要来源：优先使用文章元信息中的描述
- 理由：作者可以精心编写摘要，比自动截取更准确
- 备选方案：如果没有描述，则截取正文前 150 字
封面图：v0.3 暂不实现
- 理由：增加复杂度，v0.4 或 v0.5 再考虑
- 可以在文章元信息中预留封面字段
性能考虑：
- 100 篇文章不会有明显影响（构建时间约 10-30 秒）
- 建议在文档中记录性能基准，超过阈值时再优化

卡比的收获：

✅ 明确了技术选型：首页作列表页，使用页码路径
✅ 确定了交互方案：页码导航，每页 10 篇
✅ 识别了潜在风险：性能问题（暂时不严重，但需监控）

2.2 阶段 2：更新文档

更新 spec.md

卡比在 spec.md 中添加：

博客规范文档 v0.3

版本说明

基于 v0.2，新增文章列表和分页功能
v0.2 的文章渲染功能保持不变

功能清单

新增功能

1. 文章列表页（首页）

功能描述：

显示所有已发布的文章
按发布日期倒序排列（最新的在最前面）
每篇文章显示：标题、摘要、发布日期、作者

路由：

首页：显示第一页
分页：使用页码路径（如第2页、第3页）

分页规则：

每页显示 10 篇文章
显示页码导航（上一页、页码、下一页）
当前页高亮显示

摘要显示规则：

优先使用文章元信息中的描述字段
如果没有描述，则截取正文前 150 个字
摘要末尾添加"..."省略号

用户旅程

旅程 1：浏览文章列表

用户访问首页
看到最新文章列表（10 篇）
滚动查看更多文章
点击"下一页"或页码查看更多
点击文章标题进入详情页

旅程 2：直接访问某一页

用户通过搜索引擎或收藏链接访问第3页
看到第 3 页的文章列表
可以通过页码导航到其他页

验收标准

功能性标准

首页正确显示最新 10 篇文章
文章按日期倒序排列
摘要正确显示（优先使用描述）
分页链接正确生成
页码导航正常工作（上一页、下一页、页码跳转）
当前页高亮显示
点击文章标题能跳转到详情页

性能标准

列表页加载时间 < 1.5 秒
构建时间 < 30 秒（假设 50 篇文章）
页面性能分数 > 90

视觉标准

响应式设计，移动端适配良好
页码导航在移动端不换行
文章卡片间距合理，易于区分

SEO 标准

每个分页都有独立的元标签
标题格式：网站名 - 第 N 页（第一页除外）
正确设置规范网址
添加前一页和后一页的链接关系

更新 plan.md

博客技术方案 v0.3

版本说明

基于 v0.2，新增文章列表和分页功能
技术栈保持不变

技术方案

1. 文章数据读取

扩展现有的文章读取工具：

新增功能：

获取所有文章（带分页）
获取文章总数
生成所有分页路径（用于静态生成）

性能优化：

构建时一次性读取所有文章元信息
缓存解析结果，避免重复读取

2. 路由设计

首页（列表第一页）：

显示最新 10 篇文章

分页页面：

显示对应页码的文章

静态生成：

构建时预生成所有分页

3. 组件设计

新增组件：

文章列表组件
- 接收：文章数组、当前页码、总页数
- 功能：渲染文章卡片列表
文章卡片组件
- 接收：文章信息（标题、描述、日期、作者、路径）
- 功能：显示文章摘要信息
分页导航组件
- 接收：当前页码、总页数
- 功能：生成页码链接、上一页/下一页按钮

组件关系：

首页包含文章列表
文章列表包含多个文章卡片和分页导航

4. 数据流

构建时：

读取所有文章文件
解析文章元信息，生成文章列表
按日期排序
计算总页数
为每一页生成静态 HTML

运行时（用户访问）：

返回预生成的静态页面
无需服务器端渲染（纯静态）

5. SEO 优化

每个分页的元信息：

标题：首页用站点名，其他页添加页码
描述：统一使用站点描述
规范网址：指向当前页
链接关系：添加前一页和后一页的链接

6. 性能基准

目标：

首页加载时间：< 1.5 秒
构建时间（50 篇文章）：< 30 秒
页面性能分数：> 90

如果超过阈值：

考虑增量构建
优化图片加载（如果将来添加封面图）
使用 CDN 加速

2.3 阶段 3：AI 生成代码

有了明确的文档，卡比开始让 AI 生成代码。

卡比的请求：

基于以下文档，为博客项目生成 v0.3 的完整代码。

【spec.md 相关部分】
[粘贴上面的 spec.md v0.3 内容]

【plan.md 相关部分】
[粘贴上面的 plan.md v0.3 内容]

【当前项目结构】

首页：当前是简单的欢迎页面
文章详情页：已完成（v0.2）
文章读取工具：已完成（v0.2）
文章内容：存储为 Markdown 文件

【约束条件】

使用现代前端框架
使用样式框架
保持与现有代码风格一致
确保类型安全

【期望输出】

更新后的文章读取工具（新增列表和分页函数）
更新后的首页（列表页）
新增的分页页面
新增的文章列表组件
新增的文章卡片组件
新增的分页导航组件

请确保代码：

可以直接运行，无需修改
包含必要的错误处理
包含类型定义
包含简洁的注释

AI 会根据这些文档和要求，生成完整的代码实现。

2.4 阶段 4：验证和测试

卡比按照 spec.md 的验收标准逐一检查：

功能测试：

✅ 首页显示最新 10 篇文章
✅ 文章按日期倒序排列
✅ 摘要正确显示
✅ 分页链接正确
✅ 页码导航正常工作
✅ 点击标题跳转到详情页

性能测试：

页面性能分数：

性能：95
可访问性：100
最佳实践：100
SEO：100

构建时间（20 篇文章）：12.3 秒

视觉测试：

✅ 移动端适配良好
✅ 页码导航不换行
✅ 文章卡片间距合理

结果：v0.3 所有验收标准均通过！ 🎉

三、v0.4 实现：分类和标签系统

3.1 快速更新文档

有了 v0.3 的经验，v0.4 的文档更新变得更快了。

spec.md** 新增（节选）**：

功能：分类和标签

分类（Category）

每篇文章属于一个分类（如"技术"、"生活"、"方法论"）
用户可以查看某个分类下的所有文章
路由：/category/[slug]

标签（Tag）

每篇文章可以有多个标签（如"Next.js"、"React"、"文档驱动"）
用户可以查看某个标签下的所有文章
路由：/tag/[slug]

分类/标签列表

首页侧边栏显示所有分类和热门标签
点击后进入对应的筛选页面

plan.md** 新增（节选）**：

Frontmatter 扩展

在每篇文章的开头，添加文章的分类和标签信息。例如，一篇技术文章可以这样标记：

标题：文章标题
日期：发布日期
作者：卡比
描述：文章摘要
分类：技术（新增）
标签：Next.js、React（新增）

实现方式

1. 数据结构

文章的基本信息需要扩展，新增分类和标签字段：

文章路径
标题
日期
作者
描述
分类（新增）
标签数组（新增）
正文内容

2. 新增工具函数

需要添加以下功能：

获取所有分类列表
根据分类筛选文章
获取所有标签列表
根据标签筛选文章

3.2 遇到问题：构建时间过长

卡比按照文档让 AI 生成了代码，但在构建时发现：

构建时间过长，超过了 30 秒的阈值！

问题分析：

每个分类/标签页都需要读取所有文章并筛选
如果有 10 个分类、50 个标签，就需要读取 60 次
没有缓存机制，每次都重新解析 Markdown

回溯文档：

卡比回到 plan.md，发现性能优化部分写得不够具体。原来的文档只是简单地说："需要优化性能，避免重复读取文件。" 这样的描述太笼统，AI 无法理解具体应该怎么实现缓存机制。

问题：这个描述太笼统了，AI 没有生成实际的缓存逻辑。

3.3 更新 plan.md 并重新生成

卡比更新了 plan.md：

性能优化方案

问题：构建时间过长

原因：每个分类/标签页都重复读取和解析文章
目标：将构建时间控制在 30 秒以内（50 篇文章）

解决方案：构建时缓存

实现步骤：

在构建开始时，一次性读取所有文章
所有读取函数都使用缓存
预生成索引数据

预期效果

构建时间：< 25 秒（50 篇文章）
内存占用：< 100 MB

重新生成代码：

结果：成功优化，构建时间缩短！

3.4 经验总结：文档的精确度很重要

这次问题让卡比意识到：

❌ 模糊的文档 → AI 生成模糊的代码
✅ 精确的文档 → AI 生成精确的代码

改进原则：

在 plan.md 中，关键技术点要写清楚"如何实现"
遇到性能问题，先回溯文档，看是否有遗漏
更新文档后再重新生成代码，而不是直接修改代码

四、Git 历史：文档和代码的演化轨迹

卡比每次更新都遵循"文档先行"的原则，Git 历史清晰记录了这一过程：

观察关键模式：

文档优先：每个功能之前都有 docs: 提交
小步提交：每个功能拆分为多个小 commit
优化独立：性能优化也有对应的文档更新
可回溯：任何时候都可以回到某个版本查看当时的文档和代码

如何利用 Git 历史：

查看某个版本的文档
对比不同版本的差异
回到某个版本（如果有问题）

五、经验总结：什么有效？什么无效？

5.1 什么有效 ✅

1. 版本规划降低了焦虑

场景：看到一堆功能列表时，卡比不再手忙脚乱。

方法：

先列出所有想要的功能
按依赖关系排序
定义每个版本的核心目标
一次只做一件事

效果：

方向清晰，不会做到一半改主意
每个版本都能交付，成就感强
容易向他人（或自己）解释进展

2. 文档先行避免了返工

场景：v0.4 构建时间过长，卡比没有直接改代码，而是先回溯文档。

方法：

发现问题 → 定位是需求问题还是实现问题
需求问题 → 更新 spec.md
实现问题 → 更新 plan.md
重新生成代码

效果：

避免了"头痛医头、脚痛医脚"
文档和代码保持同步
问题的根本原因被记录下来

3. AI 协作效率大幅提升

数据对比：

任务	纯手写	文档驱动 + AI	提升比例
v0.3 实现	约 4-6 小时	约 1.5 小时	70%
v0.4 实现	约 5-7 小时	约 2 小时	65%
性能优化	约 2-3 小时	约 30 分钟	80%

关键原因：

明确的文档让 AI 减少了"猜测"
分阶段交互减少了"返工"
Prompt 模板提高了"首次成功率"

5.2 什么无效 ❌

1. 过度细化的文档反而降低效率

错误示例：

卡比一开始在 plan.md 中写了非常详细的代码结构：

问题：

文档写得太像代码，失去了"规范"的意义
AI 生成的代码几乎和文档一模一样，没有发挥 AI 的能力
后续修改时，文档和代码需要双倍维护

改进：

plan.md 应该描述"做什么"，而不是"怎么做"。

更好的写法：

描述需要实现的功能和目标，而不是具体的代码细节。例如：

目标：避免重复读取文章文件
需求：在构建时缓存所有文章数据
效果：提升构建速度，减少文件 I/O

而不是写成：

创建一个全局缓存对象
定义缓存的键值结构
实现缓存的读写逻辑

这样 AI 可以根据目标自主选择最优的实现方案，而不是被限制在某种特定的写法中。

2. 没有及时更新文档导致后续混乱

场景：

卡比在实现 v0.3 时，临时修改了分页逻辑（从每页 10 篇改为 15 篇），但忘记更新 spec.md。

后果：

实现 v0.4 时，AI 生成的代码仍然按 10 篇分页
测试时发现不一致，花了 20 分钟排查问题
最后发现是文档没更新

教训：

代码改了，文档必须同步改
建立习惯：每次 PR / commit 前检查文档是否更新
可以用 Git hooks 强制检查（如果文件改了，docs/ 必须有变动）

3. 企图一次做太多功能

错误尝试：

卡比一开始想在 v0.3 同时实现：

文章列表 ✅
分页 ✅
分类 ❌
标签 ❌
搜索 ❌

结果：

文档写得很复杂，AI 理解困难
生成的代码有很多耦合
测试时发现问题，难以定位

改进：

v0.3 只做列表 + 分页
v0.4 单独做分类 + 标签
v0.5 再做搜索

原则：每个版本只有一个核心目标。

5.3 改进建议

1. 建立文档模板库

卡比整理了一套自己的模板：

文档模板目录结构：

意图文档模板
规范文档模板
方案文档模板
版本更新检查清单

version-update.md** 示例**：

版本更新检查清单

每次发布新版本前，检查以下事项：

文档更新

spec.md 已更新需求
plan.md 已更新技术方案
intent.md 已更新（如需要）
变更摘要已记录

代码实现

所有功能已实现
单元测试已通过
集成测试已通过
性能测试已通过

验收标准

Lighthouse 分数达标
无明显 bug

Git 提交

文档提交在前（docs: ...）
功能提交在后（feat: ...）
Commit message 符合规范

部署

本地构建成功
Vercel 预览链接正常
生产环境部署成功

2. 定期回顾和重构文档

问题：随着版本迭代，文档会变得越来越长、越来越乱。

解决：

每 2-3 个版本，抽时间"重构"文档
删除过时的内容
合并重复的描述
调整结构，使其更易读

示例：

v0.5 时，卡比发现 spec.md 已经有 500 行，很难阅读。于是进行了重构：

重构前
spec.md（v0.5）：500 行，所有版本的功能堆在一起

重构后

spec.md（v1.0）：150 行，只保留当前版本的功能
docs/archive/spec-v0.1.md：归档的 v0.1 规范
docs/archive/spec-v0.2.md：归档的 v0.2 规范
docs/archive/spec-v0.3.md：归档的 v0.3 规范

3. 使用 Checklist 提高质量

在每个阶段引入检查点：

阶段 1（需求澄清）：

AI 已提供明确的建议
我已理解所有关键决策
有疑问的地方已讨论清楚

阶段 2（文档更新）：

spec.md 已更新需求
plan.md 已更新技术方案
intent.md 已更新（如需要）

阶段 3（代码生成）：

Prompt 包含完整上下文
约束条件已明确
AI 生成的代码可以直接运行

阶段 4（验证测试）：

功能测试通过
性能测试通过
视觉测试通过
文档和代码一致

六、从 v0.4 到 v1.0 的路线图

现在，卡比的博客已经有了：

✅ v0.1：静态 Landing Page
✅ v0.2：文章渲染
✅ v0.3：文章列表 + 分页
✅ v0.4：分类和标签

接下来的规划：

版本	核心功能	预估工作量	状态
v0.5	搜索功能	1-2 天	计划中
v0.6	评论系统（可选）	1-2 天	计划中
v0.7	RSS 订阅	半天	计划中
v0.8	性能优化 + SEO 增强	1 天	计划中
v0.9	用户体验优化	1 天	计划中
v1.0	完整交付 + 文档整理	1 天	计划中