Vibe Coding 深度解析：工作流、胶水编程与 Spec-Driven Development

上一篇讲了 Vibe Coding "是什么"和"为什么"。这篇讲"怎么做"------从新手最容易犯的错误出发，拆解三个核心方法论：工作流设计、胶水编程思维、以及 Spec-Driven Development。

两种路径：为什么"直接写代码"会失败

在深入方法论之前，先看一个对比。

新手路径（会导致屎山）

复制代码

提需求 → AI 生成代码 → 报错 → 把报错丢给 AI → AI 瞎改 → 代码越来越乱

这个路径的问题不出在 AI，出在人没有给 AI 任何结构。AI 每次都只能看到当前的报错和当前的代码，它不知道：

这个项目的整体架构是什么？
这段代码在整个系统中扮演什么角色？
上一次为什么改了这个地方？

没有上下文 = 没有约束 = 随机修改 = 屎山累积。

Vibe Coding 路径

复制代码

提需求 → 生成设计文档 → 确认技术栈 → 划定功能边界 → 模块拆分 → 定义数据流 → AI 按计划写代码

每一步产出文档，文档就是你和 AI 之间的契约。AI 不记得上次说了什么？文档记得。

核心原则：先让 AI 写文档，再让 AI 写代码。 规划阶段禁止输出代码。

一、工作流模型：给 AI 搭好轨道

1.1 基础四步循环

这是所有复杂工作流的底层结构：

markdown 复制代码

Prompt（设计意图）→ Generate（AI 生成初稿）→ Review（人工审查）→ Refine（精准迭代）
     ↑                                                                    |
     └────────────────────────────────────────────────────────────────────┘

每个环节的关键要点：

阶段	做什么	常见错误
Prompt	用结构化提示描述意图：上下文（Context）+ 约束（Constraints）+ 示例（Examples）+ 输出格式（Output Format）	"帮我做一个登录页"（一句话，无约束）
Generate	AI 产出初稿。这是草稿，不是成品。预期会有过度抽象、幻觉引入、边界遗漏等典型问题	拿到代码直接用，不审查
Review	这是人类贡献价值最高的环节。五维度审查：安全性、正确性、性能、可维护性、可访问性	只看功能通不通，不看代码质量
Refine	精准迭代，不要推倒重来。明确指定函数名、行号、当前错误行为、期望行为	"全部重写一遍"（丢了上下文，引入新问题）

1.2 RIPER 模型（阿里云实践）

这是对基础循环的升级，增加了对齐和验收两个关键环节：

阶段	英文	中文	关键动作
R	Research	调研与意图锁定	让 AI 反向复述你的需求，澄清边界。确认 AI 理解正确前，不进行下一步。
I	Innovate	设计与推演	AI 生成技术方案草案。强制互问互答------AI 问你不清楚的地方，你问 AI 方案的风险。引入外部参考。
P	Plan	规划与契约	明确文件路径、方法签名、Mock 数据、分步执行计划。这是"合同"签署环节。
E	Execute	执行与编码	分步指令实施，每步完成后自检。不跳过任何一个检查。
R	Review	验收与对齐	新会话 / 换模型进行"法医式审查"。以 Spec 为准绳验证 Diff。

配套的 LAFR 故障排查协议：

Locate --- 定位问题文件/函数
Analyze --- 判断是执行层错误（代码写错了）还是设计层错误（Spec 写错了）
F ix --- 先改文档再改代码（否则代码改了文档没改，下次 AI 还会犯同样的错）
Record --- 留痕，防止同一个坑掉进去两次

1.3 ISPI 四层规范模型（腾讯云实践）

这套模型专门解决复杂重构场景中人与 AI 的"意图对齐"问题：

层级	名称	核心目标	关键产出
Layer 1	Intent Definition（意图定义）	明确"为什么做"和"为什么不做"	硬性约束清单、验证标准
Layer 2	Structure Analysis（结构分析）	分析现状偏差，定位问题	职责偏差分析、数据流偏差分析
Layer 3	Plan Design（方案设计）	多方案对比，制定技术方案	3 个备选方案 + Pros/Cons + 架构护栏
Layer 4	Implement Checklist（行动清单）	可执行的行动清单	分阶段/分模块/分优先级的改动清单 + 回滚预案

关键发现 ：在腾讯的实战案例中，一个重构任务之前两次手写重构各耗时两周仍未解决本质问题，采用 ISPI 模型驱动后一周完成重构------70% 的时间花在规范定义上，但实现效率大幅提升。

二、胶水编程：拼乐高，不造零件

2.1 什么是胶水编程？

能抄就不写（用 GitHub 上经过验证的成熟代码），能连就不造（把 A、B、C 组件用胶水粘起来）。

你不创造零件代码，只负责通过胶水代码把各种成熟组件零件黏在一起。

这是 Vibe Coding 中最反直觉却最重要的一个思维转变。传统编程教育教你"从零实现"，胶水编程教你"反向搜索 + 编排组合"。

2.2 为什么胶水编程有效？

AI 最大的幻觉来源是**"凭空生成底层逻辑"**。手写的拖拽逻辑、手写的日期解析、手写的状态管理------边界 case 多、错误概率高、难以维护。

反过来，社区中已经存在经过千万次验证的成熟方案：

React 拖拽 → @dnd-kit（不要手写坐标监听）
日期处理 → date-fns（不要手写日期解析）
表单管理 → react-hook-form + zod（不要手写表单状态）
语音输入 → Web Speech API（不要从零写音频处理）

AI 的角色不是"发明这些组件"，而是写胶水代码把它们粘起来------适配接口、转换数据格式、编排调用顺序。

2.3 能力编排七步法

这是胶水编程的完整操作流程：

步骤	动作	示例（英语学习应用）
1. 写清需求	目标、输入、输出、约束、验收标准	"用户可以输入主题，AI 生成场景对话"
2. 反向搜索	让 AI 搜官方能力、工具链、成熟仓库	"搜 Web Speech API 最佳实践、Vercel AI SDK DeepSeek 接入方案"
3. 评估候选	检查维护状态、许可证、生产案例	Web Speech API（免费、原生）vs Whisper API（付费、更准）→ 选前者
4. 选择组合	确定工具链，写明为什么不用其他方案	"AI SDK 优于手写 fetch：streaming 原生支持、错误重试内置"
5. 设计边界	固定接口契约、错误处理、依赖隔离	定义 AI 响应的 Zod Schema（字段、类型、必填/可选）
6. 生成胶水	只写连接、适配、编排、配置、测试	把 AI SDK 的 streaming 响应接入 ChatArea 组件
7. 验证交付	测试、类型、schema、CI、检查清单	TypeScript 编译通过 + Zod 验证通过 + 手动跑通一个完整对话

2.4 一个对比实例

需求：给待办列表增加拖拽排序功能。

	❌ 错误示范	✅ 胶水编程
指令	"帮我写 React 待办清单的拖拽排序功能"	"给待办列表增加拖拽排序。调研 react 生态成熟方案，优先用 @dnd-kit。"
AI 做的事	凭空手写拖拽逻辑：坐标监听、排序算法、边界 case...	安装 @dnd-kit → 阅读文档 → 把现有 TodoList 组件和 @dnd-kit 衔接
结果	200 行自定义逻辑，8 个边界 bug，难以维护	30 行胶水代码，复用成熟库，稳定可维护
本质	造零件	拼乐高

三、Spec-Driven Development：让 AI 按契约干活

3.1 SDD 是什么？

"先写规范，再写代码" ------让 .md 文档成为任务的唯一事实来源。代码只是规范的产物。

如果把 Vibe Coding 比作盖房子：

纯 Vibe Coding = "师傅，帮我盖个房子"（师傅按照自己的理解盖）
Spec-Driven Development = 先画好建筑图纸 → 师傅严格按照图纸施工 → 验收以图纸为准

圈内把 .md 后缀戏称为 "Machine Done" --- Human Designed, Machine Done。

3.2 一份标准 Spec 文档的结构

markdown 复制代码

# Spec: [功能名称]

## 1. Summary（概述）
一段话描述功能，从最终用户的视角。

## 2. User Stories（用户故事）
- As a [角色], I want [行为] so that [价值]  (P1)
- As a [角色], I want [行为] so that [价值]  (P2)

## 3. Acceptance Criteria（验收标准）  ← 最重要的部分
- [ ] AC-01: Given [前提] When [动作] Then [预期结果]
- [ ] AC-02: [可测试的具体条件，不是模糊陈述]

## 4. Functional Requirements（功能需求）
- FR-001: [系统行为描述]
- FR-002: [NEEDS CLARIFICATION: 具体问题？]

## 5. Edge Cases（边界情况）
- EC-01: [异常场景] → [预期行为]
- EC-02: [空数据] → [显示空状态组件]

## 6. Data Contract（数据契约）  ← 防幻觉的关键
```typescript
interface AIResponse {
  content: string;
  corrections: { original: string; corrected: string; explanation: string }[];
  hints: string[];   // 最多 3 条中文提示
}

7. Out of Scope（不做什么） ← 防膨胀的关键

v1 不做用户登录
v1 不做移动端适配

8. Done Checklist（完成清单）

所有 AC 通过
边界情况处理完毕
测试通过
无 TODO/FIXME 残留

shell 复制代码

### 3.3 写出"可执行 Spec"的五个关键技巧

#### 技巧 1：用稳定 ID 建立可追溯性

```markdown
# ❌ "用户要能登录"（AI 无法跟踪）
# ✅ "FR-001: 系统应提供邮箱+密码登录方式"

# 在 plan.md 中引用：  "实现 FR-001 需要: auth.ts, login-form.tsx"
# 在 tasks.md 中引用：  "- [ ] FR-001: 创建 auth.ts"
# 在验收时引用：        "对照 AC-01 验证 FR-001"

FR-001、AC-01、EC-01 这样的 ID 让 AI 在 Specify → Plan → Implement → Verify 全流程中可以稳定引用同一个需求，不会出现"你说的登录和我说的登录是同一个吗"的问题。

技巧 2：用 Given-When-Then 写验收标准

markdown 复制代码

# ❌ AC-01: 登录功能正常（模糊，无法验证）
# ✅ AC-01: Given 用户已注册
#          When 输入正确邮箱和密码并点击"登录"
#          Then 系统跳转到首页，导航栏显示用户名
#          And 登录状态在刷新页面后保持

验收标准必须是可观测、可测量的事实。如果你不能写自动化测试来验证这个标准，说明它不够具体。

技巧 3：用 `[NEEDS CLARIFICATION]` 强制澄清

markdown 复制代码

- FR-005: 语音输入支持 [NEEDS CLARIFICATION: 只支持 Chrome 还是全浏览器？Chrome 的 SpeechRecognition 行为与其他浏览器不同]

这个标记强制 AI Agent 在实现前停下来请求澄清，而不是自己猜一个方案继续写。AI 最擅长的是"不懂装懂"------这个标记就是专门防这个的。

技巧 4：定义数据契约------最重要的防幻觉机制

markdown 复制代码

## Data Contract

### AI 对话响应格式（必须通过 Zod 验证）
```typescript
import { z } from 'zod';

const AIResponseSchema = z.object({
  content: z.string().min(1),
  corrections: z.array(z.object({
    original: z.string(),
    corrected: z.string(),
    explanation: z.string(),  // 中文解释
  })),
  hints: z.array(z.string()).max(3),  // 最多 3 条提示
  intent: z.enum(['continue_dialogue', 'end_conversation', 'give_hint']),
});

AI 的输出是概率性的------它可能给你多一个字段、少一个字段、字段类型不对。Zod Schema 是确定性的------不符合格式的响应直接被拒绝，不会流入业务逻辑。

这就是你的合同。你不信任 AI，你用 Zod 验证。

技巧 5：明确"不做什么"

markdown 复制代码

## Out of Scope (v1)
- 用户注册/登录
- 学习进度追踪和多设备同步
- 移动端响应式适配
- 多语言支持（仅做英中）
- 离线模式

这是防止 AI "擅自加料"的刹车。Vibe Coding 最大的屎山来源之一，就是 AI 在实现 A 功能时"顺便"加了 B、C、D 功能------而这些额外的代码没有经过设计，没有 Spec 约束，成为了不可控的技术债务。

3.4 SDD 工作流：五个阶段

yaml 复制代码

Phase 1: SPECIFY  → 写 Spec 文档（你主导，AI 辅助提问）
Phase 2: PLAN     → AI 把 Spec 拆成依赖排序的任务清单（要你审核批准）
Phase 3: CLARIFY  → AI 检查缺口、矛盾、缺失边界（代码写之前）
Phase 4: IMPLEMENT → AI 按任务清单逐个实现，每步自检
Phase 5: VERIFY   → 新会话/换模型，对照 Spec 的 AC 逐条验收

关键原则：55 分钟定义，5 分钟实现。 前期投入在 Spec 上的时间，会在后期省掉 10 倍的调试和修改。

3.5 主流 SDD 工具对比

工具	定位	核心特色	适合谁
GitHub Spec Kit (115K⭐)	完整工具包	constitution → spec → plan → tasks 四文档	团队、中型项目
OpenSpec (56K⭐)	变更提案制	proposal → design → tasks → specs	多人协作、需要审批
pspec	可执行 Spec	config/action/validate 代码块 → Agent 直接执行	单人、AI Agent 驱动
AGENTS.md (60K+ 项目)	最轻量	单个文件，README for agents	小项目、快速上手
nano-spec	极简	4 个文档 10 分钟搭建	个人项目

四、方法论的选择矩阵

你不需要每次都用到所有方法论。按场景选择：

场景	推荐方法	说明
探索性原型	四步循环 + 胶水编程	快速验证想法，不需要完整 Spec
单文件修改	四步循环（Prompt → Review → Refine）	不需要走完整的 RIPER
新功能开发	RIPER + SDD	有 Spec 才有验收标准
复杂重构	ISPI 四层模型	先理解现状再动手
技术选型	能力编排七步法	反搜→评估→选择
团队协作	SDD + OpenSpec/Spec Kit	多人需要共享契约

总结

中篇的核心信息是三句话：

工作流就是轨道 --- 没有轨道，AI 的生成是随机游走；有了轨道，AI 的生成是可预测的产出。
胶水编程是你的默认模式 --- 每次动手前先问：有没有成熟的库能做这件事？能不写底层逻辑就不写。
Spec 是你的合同 --- 数据契约（Zod/TypeScript）是防止 AI 幻觉的最后一道防线；验收标准（Given-When-Then）是你判断"做完了没有"的唯一标准。

Vibe Coding 深度解析：工作流、胶水编程与 Spec-Driven Development

两种路径：为什么"直接写代码"会失败

新手路径（会导致屎山）

Vibe Coding 路径

一、工作流模型：给 AI 搭好轨道

1.1 基础四步循环

1.2 RIPER 模型（阿里云实践）

1.3 ISPI 四层规范模型（腾讯云实践）

二、胶水编程：拼乐高，不造零件

2.1 什么是胶水编程？

2.2 为什么胶水编程有效？

2.3 能力编排七步法

2.4 一个对比实例

三、Spec-Driven Development：让 AI 按契约干活

3.1 SDD 是什么？

3.2 一份标准 Spec 文档的结构

7. Out of Scope（不做什么） ← 防膨胀的关键

8. Done Checklist（完成清单）

技巧 2：用 Given-When-Then 写验收标准

技巧 3：用 [NEEDS CLARIFICATION] 强制澄清

技巧 4：定义数据契约------最重要的防幻觉机制

技巧 5：明确"不做什么"

3.4 SDD 工作流：五个阶段

3.5 主流 SDD 工具对比

四、方法论的选择矩阵

总结

技巧 3：用 `[NEEDS CLARIFICATION]` 强制澄清