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 文件供下一阶段读取：

核心纪律：每一阶段都有明确检查点，当前阶段没验证通过就不进下一阶段。你的主要角色是「掌舵」，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 把它做扎实。

常见踩坑

1. 跳过 clarify 直接 plan：模糊需求会在 implement 阶段以更贵的方式暴露，先问清楚。
2. constitution 写成许愿池：只放真正不可妥协的原则，10 条以内，否则被稀释。
3. 从 PyPI 装包：官方明确——只从 GitHub 仓库装，PyPI 同名包非官方。
4. 一次 specify 塞太多功能：一个规格对应一个聚焦的功能集，太大就拆。
5. token 预算没留余量：SDD 比直接编码多花约 20-40% token，但省下大量返工周期，整体更划算。
6. 把规格写完就扔：规格是「活文档」，需求变了要回去改规格，而不是直接改代码让它和规格脱节。

与其他方案的关系

• 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 才不会每次都忘。

延伸阅读

• 工作流：2026 终端 AI Agent 怎么选 / 异步 coding agent 工作流
• 概念：AGENTS.md 标准 / Context Rot / Vibe Coding
• 工具：Claude Code / GitHub Copilot / Gemini CLI