第 29 课：Spec Coding——从 Vibe 到规范驱动开发

第六章：Claude Code 工程化工作流 | 第 29 课

课前思考

你刚让 Claude Code 做了一个功能，跑起来效果不错。然后你把这个 Demo 给开发同事看，他们的第一反应是什么？

「这个能跑，但没法维护。」「测试在哪？」「代码风格和我们项目完全不搭。」

Vibe Coding 能让你快速到达「差不多对了」的状态。但从那个状态到「可以交付的代码」，中间还隔着一整套工程实践。这一课讲的就是这个过渡。

---

一、两种模式的本质区别

2025 年，OpenAI 研究员 Sean Grove 在 AI Engineer World's Fair 上提出了一个观点：

「代码是意图的有损投影。规范才是真正的『新代码』。」

Vibe Coding：描述需求 → AI 直接写代码 → 跑起来看看 → 不对再改
Spec Coding：描述需求 → 写规范文档 → AI 读取规范 → 按规范生成代码 → 验证

什么时候用哪种？

场景	推荐模式	原因
快速原型验证	Vibe	速度第一，代码可能扔掉
一次性脚本/工具	Vibe	不需要长期维护
生产级功能开发	Spec	需要测试、文档、可维护性
多人协作项目	Spec	需要统一的认知基础
长期维护的代码	Spec	未来你会感谢现在的自己

Spec Coding 不是否定 Vibe Coding。它是在正确的时间选择正确的模式。

---

二、Spec Coding 的四步工作流

第一步：产品验证

在写任何代码之前，回答三个问题：

1. 灵魂三问：用户是谁？痛点在哪？为何用你？
2. MVP 思维：能验证假设的最简版本是什么？
3. 快速验证：用最小成本验证核心假设

这些内容在第一、第二章已经详细讲过。关键点是：不要把需求验证和编码混在一起做。 先确认方向对了，再让 AI 写代码。

第二步：编写 AI 友好的 PRD

给 AI 看的 PRD 和给人看的不太一样。五个核心部分：

第一部分：文档信息
- 版本号、阶段（初稿/中稿/定稿）、干系人

第二部分：需求背景与目标
- 项目概述、核心问题、用户故事
- SMART 目标

第三部分：方案概述
- Mermaid 流程图：核心业务流程、信息架构

第四部分：细节方案
- 页面原型与交互说明
- 边缘 Case 处理
- 非功能性需求（性能、安全、可访问性）

第五部分：上线计划
- 排期、灰度策略

关键词：结构化 + 可视化。 PRD 越清楚，AI 的输出越稳定。

第三步：与 AI 确认理解（关键步骤）

很多人跳过这一步，直接把 PRD 扔给 AI 开始写代码。这是最常见的错误。

正确的做法——把 PRD 给 AI 后，先让它复述理解：

请基于上面的 PRD，复述你的理解：
1. 目标用户是谁？
2. 核心功能有哪些？（按优先级排列）
3. 明确不做哪些功能？
4. 你认为有哪些潜在的风险或模糊点？

这一步可能只需要 2 分钟，但能省下后续 2 小时的返工。

第四步：AI 生成 Spec → 你审查 → AI 编码

你的 PRD → AI 生成技术 Spec（数据模型、API 设计、组件树）
       → 你审查 Spec，确认无误
       → AI 按 Spec 逐模块编码
       → 你验收结果

关键点：不要跳过 Spec 这一步。Spec 是 PRD 和代码之间的桥梁——PRD 描述「要什么」，Spec 描述「怎么做」。如果 Spec 写错了，代码肯定错。

---

三、实战示例：从 PRD 到代码

假设你是一个电商 PM，需求是「用户可以对已完成订单发表评价」。

你写的 PRD 片段：

评价功能：用户可以对已完成的订单发表评价，包含评分（1-5 星）和文字评价内容。已评价的订单不可再次评价。评价后展示在商品详情页。

AI 生成的 Spec 片段：

数据模型：
- reviews 表：id, order_id (FK), user_id (FK), rating (1-5), content, created_at

API：
- POST /api/orders/:id/review  → 发表评价
- GET /api/products/:id/reviews → 获取商品评价列表

约束：
- 订单状态必须为 completed
- 一个订单只能评价一次（order_id unique）
- rating 范围 1-5

确认 Spec 后 AI 生成的代码片段：

// 发表评价 API
app.post('/api/orders/:id/review', auth, async (req, res) => {
  const order = await db.orders.findByPk(req.params.id);

  // 约束 1：订单必须已完成
  if (order.status !== 'completed') {
    return res.status(400).json({ error: '只能评价已完成的订单' });
  }

  // 约束 2：一个订单只能评价一次
  const existing = await db.reviews.findOne({
    where: { order_id: order.id }
  });
  if (existing) {
    return res.status(400).json({ error: '该订单已评价' });
  }

  // 约束 3：rating 范围校验
  const { rating, content } = req.body;
  if (rating < 1 || rating > 5) {
    return res.status(400).json({ error: '评分范围为 1-5' });
  }

  const review = await db.reviews.create({
    order_id: order.id,
    user_id: req.user.id,
    rating,
    content
  });

  res.status(201).json(review);
});

注意看——Spec 中定义的三个约束全部变成了代码。这就是规范驱动开发的威力：你的 PRD 质量，直接决定了 AI 代码的质量。

---

课后练习

1. 找一个你最近做的功能，用 Spec Coding 四步法重新走一遍——先写 PRD，让 AI 复述理解，生成 Spec，再编码
2. 对比：直接 Vibe 生成的代码 vs Spec Coding 生成的代码，差异在哪里？
3. 在你的 CLAUDE.md 中加一条规则：「开发新功能时，先生成技术 Spec 供审查」