#003-让 AI 成为你的文档执行者

—— 从 Vibe-coding 到 Spec-coding 的实操指南 + 博客 v0.2 演化

系列导读：这是《用一份 .md，把想法变成产品》系列的第 3 篇。在上一篇中，我们建立了三份核心文档并实现了博客 v0.1。这一篇，我们将学习如何让 AI 真正理解并执行文档，将博客演化到 v0.2。

开篇：卡比的新挑战

v0.1 上线了，卡比很满意。一个简洁的 Landing Page，加载速度快，设计优雅，所有验收标准都达标。

但很快，卡比遇到了新问题："一个博客没有文章，总感觉少了点什么。"

于是，卡比决定在 v0.2 中添加核心功能：Markdown 文章渲染。

卡比打开电脑，准备开始新一轮开发。但这次，它没有直接让 AI 生成代码，而是先问自己三个问题：

我真的想清楚要做什么了吗？（需求是否明确？）
文档需要更新哪些部分？（intent/spec/plan 分别要改什么？）
如何让 AI 精确理解我的意图？（怎么写 Prompt？）

这就是文档驱动开发和 Vibe-coding 的核心区别：不是想到什么就让 AI 做什么，而是先思考、先规划、再执行。

今天，我们将跟随卡比，学习如何让 AI 成为可靠的文档执行者。

一、AI 协作的核心原则

在开始实际操作之前，我们需要理解 AI 协作的本质。

原则 1：AI 是字面主义者，要说"人话的机器话"

AI 不会读心术。

当你说"帮我添加文章功能"，AI 会有一百种理解方式：

理解 A：添加一个静态的文章列表页
理解 B：从数据库读取文章
理解 C：集成 WordPress API
理解 D：实现富文本编辑器

为什么会这样？ 因为 AI 只能基于你提供的信息进行推理，它无法知道你脑海中的具体画面。

解决方法：用 AI 能理解的"机器话"，但以人类自然的方式表达。

错误示例："帮我加个文章功能"

正确示例：

"基于以下需求，为博客添加 Markdown 文章渲染功能：

需求背景

文章存储在本地目录
每篇文章是一个 .md 文件
文章包含标题、日期、作者等元信息

技术约束

使用 Next.js（一个网站开发框架）
使用相应工具读取和解析文章

期望输出

文章读取工具函数
文章详情页
一个示例文章文件"

关键差异：后者提供了明确的上下文、约束条件和期望结果。

原则 2：上下文管理是关键，不要指望 AI 记住一切

AI 的记忆是有限的。即使在一次对话中，它也可能"忘记"之前说过的内容（尤其是对话很长时）。

常见问题：

第一次对话：AI 理解了你的架构
第十次对话：AI 突然生成了不符合的代码

为什么？ 因为上下文太长，早期信息被"遗忘"了。

解决方法：每次关键交互时，重新提供核心上下文。

实践技巧：

维护一份"上下文模板"，每次提问时复制粘贴：

项目背景：框架、样式、部署平台、文档位置

将三份文档作为"记忆外存"，需要时提供相关片段
分段式交互，不要在一次对话中塞太多需求：

第一次：让 AI 帮你设计数据结构
第二次：让 AI 生成读取逻辑
第三次：让 AI 生成渲染组件

原则 3：验证点前置，小步快跑好过大步返工

A：从头重写（浪费时间）
B：修修补补（技术债务）

更好的方式：在生成代码之前，先让 AI 提供"预览"或"方案概要"。

实践流程：

需求澄清阶段：让 AI 提问，确保理解一致

"我想添加文章渲染功能，请帮我澄清以下细节：文章数据来源、路由结构、是否需要分页、是否需要 SEO 优化"

方案预览阶段：让 AI 先给出架构设计

"请基于以上需求，提供技术方案的概要（不需要完整代码）：文件结构、核心函数、数据流设计"

代码生成阶段：确认方案无误后，再生成完整代码

为什么这样做？

早发现问题，成本最低
AI 也需要"迭代"，不是一次就完美
分阶段验证，降低风险

小结：这三个原则是 AI 协作的基石。记住：AI 是工具，不是魔法棒；是执行者，不是决策者；是助手，不是替代品。

二、分阶段交互模式：从 v0.1 到 v0.2 的演化

现在，我们用实际案例演示如何让 AI 帮我们实现 v0.2。

阶段 1：需求澄清

卡比的初始想法很简单："我想让博客能显示文章"。

但这个需求太模糊了。于是，卡比决定先让 AI 帮忙澄清细节。

卡比的 Prompt：

"我正在开发一个基于 Next.js 的个人博客（v0.1 已完成 Landing Page）。现在想在 v0.2 添加文章渲染功能，请帮我澄清以下问题：

当前状态

框架：Next.js 14
部署：Vercel
现有页面：首页 Landing Page

初步想法

文章用 Markdown 写，存储在本地
访问特定路径可以看到渲染后的文章
文章需要包含标题、日期、作者等元数据

需要你帮我思考的问题

文章文件应该放在哪个目录？
Markdown 元信息应该包含哪些字段？
是否需要文章列表页？
路由应该如何设计？
是否需要考虑 SEO？
是否需要代码高亮？
是否需要目录功能？

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

AI 的回应（精简版）：

AI 逐一分析了这些问题，给出了建议：

文章目录：建议放在 /content/posts/ 目录，遵循社区惯例
元信息字段：v0.2 只需四个基础字段（标题、日期、作者、摘要），其他功能后续再加
文章列表页：v0.2 暂不实现，先完成单篇渲染
路由设计：使用 /posts/文章标识的形式
SEO：强烈建议在 v0.2 就加上，每篇文章要有独立的页面标题和描述
代码高亮：建议添加，提升阅读体验
目录功能：v0.2 暂不实现，后续版本再考虑

卡比的收获：

✅ 明确了技术选型和文件组织方式
✅ 确定了元信息字段内容
✅ 识别了优先级：v0.2 先实现单篇渲染
✅ 明确了 SEO 和代码高亮的重要性

阶段 2：更新文档

有了明确的需求，卡比开始更新三份核心文档。

更新 spec.md

卡比在 spec.md 中新增了"Markdown 文章渲染"功能的详细规范：

功能描述：

用户可以访问特定路径查看单篇文章
文章内容从本地 Markdown 文件读取
支持元信息（标题、日期、作者、摘要）
支持代码块语法高亮

用户旅程：

用户通过某个链接访问文章页面
页面加载，显示文章标题、发布日期、作者信息
文章内容正确渲染，包括文本、代码块、列表等
代码块有语法高亮，易于阅读
页面响应式，移动端适配良好

验收标准：

能够正确渲染 Markdown 文件
元信息字段正确解析和显示
代码块支持语法高亮
文章详情页加载时间 < 2 秒
每篇文章有独立的 SEO 标签
不存在的文章返回 404 页面

更新 plan.md

卡比在 plan.md 中详细说明了技术实现方案：

文件存储：

文章存储在 /content/posts/ 目录
每篇文章一个 .md 文件
文件命名使用小写、连字符分隔的格式

数据读取：

创建文章读取工具函数
使用专门的工具解析 Markdown 元信息
将 Markdown 转换为 HTML

路由设计：

文章详情页路径：/posts/文章标识
所有文章页面静态生成
实现 SEO 优化的动态标签

样式设计：

使用 Tailwind Typography 插件
代码高亮使用深色主题

性能优化：

构建时静态生成所有页面
无需服务器端渲染

保持 intent.md 不变

核心意图（构建简洁、可维护的个人博客）没有变化，因此 intent.md 保持 v0.1 的内容即可。

阶段 3：生成代码

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

卡比的 Prompt：

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

spec.md** 相关部分**
[粘贴上面更新后的 spec.md v0.2 内容]

plan.md** 相关部分**
[粘贴上面更新后的 plan.md v0.2 内容]

项目背景

框架：Next.js 14
样式：Tailwind CSS
当前状态：v0.1（已有首页 Landing Page）

约束条件

使用 TypeScript
所有文章页面静态生成
确保代码可以直接运行
包含必要的错误处理

期望输出

文章读取工具函数的完整代码
文章详情页的完整代码
示例文章
需要添加的依赖

请确保代码符合最佳实践。"

AI 的工作成果：

AI 生成了以下内容：

文章读取工具函数：实现了读取单篇文章、获取所有文章列表等功能
文章详情页组件：包含文章标题、日期、作者信息和内容渲染
示例文章：一篇"Hello World"主题的 Markdown 文章
依赖列表：需要安装的工具库清单

所有代码都可以直接运行，无需修改。

三、Prompt 工程实战

在实际操作中，卡比总结了一些 Prompt 工程的技巧。

3.1 好的 Prompt 的特征

✅ 明确且具体

❌ 错误：「帮我添加文章功能」
✅ 正确：「基于 spec.md 和 plan.md，生成文章读取工具函数」

✅ 包含上下文

提供项目背景、技术栈、约束条件

✅ 设定约束

性能、安全、兼容性要求

✅ 要求示例

期望输出的具体内容和格式

3.2 Prompt 模板库

模板 A：需求澄清

我正在开发一个【项目类型】，当前版本为【版本号】。

当前状态

已实现功能
技术栈

新需求
我想在下一个版本添加【功能描述】。

需要你帮我思考的问题
1-5个具体问题

请逐一分析，并给出建议。不要直接生成代码，先帮我梳理思路。

模板 B：文档更新

请帮我更新【文档名称】，从【旧版本】到【新版本】。

变更内容

新增功能
修改功能
删除功能

原文档内容
[粘贴原文档]

期望输出
更新后的完整文档内容。

请确保：版本号正确更新、变更摘要清晰、保持格式一致

模板 C：代码生成

基于以下文档，生成【文件路径】的完整代码。

spec.md** 相关部分**
[粘贴片段]

plan.md** 相关部分**
[粘贴片段]

框架、样式、已有模块

约束条件

技术约束、性能约束

期望输出

完整代码
使用示例

请确保代码：符合项目风格、包含错误处理、可以直接运行

四、常见陷阱与解决方案

陷阱 1：AI 生成的代码不符合现有架构

问题：AI 生成了旧版本的代码，但项目使用新版本。

原因：plan.md 中没有明确说明架构约束。

解决：在 plan.md 中明确说明架构约束，包括必须使用的版本、不能使用的旧方式、文件位置等。

陷阱 2：需求理解偏差

问题：AI 生成了完整的评论系统，但你只想要文章渲染。

原因：需求描述不够具体。

解决：使用「预览模式」——先让 AI 提供技术方案的概要（文件结构、核心函数、数据流），确认方案无误后，再让 AI 生成完整代码。

陷阱 3：文档和代码不同步

问题：实现时临时修改了方案，但忘记更新 plan.md。

后果：后续开发时 AI 基于旧文档生成代码，出现不一致。

解决：建立习惯——代码改了，文档必须同步改；每次提交前检查文档是否更新。

五、工具链推荐

5.1 AI 助手选择

Claude / ChatGPT：

需求澄清
文档编写
代码审查

Cursor / GitHub Copilot：

实时代码生成
代码补全

本项目使用：Claude（需求澄清和文档编写）+ Cursor（代码生成）

5.2 文档管理

目录结构：

项目根目录/docs/

5.3 版本控制

Git 提交规范：

每次提交都清楚标注是文档更新还是功能实现：

docs: update spec.md for article rendering (v0.2)
feat: implement article detail page (v0.2)

六、博客 v0.2 最终实现

6.1 最终文件结构

项目包含以下关键部分：

首页（v0.1）
文章详情页（v0.2）
文章读取工具（v0.2）
示例文章
三份文档（已更新到 v0.2）

6.2 运行效果

访问首页：显示 Landing Page（v0.1）

访问文章：标题、日期、作者正确显示；Markdown 内容正确渲染；代码块有语法高亮；SEO 标签正确生成

访问不存在的文章：返回 404 页面

6.3 Git Commit 记录

提交历史清晰记录了开发过程：

添加示例文章
实现文章详情页
添加文章读取工具
更新 spec.md 和 plan.md（文章渲染）
实现首页
创建初始文档
初始化项目

关键观察：

文档更新先于功能实现
每个版本的文档和代码变更都有清晰的提交历史
Commit message 遵循规范

6.4 验收标准检查

验收标准	状态	说明
能够正确渲染 Markdown 文件	✅ 通过	示例文章正常显示
元信息字段正确解析和显示	✅ 通过	标题、日期、作者、摘要均正确
代码块支持语法高亮	✅ 通过	代码高亮正常
文章详情页加载时间 < 2 秒	✅ 通过	Lighthouse 测试：1.2 秒
动态生成的 SEO 标签正确	✅ 通过	title, description 标签均正确
不存在的文章返回 404 页面	✅ 通过	访问不存在的文章返回 404

结论：v0.2 所有验收标准均已达成！🎉

结语：从 Vibe-coding 到 Spec-coding

通过 v0.2 的实践，卡比深刻体会到了文档驱动开发的价值：

我们学到了什么？

1. AI 协作的本质

AI 不是魔法棒，是执行者：它按你说的做，而不是按你想的做
文档是人机协作的通用语言：清晰的文档 = 清晰的指令
小步验证比大步返工更高效：需求澄清 → 文档更新 → 代码生成，每步都要验证

2. 三个阶段的价值

阶段 1（需求澄清）：避免方向错误，降低返工成本
阶段 2（更新文档）：确保团队（或未来的自己）理解一致
阶段 3（生成代码）：让 AI 基于明确的规范工作，而不是猜测

3. Prompt 工程的重要性

好的 Prompt = 好的结果：明确、具体、包含上下文、设定约束
模板化提升效率：建立自己的 Prompt 模板库
验证点前置：让 AI 先「画草图」，确认后再「施工」

4. 常见陷阱的避免

架构不一致：在 plan.md 中明确项目规范
需求理解偏差：使用「预览模式」，先确认方案再实现
文档代码不同步：建立「文档优先」的习惯

我们收获了什么？

可见成果

✅ 一个可运行的博客 v0.2（从 Landing Page 到文章渲染）
✅ 三份完整的文档（intent.md, spec.md, plan.md）
✅ 清晰的 Git 历史（文档和代码的演化轨迹）

隐性成果

可控的演化路径：从 v0.1 到 v0.2，再到未来的 v0.3、v0.4
可追溯的决策历史：为什么选择这个技术方案？文档里都有记录
可复用的方法论：这套流程不仅适用于博客，也适用于其他项目

下一步：从 v0.2 到 v1.0

这个系列将继续探索博客的演化路径（以下为规划中的内容）：

第 4 篇（规划中）：实战案例 - 从 v0.2 到 v1.0 的完整演化
- v0.3：文章列表页 + 分页
- v0.4：分类和标签系统
- 经验总结：什么有效？什么无效？
第 5 篇（规划中）：优化迭代 - 让系统更好用
- 添加搜索功能
- 性能优化
- 用户体验提升
第 6 篇（规划中）：团队协作 - 文档驱动如何支持多人开发
- 文档的协作流程
- Code Review 与 Document Review
- 如何让新成员快速上手

最重要的是：我们不仅在学习方法论，更是在用真实项目证明它的可行性。

给读者的建议

如果你想尝试文档驱动开发，建议从小项目开始：

选择一个个人项目（如个人博客、工具网站）
写下第一份 intent.md（为什么要做这个？）
定义 v0.1 的最小功能（不要一开始就追求完美）
按照本文的三阶段流程实践（需求澄清 → 更新文档 → 生成代码）
记录问题和经验（建立自己的最佳实践）

记住：文档驱动不是为了写文档而写文档，而是为了让开发过程更可控、更可演化。

资源和链接

本系列文章：

第 1 篇：为什么我们需要文档驱动开发？
第 2 篇：三份文档，构建你的产品蓝图
第 3 篇：让 AI 成为你的文档执行者（本篇）

参考资料：

GitHub SpecKit - 规范驱动开发工具
Spec-Driven Development - 文档驱动开发指南
AI 辅助开发的最佳实践

工具推荐：

Cursor - AI 代码编辑器
Claude - AI 助手（需求澄清和文档编写）
Vercel - 部署平台

附录：完整的 Prompt 模板库

为了方便读者使用，这里提供完整的 Prompt 模板库（可直接复制使用）。

模板 A：需求澄清

我正在开发一个【项目类型】，当前版本为【版本号】。

当前状态

已实现功能：
1. 【功能 1】
2. 【功能 2】
技术栈：
- 框架：【框架名称】
- 部署：【部署平台】

新需求
我想在下一个版本（【版本号】）添加【功能描述】。

需要你帮我思考的问题

【问题 1】
【问题 2】
【问题 3】
【问题 4】
【问题 5】

请逐一分析，并给出建议。不要直接生成代码，先帮我梳理思路。

模板 B：文档更新

请帮我更新【文档名称】，从【旧版本】到【新版本】。

变更内容

新增功能：【功能描述】
修改功能：【修改说明】
删除功能：【删除说明】

原文档内容【粘贴原文档】

期望输出
更新后的完整文档内容。

请确保：

版本号正确更新
变更摘要清晰
保持格式一致
新旧功能的对应关系明确

模板 C：代码生成

基于以下文档，生成【文件路径】的完整代码。

spec.md** 相关部分**
【粘贴 spec.md 片段】

plan.md** 相关部分**
【粘贴 plan.md 片段】

项目背景

框架：【框架名称】
样式：【样式方案】
已有模块：【列举相关模块】

约束条件

【技术约束 1】
【技术约束 2】
【性能约束】
【安全约束】

期望输出

【文件 1】的完整代码
【文件 2】的完整代码
使用示例

请确保代码：

符合项目的代码风格
包含必要的错误处理
包含类型定义（如果使用 TypeScript）
包含简洁的注释
可以直接运行（无需修改）

模板 D：代码审查

请审查以下代码，检查是否存在问题。

代码
【粘贴代码】

审查重点

是否符合 plan.md 中的技术方案？
是否存在性能问题？
是否存在安全风险？
错误处理是否完善？
代码风格是否一致？
是否有更好的实现方式？

期望输出

问题清单（如果有）
改进建议（具体可操作）
修改后的代码（如果需要）

请用批判性的眼光审查，不要只说「看起来不错」。

模板 E：问题排查

我遇到了以下问题，请帮我分析原因并提供解决方案。

问题描述
【详细描述问题现象】

期望行为
【期望的正确行为】

相关代码
【粘贴相关代码片段】

已尝试的解决方案

【尝试 1】 - 结果：【失败/部分成功】
【尝试 2】 - 结果：【失败/部分成功】

环境信息

框架版本：【版本号】
浏览器：【浏览器名称】
错误日志：【粘贴错误信息】

期望输出

问题根本原因分析
解决方案（最好提供 2-3 种选择）
具体的实现代码
如何避免类似问题再次发生

使用建议：

将这些模板保存到 /docs/prompts/ 目录
每次使用时复制粘贴，填充具体内容
根据项目特点调整模板（不要生搬硬套）
积累自己的「最佳 Prompt」示例

感谢阅读到这里！ 🎉

如果你觉得这篇文章有帮助，欢迎分享给更多人。下一篇文章，我们将继续深入，展示如何将博客从 v0.2 演化到 v1.0。

让我们一起，用文档驱动的方式，构建更可控、更可演化的产品！