Spec-Driven Development 实战：用 GitHub Spec Kit 让 AI 先写规格再写代码
适用场景
这篇不是「要不要写文档」的争论，而是一套让 AI agent 先把规格写清楚、确认后再生成代码的可执行流程。适合：
- 被 vibe coding 坑过的人——agent 写了 400 行，一半解决了错的问题
- 要把 AI 编程从「玩具原型」推到「生产可维护」的团队
- 接手既有项目、要加功能但怕 agent 越改越乱的开发者
- 想让规格评审取代逐行 code review、把人力用在刀刃上的 tech lead
不适合：单文件脚本 / 一次性工具、需求已经在 Jira/Linear/Notion 里写全了不想重复、或者只追求最快出第一版原型的场景。
什么是 Spec-Driven Development
SDD 把传统的「先写代码、后补文档」反过来：规格是真相来源，代码是规格生成出来的产物，AI agent 是那台生成器。
vibe coding 的失败模式很具体：系统的「真相」活在一段会随上下文窗口填满而重置的聊天记录里。agent 忘、你也忘，新功能和旧功能互相矛盾。SDD 把真相变成磁盘上的一个文件。
来源说明：本文基于 GitHub 官方博客与 github/spec-kit 仓库、多份 2026 实操指南综合整理。Spec Kit 于 2025-09 公布、2025-11 首个 tag 发布，命令仍在迭代，请以仓库最新 README 为准。
四阶段闭环
每个 spec-driven 流程——无论用 Spec Kit、Kiro 还是自制模板——都跑同一个序列，每一阶段产出一个 markdown 文件供下一阶段读取：
| 阶段 | 斜杠命令 | 产出 | 关注点 |
|---|---|---|---|
| 1. Specify | /speckit.specify | 规格文件 | 「做什么」「为什么」——用户旅程、成功长什么样，不碰技术栈 |
| 2. Plan | /speckit.plan | 技术实现计划 | 给定技术栈后的架构与方案 |
| 3. Tasks | /speckit.tasks | 依赖排序的任务清单 | 把计划拆成可执行、有依赖顺序的小任务 |
| 4. Implement | /speckit.implement | 代码 | agent 按任务清单逐个执行 |
核心纪律：每一阶段都有明确检查点，当前阶段没验证通过就不进下一阶段。你的主要角色是「掌舵」，agent 干大部分写的活。
第一步：装 Specify CLI
需要 Python 3.11+、uv（官方推荐）或 pipx、Git、以及一个支持的 AI agent（Claude Code / GitHub Copilot agent 模式 / Gemini CLI / Cursor / Codex CLI / Qwen Code 等 24+ 集成）。
# 唯一官方包来自 GitHub 仓库——不要从 PyPI 装同名包（非官方维护）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
# 新项目初始化（指定你的 agent）
specify init my-project --ai claude-code
# 或接入已有项目
cd existing-project
specify init . --ai copilot
specify init 会生成 .specify/ 目录：模板、配置、agent 集成都在里面。之后所有斜杠命令通过你选的 agent 界面驱动。
第二步：先立 constitution（项目宪法）
constitution.md 是 SDD 的一个关键补充——为项目立一组不可妥协的原则：测试约定、CLI-first 要求、设计系统标准、安全合规规则。立一次，后续每个阶段都引用它。
/speckit.constitution
例如写进去：
- 所有新功能必须带单元测试，覆盖率不低于现有水平
- 不引入新的运行时依赖，除非在计划阶段明确批准
- 对外 API 变更必须向后兼容
- 数据库迁移必须可回滚
这样后面 Plan / Implement 阶段 agent 都会受这些约束，而不是每次重新讲。
第三步：走完四阶段
# 1. 描述要做什么（高层、面向用户，别谈技术栈）
/speckit.specify
# 例："做一个书签管理器，用户能按标签归类、全文搜索、导出 JSON"
# （可选但推荐）澄清欠规格的地方，减少返工
/speckit.clarify
# 2. 给定技术栈，生成实现计划
/speckit.plan
# 例："Nuxt 4 + libsql + drizzle，全文搜索用 Pagefind"
# 3. 拆成依赖排序的任务清单
/speckit.tasks
# （可选）跨产物一致性与覆盖度分析
/speckit.analyze
# 4. 执行
/speckit.implement
辅助命令（提质量）：
/speckit.clarify：在 plan 之前，用结构化追问把模糊点问清楚（强烈建议，省后续返工）/speckit.analyze：在 tasks 之后、implement 之前，做跨产物一致性和覆盖度检查/speckit.checklist：生成自定义质量检查清单，验证需求的完整性、清晰度、一致性/speckit.taskstoissues：把任务清单转成 GitHub issues 做跟踪
什么时候该用、什么时候别用
✅ 用 SDD：
- 会上生产、需要长期维护的功能
- 多人协作、需要规格作为共识
- 既有系统加功能 / 遗留代码现代化
- 复杂到「直接 prompt 会跑偏」的需求
❌ 别用 SDD：
- 单文件脚本 / 一次性工具
- 需求已在别的系统里写全、不想重复
- 纯原型，速度比可维护性重要得多
经验法则：原型用 vibe，生产用 spec。 先 vibe 探路，确认方向后切到 spec-driven 把它做扎实。
常见踩坑
- 跳过 clarify 直接 plan：模糊需求会在 implement 阶段以更贵的方式暴露，先问清楚。
- constitution 写成许愿池：只放真正不可妥协的原则，10 条以内，否则被稀释。
- 从 PyPI 装包：官方明确——只从 GitHub 仓库装，PyPI 同名包非官方。
- 一次 specify 塞太多功能：一个规格对应一个聚焦的功能集，太大就拆。
- token 预算没留余量：SDD 比直接编码多花约 20-40% token，但省下大量返工周期，整体更划算。
- 把规格写完就扔：规格是「活文档」，需求变了要回去改规格，而不是直接改代码让它和规格脱节。
与其他方案的关系
- vs Kiro IDE：Kiro 是 AWS 的专有 VS Code fork，把 SDD 烘进 IDE；Spec Kit 是开源、agent 无关的工具包，套在你已有的任何 agent 外面，跨 IDE 和 CLI 都能用。
- vs 纯 vibe coding：vibe 是「prompt 完照单全收」；SDD 是「先有批准的规格、计划、任务，再写一行代码」。
- 配合 终端 agent 工作流：SDD 定义「做什么」，终端 agent 栈定义「用哪个工具怎么执行」，两者叠加。
一句话总结
立宪法 → Specify（做什么） → Clarify（问清楚） → Plan（怎么做）
→ Tasks（拆任务） → Analyze（查一致） → Implement（执行）
规格会比聊天记录活得久。把真相写进磁盘，AI 才不会每次都忘。