第9章 先写规格再写代码
开场：从"代码是真相"到"意图是真相"
传统软件开发有一个信条："代码是真相之源。"
意思是：不管文档怎么写，不管需求怎么说，最终还是要看代码实现了什么。代码是唯一不骗人的。
但在 AI 编程时代，这个信条正在发生变化。
为什么？因为写代码变得太快了。
想一想：以前写一个功能，可能需要几天甚至几周。写代码是"昂贵"的，所以代码是核心资产。
现在呢？AI 几秒钟就能生成代码。写代码变得"便宜"了。
当写代码不再是瓶颈，什么变重要了？
是你想要什么。
你的意图、你的需求、你的想法——这些比代码本身更重要。
这就是"规格驱动开发"的核心思想。
你会学到什么
- 什么是规格驱动开发（SDD）
- 为什么它特别适合 AI 编程
- 如何写一份好的规格书
- GitHub Spec Kit 工具的使用
- 一个完整的实战案例
第一节：什么是规格驱动开发？
规格驱动开发（Spec-Driven Development，简称 SDD）是一种新的开发方式。
让我们对比一下传统方式和 SDD 方式。
传统开发方式：
想法 → 直接写代码 → 不断修改 → 最终产品
这种方式的问题是什么？
- 你以为你知道要什么，写着写着发现不是
- 代码写到一半发现方向错了，要重写
- 别人看你的代码，不知道你为什么这么写
- 需求变了，代码很难跟着变
SDD 开发方式：
想法 → 写规格 → 写计划 → AI执行 → 验证 → 最终产品
这种方式的优势是什么？
- 写规格前，你必须想清楚要什么
- 有了规格，AI 执行更准确
- 需求变了？修改规格，让 AI 重新生成
- 别人看规格，就知道项目是做什么的
[图 9-1] 传统开发与 SDD 开发对比
图表说明：左右对比图。左侧是传统开发流程：想法 → 代码 → 修改 → 修改 → 修改 → 产品（中间有很多反复的箭头）。右侧是 SDD 流程：想法 → 规格书 → 执行计划 → AI 执行 → 验证 → 产品（流程线性，箭头单向）。
SVG 生成提示词： "A side-by-side comparison diagram. Left side '传统开发': Idea → Code → Modify → Modify → Modify → Product, with many back-and-forth arrows. Right side 'SDD开发': Idea → Spec → Plan → AI Execute → Verify → Product, with linear flow. Labels in Chinese."
为什么 SDD 特别适合 AI 编程？
第一，AI 需要清晰的上下文
你给 AI 的信息越多，AI 生成的代码就越准确。
规格书就是一份完整的上下文文档。它告诉 AI：
- 这是什么项目
- 要解决什么问题
- 目标用户是谁
- 具体要实现什么功能
- 用什么技术栈
- 有什么约束条件
有了这些信息，AI 不需要"猜测"，只需要"执行"。
第二，AI 写代码很快，改代码也很快
传统开发中，写规格感觉是"额外工作"，因为写规格的时间可能和写代码的时间差不多。
但 AI 编程中，写规格可能花 30 分钟，AI 生成代码只需要 30 秒。
这种情况下，花时间把规格写清楚，是值得的。
第三，便于验证
第 7 章我们讲过验证的重要性。
有了规格书，验证就很简单：AI 生成的代码是不是实现了规格书里的所有要求？
如果没有规格，你怎么判断 AI 是不是做对了？
第四，便于修改
需求总是会变的。
有了规格书，需求变了，你只需要：
- 修改规格书
- 让 AI 根据新规格重新生成
不用在一堆代码里找哪里要改。
第二节：规格书应该包含什么？
一份完整的规格书包含以下几个部分。
1. 项目概述
回答三个问题：
- 这是什么项目？
- 给谁用？
- 解决什么问题？
这部分要简洁，一两段话就够了。
示例：
这是一个帮助自由职业者管理财务的记账本工具。目标用户是独立工作的设计师、开发者、咨询师等，他们可能有多个收入来源，需要为报税做准备。现有工具太复杂或太贵，这个工具提供简单、免费的个人财务管理。
2. 目标用户
更详细地描述你的用户。
- 他们是谁？
- 他们现在的痛点是什么？
- 他们为什么需要这个产品？
示例：
目标用户画像：
小李，独立设计师，28 岁。同时为 3-5 个客户工作，收入不稳定。每月底要花几个小时整理各种收入和支出，为报税做准备。现在用 Excel 记账，经常忘记记录，导致年底整理很痛苦。
痛点：
- 经常忘记记录交易
- 不确定自己这个月赚了多少钱
- 年底报税时整理资料很麻烦
- 现有记账软件太复杂，很多用不到的功能
3. 用户故事
用"用户故事"的格式描述核心功能。
格式是：作为[谁]，我想要[什么]，为了[什么目的]。
示例：
用户故事 1：作为自由职业者，我想要快速添加收入记录，为了追踪我的收入来源。
用户故事 2：作为自由职业者，我想要添加支出记录，为了了解我的花费情况。
用户故事 3：作为自由职业者，我想要查看当前余额，为了了解我的财务状况。
用户故事 4：作为自由职业者，我想要按月份筛选记录，为了做月度分析。
用户故事 5：作为自由职业者，我想要导出数据为 CSV，为了报税使用。
4. 功能需求
详细描述每个功能要做什么。
MVP 功能（第一版必须有的）：
| 功能 | 描述 | 优先级 |
|---|---|---|
| 添加记录 | 可以添加收入或支出记录 | 高 |
| 显示余额 | 显示当前总收入、总支出、余额 | 高 |
| 记录列表 | 显示所有记录，按日期排序 | 高 |
| 月份筛选 | 可以按月份查看记录 | 中 |
| 删除记录 | 可以删除错误的记录 | 中 |
以后再加的功能：
| 功能 | 描述 | 优先级 |
|---|---|---|
| 图表统计 | 收入支出饼图、月度趋势图 | 低 |
| 分类管理 | 为记录添加分类标签 | 低 |
| 数据备份 | 导出/导入数据 | 低 |
| 多币种 | 支持不同货币 | 低 |
5. 非功能需求
描述"功能以外"的要求。
性能要求：
- 页面加载时间不超过 2 秒
- 可以存储至少 1000 条记录不卡顿
兼容性要求：
- 支持最新版 Chrome、Safari、Edge
- 在手机浏览器上也能正常使用
安全要求：
- 数据存储在用户本地，不会上传到服务器
- 敏感信息（如有）需要加密存储
可用性要求：
- 新用户不需要看文档就能上手
- 界面简洁，没有复杂设置
6. 技术约束
说明技术栈和约束。
前端：
- 使用 React
- 使用 Tailwind CSS 做样式
后端：
- 不需要后端，纯前端应用
数据存储：
- 使用浏览器 localStorage
不能用：
- 不能要求用户安装任何软件
- 不能依赖服务器（离线也能用）
7. 验收标准
怎么算"完成"？
列出可以检查的标准：
- 用户可以添加收入记录
- 用户可以添加支出记录
- 余额计算正确（收入减支出）
- 收入用绿色显示，支出用红色显示
- 可以按月份筛选记录
- 可以删除记录
- 数据刷新页面后不丢失
- 页面在手机上也能正常显示
第三节：GitHub Spec Kit 工具
Spec Kit 是 GitHub 出品的一个开源工具，专门用于规格驱动开发。
它提供了一套命令行工具，帮助你：
- 创建规格书模板
- 把规格转成任务列表
- 让 AI 按规格执行
Spec Kit 的核心命令
请见表 9-1。
表 9-1 Spec Kit 核心命令
| 命令 | 作用 | 示例 |
|---|---|---|
/speckit.specify |
创建规格书 | /speckit.specify 我要做一个记账本 |
/speckit.plan |
把规格转成技术计划 | /speckit.plan |
/speckit.tasks |
把计划转成任务列表 | /speckit.tasks |
/speckit.implement |
让 AI 执行任务 | /speckit.implement |
一个完整的工作流
# 第 1 步：创建规格
/speckit.specify "我要做一个团队协作的待办清单"
# AI 会问你一些问题，帮你澄清需求
# 第 2 步：生成技术计划
/speckit.plan
# AI 会分析规格，生成技术实现计划
# 第 3 步：生成任务列表
/speckit.tasks
# AI 会把计划拆成可执行的小任务
# 第 4 步：让 AI 执行
/speckit.implement
# AI 会按任务列表开始实现
[图 9-2] Spec Kit 工作流程
图表说明：流程图显示 4 个步骤：1. Specify（创建规格）→ 2. Plan（技术计划）→ 3. Tasks（任务列表）→ 4. Implement（AI 执行）。每一步有对应的图标和箭头连接。
SVG 生成提示词： "A horizontal flow diagram with 4 steps: 1. 'Specify - 创建规格' with document icon → 2. 'Plan - 技术计划' with blueprint icon → 3. 'Tasks - 任务列表' with checklist icon → 4. 'Implement - AI执行' with robot icon. Arrows connect each step."
Spec Kit 的优势
优势 1：结构化
Spec Kit 强制你按照结构化的方式写规格。不会遗漏重要信息。
优势 2：AI 辅助
Spec Kit 会问你问题，帮你把模糊的想法澄清。
优势 3：从规格到代码的完整链路
从规格到计划，从计划到任务，从任务到代码——一条龙服务。
优势 4：开源免费
Spec Kit 是开源的，任何人都可以用。
第四节：一份完整的规格书示例
让我们写一份完整的规格书，以"团队待办清单"为例。
# 团队待办清单规格书
## 1. 项目概述
**产品名称**：TeamTask（团队任务协作工具）
**一句话描述**：一个让小团队协作管理任务的简单工具。
**解决的问题**：
* 现有工具（如 Jira、Trello）太复杂
* 团队沟通分散在各种渠道
* 任务状态不透明，不知道谁在做什么
**目标用户**：
* 3-10 人的小团队
* 创业公司
* 远程工作的团队
* 不想学习复杂工具的团队
---
## 2. 用户画像
**典型用户**：张三，小团队负责人
* 团队有 5 个人，大家远程工作
* 目前用微信群沟通任务，经常漏掉信息
* 想要一个简单的地方可以看到所有任务
* 不想花时间学习复杂工具
* 预算有限，不想买昂贵的软件
**典型用户**：李四，团队成员
* 同时参与多个项目
* 需要知道自己的任务优先级
* 需要让负责人知道自己的进度
* 手机和电脑都要能用
---
## 3. 用户故事
**故事 1**：作为团队成员，我想要查看所有任务，以便了解团队在做什么。
**故事 2**：作为团队负责人，我想要创建任务并分配给成员，以便跟踪工作进度。
**故事 3**：作为团队成员，我想要更新任务状态，以便让大家知道我的进展。
**故事 4**：作为团队负责人，我想要看到任务统计，以便了解团队工作负载。
**故事 5**：作为团队成员，我想要按自己筛选任务，以便只看我的工作。
---
## 4. 功能需求
### 4.1 MVP 核心功能（第一版）
**任务管理**：
* 创建任务（标题、描述、负责人、截止日期）
* 编辑任务信息
* 删除任务
* 更新任务状态（待办/进行中/完成）
**任务视图**：
* 看板视图：按状态分列显示
* 列表视图：按日期排序
* 筛选：按负责人筛选
**团队管理**：
* 添加团队成员
* 移除团队成员
* 查看成员列表
### 4.2 以后再加的功能
* 任务评论
* 文件附件
* 提醒通知
* 移动端 App
* 任务优先级
* 任务标签
* 活动历史
---
## 5. 非功能需求
**性能**：
* 页面加载时间 < 2 秒
* 可以流畅显示 100+ 任务
**兼容性**：
* 支持最新版 Chrome、Safari、Edge
* 移动端浏览器可用
**可用性**：
* 新用户 5 分钟内能学会使用
* 不需要培训文档
**数据**：
* 数据实时同步到所有团队成员
* 支持离线查看（在线时自动同步）
---
## 6. 技术栈
**前端**：
* React 18+
* TypeScript
* Tailwind CSS
* shadcn/ui（组件库）
**后端**：
* Next.js 14（App Router）
* API Routes
**数据库与认证**：
* Supabase（PostgreSQL 数据库）
* Supabase Auth（用户认证）
* Supabase Realtime（实时同步）
**部署**：
* Vercel
---
## 7. 数据结构设计
**tasks 表**：
* id（UUID，主键）
* title（文本，任务标题）
* description（文本，任务描述）
* status（枚举：todo/in_progress/done）
* assignee_id（外键，关联 users）
* due_date（日期，截止日期）
* created_at（时间戳）
* updated_at（时间戳）
**users 表**：
* id（UUID，主键）
* email（文本，邮箱）
* name（文本，姓名）
* created_at（时间戳）
---
## 8. 验收标准
* [ ] 用户可以注册/登录
* [ ] 用户可以创建任务
* [ ] 用户可以分配任务给团队成员
* [ ] 用户可以更新任务状态
* [ ] 用户可以看到团队所有任务
* [ ] 任务实时同步到所有成员
* [ ] 用户可以按负责人筛选任务
* [ ] 看板视图正常显示
* [ ] 列表视图正常显示
* [ ] 页面加载时间 < 2 秒
第五节：从规格到代码的完整流程
有了规格书，下一步是怎么把它变成代码？
步骤 1：规格 → 技术计划
让 AI 帮你分析规格，生成技术计划。
你：
根据这份规格书，生成一个技术实现计划。
包括：数据结构设计、API 设计、组件结构。
AI：
好的，让我分析这份规格...
**技术实现计划**
1. 数据结构设计
tasks 表：id, title, description, status, assignee_id, due_date
users 表：id, email, name
用 Supabase 创建这些表
2. API 设计
GET /api/tasks - 获取任务列表
POST /api/tasks - 创建任务
PUT /api/tasks/:id - 更新任务
DELETE /api/tasks/:id - 删除任务
GET /api/users - 获取用户列表
3. 组件结构
app/
- page.tsx（首页）
- login/page.tsx（登录页）
components/
- TaskBoard（看板视图）
- TaskList（列表视图）
- TaskCard（任务卡片）
- TaskForm（任务表单）
步骤 2：计划 → 任务
把技术计划拆成可执行的小任务。
你：
把技术计划拆成具体的任务列表，每个任务应该在 30 分钟内完成。
AI：
好的，这是任务列表：
**Phase 1: 项目初始化**
- [ ] 创建 Next.js 项目
- [ ] 安装依赖（Tailwind、shadcn/ui）
- [ ] 连接 Supabase
**Phase 2: 认证**
- [ ] 创建登录页面
- [ ] 实现登录逻辑
- [ ] 实现注册逻辑
**Phase 3: 数据模型**
- [ ] 在 Supabase 创建 tasks 表
- [ ] 在 Supabase 创建 users 表
- [ ] 设置行级安全策略（RLS）
**Phase 4: 任务管理**
- [ ] 实现创建任务 API
- [ ] 实现更新任务 API
- [ ] 实现删除任务 API
- [ ] 创建任务表单组件
**Phase 5: 任务展示**
- [ ] 创建看板视图组件
- [ ] 创建列表视图组件
- [ ] 实现任务筛选
**Phase 6: 实时同步**
- [ ] 集成 Supabase Realtime
- [ ] 实现任务实时更新
步骤 3：任务 → 代码
让 AI 按任务执行。
你：
开始执行 Phase 1 的任务。
AI：
好的，开始执行...
✓ 创建 Next.js 项目完成
✓ 安装依赖完成
✓ 连接 Supabase 完成
Phase 1 完成。继续 Phase 2 吗？
你：
继续 Phase 2。
AI：
开始执行 Phase 2：认证...
[生成登录页面代码]
[实现登录逻辑]
[实现注册逻辑]
Phase 2 完成。登录功能已可用。
第六节：规格驱动开发的好处
好处 1：意图清晰
规格书是你"想要什么"的清晰表达。
有了规格，AI 不需要猜测你的意图，只需要实现你描述的东西。
好处 2：可追溯
问题出在哪？
- 查规格书：原来的需求是什么？
- 查技术计划：当时是怎么设计的？
- 查代码：实际是怎么实现的？
每一步都有记录，方便定位问题。
好处 3：可复用
下次做类似项目，规格书可以作为模板。
你只需要修改一部分内容，不需要从头开始。
好处 4：抗工具变化
即使 Spec Kit 将来被替代，"写规格"这个能力永远有用。
规格驱动开发是一种思维方式，不是某个特定工具的功能。
第七节：常见问题
问题 1：写规格不是浪费时间吗？
答：在 AI 编程之前，写规格确实感觉浪费时间。
但在 AI 编程时代，情况变了：
- 传统：写规格 2 小时，写代码 2 天。规格占比 4%
- AI 编程：写规格 2 小时，AI 生成 2 分钟。规格占比 98%
当代码生成变得很快，把规格写好就是值得的。
问题 2：规格需要多详细？
答：够详细就行。
标准是：如果你把规格给另一个 AI，它能按规格做出你想要的东西。
不需要过度设计。MVP 先简单，后面可以迭代。
问题 3：需求变了怎么办？
答：修改规格，让 AI 重新生成。
这就是 SDD 的优势——需求变，规格变，代码跟着变。
动手实验室
完整项目代码：
labs/chapter09-spec-kit/
在这个目录里，我为你准备了：
- Spec Kit 安装指南
- 完整的规格书模板
- 从规格到代码的完整案例
你可以：
- 直接运行体验
- 作为起点修改
- 学习如何写规格书
本章小结
这一章，我们学习了"规格驱动开发"（SDD）。
核心观点：在 AI 编程时代，"意图"比"代码"更重要。
我们介绍了：
- 什么是 SDD：先写规格，再写代码
- 为什么 SDD 适合 AI 编程：代码变便宜了，意图变贵了
- 规格书应该包含什么：概述、用户、功能、技术、验收
- GitHub Spec Kit 工具的使用
- 从规格到代码的完整流程
要点回顾请见表 9-2。
表 9-2 规格驱动开发要点回顾
| 概念 | 要点 |
|---|---|
| SDD | 先写规格，再写代码的开发方式 |
| 规格书 | 包含概述、用户、功能、技术、验收的文档 |
| Spec Kit | GitHub 的 SDD 工具，辅助写规格和执行 |
| 流程 | 规格→计划→任务→代码 |
记住：
在 AI 编程时代，"意图"比"代码"更重要。
写好规格书，让 AI 来实现它。
规格是"真相"，代码是"产出"。
在下一章，我们会学习"给 AI 装上技能包"——用 Superpowers 把资深工程师的方法编码成 AI 能遵循的工作流。
本章字数：约 12,000 字