Spec Kit 实战：从规范到可运行代码的 AI 辅助开发流程
Spec Kit 实战：从规范到可运行代码的 AI 辅助开发流程
前言
在传统软件开发中，我们习惯了"代码为王"的思维：先写代码，再补文档，规范往往沦为事后总结。但随着 AI 编码工具的普及，这个关系正在被颠覆——GitHub 官方开源的 Spec Kit 提出了一种新的开发范式：规范驱动开发（Spec-Driven Development, SDD）。
核心理念很简单：规范定义"做什么"，AI 负责"怎么做"。规范不再是被动记录，而是变成可执行的产物，直接从规范生成可工作的实现。
本文将结合我的实际使用经验，介绍 Spec Kit 的完整工作流、与主流 AI 编码工具的集成方式、以及一些实战踩坑记录。特别地：
- 第五章会分享我在实践中沉淀的多模型分工方案，针对 Spec Kit 不同阶段选用最适合的 AI 模型
- 第八章将分享一个图片预览问题的真实排查案例，展示如何在 bug 修复场景中灵活运用 Spec Kit
- 第九章会对比 Spec Kit 与 Crush(OpenCode) 两种工具的适用场景
目录
- 一、什么是规范驱动开发（SDD）
- 二、Spec Kit 核心工作流（5 步）
- 三、安装与初始化
- 四、与主流 AI 编码工具的集成
- 五、多模型分工实战：五步流程中的模型选择
- 六、质量保障命令
- 七、实战技巧与踩坑记录
- 八、实战案例：图片预览问题的规范驱动排查
- 九、同类工具对比：Spec Kit vs Crush(OpenCode)
- 十、实操提示词模板
- 十一、项目目录结构示例
- 十二、总结
- 参考资料
一、什么是规范驱动开发（SDD）
1.1 传统开发 vs 规范驱动开发
传统开发流程：
需求 → 设计(可选) → 编码 → 测试 → 文档(可选)
规范驱动开发流程：
需求 → 规范(Spec) → 计划(Plan) → 任务(Tasks) → 实现(Implementation) → 验收
核心差异：
- 传统流程中，规范和文档是编码后的产物，往往滞后甚至缺失
- SDD 流程中，规范是起点，是 AI 实现的"宪法"，是验收的标准
1.2 Spec Kit 是什么
Spec Kit 是 GitHub 官方开源的规范驱动开发工具包，支持 30+ AI 编码工具，包括：
- GitHub Copilot
- Claude Code
- Cursor
- Codex CLI
- Windsurf
- Kilo（国产工具，支持 DeepSeek、GLM 等模型）
GitHub 仓库：https://github.com/github/spec-kit
文档站：https://github.github.io/spec-kit/
二、Spec Kit 核心工作流（5 步）
Spec Kit 的核心是 5 步工作流，每一步都有对应的命令：
| 步骤 | 命令 | 作用 |
|---|---|---|
| 1. 制定项目原则 | /speckit.constitution |
定义技术栈、代码质量、性能要求等"宪法" |
| 2. 定义功能需求 | /speckit.specify |
模糊需求 → 用户故事、功能需求（FR）、成功标准（SC） |
| 3. 生成技术方案 | /speckit.plan |
数据模型、接口契约、架构决策、quickstart |
| 4. 分解任务列表 | /speckit.tasks |
方案 → 有序任务单元（含依赖关系和并行标记） |
| 5. 执行实现 | /speckit.implement |
AI 按任务列表逐一编写代码、创建文件、运行测试 |
2.1 第一步：制定项目原则（constitution）
constitution.md 是整个项目的"宪法"，定义了：
- 技术栈约束（如"必须使用 TypeScript"、"禁止未授权第三方库"）
- 代码质量标准（如"所有公共 API 必须有 JSDoc 注释"）
- 性能要求（如"首次加载时间不超过 3 秒"）
- 安全原则（如"敏感数据必须加密存储"）
示例：
## 技术栈
- 前端：Vue 3 + TypeScript + Vite
- 后端：Node.js + Express + PostgreSQL
- 禁止使用：jQuery、未授权的 npm 包
## 代码质量
- 所有公共函数必须有 JSDoc
- TypeScript strict mode
- 单元测试覆盖率 ≥ 80%
## 性能
- 首屏渲染时间 < 2s
- API 响应时间 < 500ms
2.2 第二步：定义功能需求（specify）
这一步把模糊的口头需求转化为结构化的规范文档，包括：
- 用户故事（User Stories）
- 功能需求（Functional Requirements, FR）
- 成功标准（Success Criteria, SC）
输出文件：specs/001-xxx/spec.md
2.3 第三步：生成技术方案（plan）
基于 spec.md，AI 会生成详细的技术方案，包括：
- 数据模型（Data Model）
- 接口契约（API Contract）
- 架构决策（Architecture Decision）
- 快速开始指南（Quickstart）
输出文件：specs/001-xxx/plan.md
2.4 第四步：分解任务列表（tasks）
plan.md 被分解为具体的任务单元，每个任务包含：
- 任务描述
- 依赖关系（哪些任务必须先完成）
- 并行标记（哪些任务可以并行执行）
输出文件：specs/001-xxx/tasks.md
2.5 第五步：执行实现（implement）
AI 按照 tasks.md 的顺序，逐一：
- 创建文件
- 编写代码
- 运行测试
- 修复错误
三、安装与初始化
3.1 环境要求
- 操作系统：Linux / macOS / Windows
- Python ≥ 3.11
- uv 包管理器（推荐）或 pipx
- Git
3.2 安装 Spec Kit
# 使用 uv 安装
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z
# 验证安装
specify --version
3.3 初始化项目
# 新项目
specify init my-project --integration copilot
# 现有项目
specify init . --integration copilot
# 强制在非空目录初始化
specify init . --force --integration copilot
初始化后会生成：
.specify/目录：包含模板、脚本、内存文件specs/目录：存放规范文档
四、与主流 AI 编码工具的集成
Spec Kit 支持 30+ AI 编码工具，不同工具的初始化命令略有差异：
# Codex CLI
specify init . --integration codex
# Claude Code
specify init . --integration claude
# Kilo（国产工具）
specify init . --integration kilo
# GitHub Copilot
specify init . --integration copilot
# Cursor
specify init . --integration cursor
运行 specify integration list 可查看所有可用集成。
五、多模型分工实战：五步流程中的模型选择
5.1 为什么需要多模型分工
Spec Kit 的 5 步工作流将开发过程划分为认知负荷不同的阶段：
| 阶段 | 核心任务 | 认知需求 |
|---|---|---|
| 规范/方案 | 理解模糊需求、生成结构化文档、做架构决策 | 强推理、精准表达 |
| 代码实现 | 按任务列表批量写代码、跑测试、修 bug | 严格遵循指令、快速迭代 |
| 验收检查 | 全面审查实现是否满足规范 | 综合评估、捕捉边界情况 |
| 文档生成 | 编写实现摘要、经验总结、注意事项 | 结构清晰、中文组织 |
| 经验沉淀 | 从一次实践中提炼可复用规则 | 模式识别、泛化抽象 |
不同 AI 模型在这些能力维度上各有优势。如果只用同一个模型完成所有步骤，要么浪费推理能力强的模型在重复性任务上，要么让执行快的模型做它不擅长的架构决策。
5.2 我的分工方案
经过多个项目的实践迭代，我沉淀了一套多模型分工方案：
| 阶段 | 对应 Spec Kit 步骤 | 模型 | 产出 |
|---|---|---|---|
| 规范与方案 | constitution + specify + plan + tasks | Codex GPT-5.5 | spec.md, plan.md, data-model.md, tasks.md |
| 代码实现 | implement | DeepSeek v4 Flash | 代码文件、测试、变更清单 |
| 验收检查 | checklist | GPT-5 | 验收清单、问题报告 |
| 文档预览 | —（补充步骤） | GLM-5 | 实现摘要、经验总结 |
| 经验沉淀 | —（补充步骤） | GPT-5 | SKILL.md（可复用规则） |
5.3 各环节详解
5.3.1 规范/方案阶段 → Codex GPT-5.5
这一阶段对模型的需求理解和结构化输出能力要求最高。Codex GPT-5.5 的优势在于：
- 能主动识别需求中的模糊点，通过反问帮助澄清
- 生成的技术方案会考虑备选方案并给出优劣对比
- 对"禁止行为"和"验收标准"的界定比执行型模型更精准
实践提示词：
$speckit-specify
请特别注意识别需求中的模糊点，主动通过反问澄清。
规范需要包含明确的验收标准和禁止行为。
对于技术方案，请考虑至少两种备选方案并给出对比。
5.3.2 代码实现阶段 → DeepSeek v4 Flash
这一阶段的核心是严格按任务列表执行。DeepSeek v4 Flash 的优势：
- 执行速度快，迭代成本低
- 擅长严格遵循详细的 tasks.md，不擅自添加额外功能
- 生成代码时能保持风格一致
但需要注意：DeepSeek v4 Flash 不适合做架构决策，如果 tasks.md 写得不够细，它可能会偏离预期。所以上一阶段的 tasks.md 质量是关键。
实践提示词：
$speckit-implement
请严格遵守 tasks.md 的顺序执行，不擅自变更任务优先级。
实现完成后列出：新增文件、修改文件、测试结果、仍然存在的风险。
不要引入 tasks.md 未授权的库或依赖。
5.3.3 验收检查阶段 → GPT-5
代码实现完成后，需要一个全局视角来检查是否符合规范。GPT-5 的优势：
- 能对照 spec.md 逐项检查功能完整性和边界条件
- 对错误处理和异常路径的覆盖检查比较全面
- 发现的问题能给出具体的修复建议
实践提示词：
$speckit-checklist
请对照 spec.md 中的功能需求和成功标准，逐项检查实现结果。
检查项包括：功能完整性、边界条件处理、错误处理、代码一致性。
对每一项给出 pass/fail 判断，fail 项需说明具体问题。
5.3.4 文档预览阶段 → GLM-5
这一阶段是我在 5 步流程外补充的步骤——在验收通过后，让 AI 自动生成实现文档。GLM-5 的优势：
- 中文文档生成质量好，结构清晰
- 能区分"技术细节"和"读者关注点"，生成面向不同受众的文档
- 对实现过程的梳理比较条理
实践提示词：
基于当前实现结果，生成以下文档：
1. 实现摘要：概述实现了什么、改了哪些文件
2. 经验总结：本次实现中遇到的问题和解决方案
3. 注意事项：后续开发中需要关注的点
要求：结构清晰、重点突出、面向开发者可读。
5.3.5 经验沉淀阶段 → GPT-5
项目完成后，把本次实践中验证有效的规则提炼为可复用的 SKILL.md。GPT-5 的优势：
- 能区分"本次项目的特有信息"和"可跨项目复用的通用规则"
- 对错误模式的归纳比较准确
- 生成的 SKILL.md 结构完整，包含触发条件、执行步骤、验收清单等
实践提示词：
请回顾本次完整的开发过程（从 spec 到实现到验收），生成一份 SKILL.md。
SKILL.md 需要包含：
1. 触发条件：什么场景下可以使用本 Skill
2. 执行步骤：可复用的操作流程
3. 关键规则：本次实践中验证有效的原则
4. 常见错误：避免重复踩坑
5. 验收清单：判断执行是否完成的检查项
请特别区分"本次项目的特有信息"和"可跨项目复用的通用规则"。
5.4 多模型协作的注意事项
-
上下文传递是关键：每个阶段的输出（spec.md、plan.md、tasks.md）就是下一个阶段的输入上下文。文档质量直接决定下游效果。
-
不要频繁切换模型：每个阶段内尽量用同一个模型完成，避免在 spec 阶段反复切换模型导致的风格不一致。
-
验收和沉淀用同一模型的好处：GPT-5 既做验收又做沉淀，可以利用验收阶段的上下文直接生成 SKILL.md，减少重复描述。
-
执行型模型的 tasks.md 必须详细：DeepSeek v4 Flash 的优势是严格遵循指令，但如果 tasks.md 不够细，它的"自由发挥"能力不如推理型模型。实践建议：tasks 粒度控制在每个任务 1-3 个文件，依赖关系明确标注。
六、质量保障命令
除了核心 5 步，Spec Kit 还提供辅助质量保障命令：
| 命令 | 作用 |
|---|---|
/speckit.clarify |
识别规范模糊点，结构化问答澄清（plan 前使用） |
/speckit.analyze |
检查规范、计划、任务之间的一致性与覆盖度 |
/speckit.checklist |
生成需求满足检查清单，辅助人工审查 |
/speckit.taskstoissues |
任务列表 → GitHub Issues |
注意：/speckit.checklist 生成的是初步验收清单，实际验收时我仍会用 GPT-5 做独立审查（见第五章），因为 AI 自检往往不如独立模型审查全面。
七、实战技巧与踩坑记录
7.1 实战技巧
1. 优先用 constitution 约束 AI
不要让 AI 自己猜测技术栈和代码标准，在 constitution.md 中明确写出：
- 禁止使用的库
- 必须支持的存储方式
- 性能和安全红线
2. 迭代优化规范
如果 AI 生成的代码不符合需求，不要直接改代码，而是：
- 更新 spec.md 或 constitution.md
- 重新运行
/speckit.plan和/speckit.implement
这样规范和代码始终保持同步。
3. 老项目先做 research
对于已有代码库的项目，不要直接开始新功能的规范，而是：
- 让 AI 文档化现有代码库
- 生成
research.md压缩视图 - 在 research 基础上补充新功能规范
4. 需求变更的正确流程
需求变更时：
修改规范 → 重新 plan → 重新 tasks → 重新 implement
不要跳过中间步骤直接改代码。
7.2 踩坑记录
坑 1：constitution 不够严格
现象：AI 使用了未授权的库，或代码风格不符合团队标准。
修正：在 constitution.md 中增加明确的禁止条款和强制条款。
坑 2：spec.md 太模糊
现象：plan.md 生成后，发现缺少关键功能点。
修正：在 spec 前使用 /speckit.clarify，让 AI 通过问答帮你澄清需求。
坑 3：跳过 tasks 直接 implement
现象：AI 实现时任务顺序混乱，依赖关系未处理。
修正：必须完整走完 5 步流程，tasks.md 是实现顺序的保障。
坑 4：验收检查省略
现象：代码生成完成，但测试失败或功能缺失。
修正：
- 使用
/speckit.checklist生成验收清单 - 人工逐项检查
- 不要依赖 AI 自声称"已完成"
坑 5：多模型分工时上下文断裂
现象：DeepSeek v4 Flash 实现时忽略了 spec.md 中明确写的约束。
修正：在 tasks.md 中显式复述关键约束，不要假设执行模型会主动回看 spec.md。
这是多模型分工独有的坑——每个模型的上下文窗口独立，关键信息必须在当前阶段的输入文档中复述一遍。
八、实战案例：图片预览问题的规范驱动排查
8.1 背景
在一个微信小程序/App 混合开发项目中，图片预览组件出现了多个异常：
- 同一张图片重复进入预览时显示异常
- 横屏切换后视口尺寸未正确重算
- 缩放后拖动边界计算错误
这是一个典型的"老项目、新问题"场景：代码库已有复杂调用链路，问题涉及平台差异，单纯靠"试试改改"效率极低。
8.2 为什么用 Spec Kit（而不是直接改代码）
虽然这是 bug 修复而非新功能开发，但仍然选择使用 Spec Kit 的原因：
- 问题复杂度高：涉及多个入口、平台分支、手势处理链路
- 需要结构化排查：避免"头痛医头、脚痛医脚"
- 希望沉淀经验：不仅要修好，还要形成可复用的排查 skill
8.3 实际流程
由于是 bug 修复而非新功能，没有完全照搬 5 步流程，而是做了适配，同时应用了第五章的多模型分工思路：
1. 简化 constitution（项目约束）→ Codex GPT-5.5
## 技术栈
- 前端：uni-app + Vue 2 + JavaScript
- 平台：微信小程序 + App（iOS/Android）
## 排查原则
- 优先检查调用链路，不要假设组件行为
- 文档口径与实际代码不一致时，以代码为准
- 区分平台差异，不要盲目复用修复方案
2. 定义问题规范（spec）→ Codex GPT-5.5
在 specs/002-fix-image-preview/spec.md 中：
- 描述 3 类问题的现象和触发条件
- 标注涉及的关键文件：
details.vue、imagePreview.vue - 明确验收标准：每个问题的修复后行为
3. 生成排查计划（plan）→ Codex GPT-5.5
生成了结构化的排查方案：
- 数据模型：图片预览的状态流转图
- 调用链路：从入口到渲染的完整路径
- 平台分支：微信小程序与 App 的差异点
- quickstart：复现问题的最小步骤
4. 分解任务（tasks）→ Codex GPT-5.5
将排查工作拆分为：
- 日志埋点任务
- 调用链路追踪任务
- 平台差异对比任务
- 修复验证任务
5. 执行实现（implement）→ DeepSeek v4 Flash
按 tasks.md 逐一排查和修复，输出变更清单和测试结果。
6. 验收（checklist）→ GPT-5
对照 spec.md 中的验收标准逐项检查，发现遗漏的边界情况。
7. 文档与沉淀
- GLM-5 生成了两份经验文档：
image-preview-experience-preview.md：面向 3 类问题的统一复盘image-preview-implementation-summary.md：当前实现的完整总结
- GPT-5 同时形成了
SKILL.md：后续排查同类问题的执行规则
8.4 经验与反思
适用场景判断
Spec Kit 的完整 5 步流程更适合：
- 从零开始的新功能开发
- 需要生成大量代码的任务
- 规范明确、架构可控的项目
对于 bug 修复这种"问题诊断型"任务，建议：
- 保留 constitution 和 spec 步骤（定义问题边界）
- 简化 plan 步骤（侧重排查路径而非架构设计）
- 强化 tasks 步骤（确保排查有序）
核心价值
即使场景不完全适用，Spec Kit 仍提供了：
- 结构化思维：强制你先写清楚"问题是什么"，再动手
- 可追溯性：规范、计划、任务、实现全程记录
- 可复用性：修复过程沉淀为 skill，后续同类问题可快速定位
踩坑
- constitution 太简单会导致 AI 在排查时"乱猜"平台差异
- spec 写得太模糊会导致 plan 缺少关键调用链路
- 老项目直接用 spec-kit 时，建议先让 AI 生成
research.md压缩视图
8.5 目录结构
最终生成的项目结构：
specs/002-fix-image-preview/
├── spec.md # 问题描述与验收标准
├── plan.md # 排查路径与调用链路
├── tasks.md # 排查任务列表
├── data-model.md # 图片预览状态流转图
├── quickstart.md # 问题复现步骤
├── research.md # 现有代码库压缩视图
├── SKILL.md # 后续排查规则
└── doc-output/
├── image-preview-experience-preview.md
└── image-preview-implementation-summary.md
九、同类工具对比：Spec Kit vs Crush(OpenCode)
9.1 Crush 简介
Crush（原 OpenCode）是 Charmbracelet 团队开发的终端 AI 编码工具。与 Spec Kit 的结构化工作流不同，Crush 主打对话式交互，配置方式更轻量：
# 安装
winget install charmbracelet.crush
# 启动
crush # 启动 TUI
crush -p "问题" -q # 非交互模式
配置方式：crush.json + AGENTS.md
9.2 对比
| 特性 | Spec Kit | Crush |
|---|---|---|
| 工作流 | 5 步结构化（规范→计划→任务→实现） | 对话式交互 |
| 配置方式 | .specify/ + specs/ 目录 |
crush.json + AGENTS.md |
| 依赖 | Python 3.11+ + uv 包管理器 | Go 单二进制 |
| 适用场景 | 大型项目、规范化流程、需要文档沉淀 | 快速原型、轻量交互、个人项目 |
| 学习成本 | 较高，需要理解 SDD 工作流 | 较低，上手即用 |
9.3 选择建议
- 如果你在团队项目中需要结构化的规范文档、可追溯的决策记录、以及完整的验收流程，Spec Kit 是更好的选择。
- 如果你只是个人快速开发、或者已有成熟的 AGENTS.md 配置，Crush 的对话式交互更轻量。
- 两者并不互斥：可以用 Crush 做快速探索，在进入正式开发阶段后用 Spec Kit 做规范化管理。
十、实操提示词模板
10.1 通用模板（适用于所有模型）
$speckit-plan
请严格遵守 .specify/memory/constitution.md。
本次生成的 plan.md 必须使用简体中文。
代码、命令、API、路径、类名、函数名可以保留英文。
10.2 按模型定制的提示词
Codex GPT-5.5（用于 spec/plan 阶段）
$speckit-specify
请特别注意识别需求中的模糊点，主动通过反问澄清。
规范需要包含明确的验收标准和禁止行为。
对于技术方案，请考虑至少两种备选方案并给出对比。
DeepSeek v4 Flash（用于 implement 阶段）
$speckit-implement
请严格遵守 tasks.md 的顺序执行，不擅自变更任务优先级。
实现完成后列出：新增文件、修改文件、测试结果、仍然存在的风险。
不要引入 tasks.md 未授权的库或依赖。
GPT-5（用于验收阶段）
$speckit-checklist
请对照 spec.md 中的功能需求和成功标准，逐项检查实现结果。
检查项包括：功能完整性、边界条件处理、错误处理、代码一致性。
对每一项给出 pass/fail 判断，fail 项需说明具体问题。
GLM-5（用于文档预览阶段）
基于当前实现结果，生成以下文档：
1. 实现摘要：概述实现了什么、改了哪些文件
2. 经验总结：本次实现中遇到的问题和解决方案
3. 注意事项：后续开发中需要关注的点
要求：结构清晰、重点突出、面向开发者可读。
GPT-5（用于 Skill 沉淀阶段）
请回顾本次完整的开发过程（从 spec 到实现到验收），生成一份 SKILL.md。
SKILL.md 需要包含：
1. 触发条件：什么场景下可以使用本 Skill
2. 执行步骤：可复用的操作流程
3. 关键规则：本次实践中验证有效的原则
4. 常见错误：避免重复踩坑
5. 验收清单：判断执行是否完成的检查项
请特别区分"本次项目的特有信息"和"可跨项目复用的通用规则"。
十一、项目目录结构示例
完整的 Spec Kit 项目结构：
.
├── .specify/
│ ├── memory/
│ │ └── constitution.md
│ ├── scripts/
│ │ └── bash/
│ └── templates/
├── specs/
│ └── 001-create-taskify/
│ ├── spec.md
│ ├── plan.md
│ ├── data-model.md
│ ├── quickstart.md
│ ├── research.md
│ └── tasks.md
├── src/
└── README.md
十二、总结
Spec Kit 的核心价值：
- 规范先行：把"做什么"定义清楚，再让 AI 解决"怎么做"
- 分层精炼：需求 → 规范 → 方案 → 任务 → 实现，每一步都可验收
- 工具兼容：支持 30+ AI 编码工具，不绑定特定平台
- 迭代可控：需求变更时规范同步更新，避免规范滞后
- 多模型协作：不同阶段选用最适合的 AI 模型，发挥各自优势
结合多模型分工方案后的完整开发流程：
[Codex GPT-5.5] [DeepSeek v4 Flash] [GPT-5] [GLM-5] [GPT-5]
规范 → 方案 → 任务 → 代码实现 → 验收 → 文档预览 → Skill
如果你正在使用 AI 编码工具，Spec Kit 可以帮助你从"随机对话式开发"转向"规范驱动式开发"，让 AI 生成的代码更可控、更可验收。而多模型分工方案则是在此基础上进一步优化——不求一个模型完成所有事，而是让每个模型做它最擅长的事。
浙公网安备 33010602011771号