Spec-Kit：规范驱动开发工具包深度解析
规范不再是写完就丢的脚手架，而是可直接生成可运行代码的可执行文档。
🦢 什么是 Spec-Kit？
Spec-Kit 是 GitHub 开源的开发工具包，用于实现规范驱动开发（Spec-Driven Development，SDD）。它颠覆了传统软件开发中”代码为王”的理念——规范不再是一次性文档，而是可执行的、直接生成实现的核心资产。
核心理念对比
| 传统开发 | Spec-Driven Development |
|---|---|
| 需求文档写完就丢 | 规范是执行的起点 |
| 开发者直接写代码 | AI 根据规范生成代码 |
| 代码与文档脱节 | 规范与实现严格对应 |
| “Vibe Coding”随机生成 | 结构化、可预测的流程 |
| 一次性提示词 | 多轮 refinement refinement |
Spec-Kit 的目标是让你专注于产品场景和可预测的结果，而不是从零开始”vibe coding”每个功能。
🎯 核心工作流：五步构建
Spec-Kit 提供了一套完整的开发流程，通过 5 个核心命令实现结构化开发：
1️⃣ /speckit.constitution — 建立项目原则
创建项目的治理原则和开发指南，这是所有后续开发的”宪法”。
/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements. Include governance for how these principles should guide technical decisions and implementation choices.
输出：.specify/memory/constitution.md
典型内容包括：
- 代码质量标准
- 测试覆盖要求
- 用户体验一致性规范
- 性能基准
- 技术决策治理流程
2️⃣ /speckit.specify — 定义需求
描述要做什么（what & why），而不是怎么做（how）。
/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.
关键原则：
- ✅ 明确业务场景和用户故事
- ✅ 描述功能行为和边界
- ❌ 不要指定技术栈
- ❌ 不要预设实现细节
输出：specs/001-feature-name/spec.md
3️⃣ /speckit.plan — 制定技术方案
提供技术栈选择和架构决策。
/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.
输出内容：
plan.md— 实现计划data-model.md— 数据模型设计api-spec.json— API 规范research.md— 技术调研记录quickstart.md— 快速启动指南
4️⃣ /speckit.tasks — 生成任务清单
将计划拆解为可执行、可追踪的任务列表。
/speckit.tasks
任务清单特点：
- 按用户故事分组
- 尊重依赖顺序（模型 → 服务 → 接口）
- 标记可并行执行的任务
[P] - 指定具体文件路径
- 支持 TDD（测试先行）结构
- 每个阶段包含 checkpoint 验证点
输出：specs/001-feature-name/tasks.md
5️⃣ /speckit.implement — 执行实现
自动执行任务清单，完成功能构建。
/speckit.implement
执行流程：
- 验证前置条件（constitution、spec、plan、tasks 齐全）
- 解析任务清单
- 按依赖顺序执行任务
- 遵循 TDD 方法
- 提供进度更新和错误处理
🚀 快速开始
环境要求
- 操作系统：Linux / macOS / Windows
- Python：3.11+
- 包管理：uv
- 版本控制：Git
- AI 助手：任意支持的 CLI 工具
安装 CLI 工具
# 安装指定稳定版本（推荐） uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z # 或安装最新版（可能包含未发布变更） uv tool install specify-cli --from git+https://github.com/github/spec-kit.git # 检查安装 specify check
初始化项目
# 创建新项目 specify init my-project --ai claude # 在当前目录初始化 specify init . --ai claude # 或使用 --here 标志 specify init --here --ai claude # 强制合并到非空目录 specify init . --force --ai claude # 跳过 Git 初始化 specify init my-project --ai gemini --no-git # 为 Codex 安装 agent skills specify init my-project --ai codex --ai-skills
无需安装直接运行
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init . --ai claude
🤖 支持的 AI 助手
Spec-Kit 与主流 AI 编码助手深度集成：
| AI 助手 | 支持状态 | 备注 |
|---|---|---|
| Claude Code | ✅ | 官方推荐 |
| Gemini CLI | ✅ | |
| GitHub Copilot | ✅ | VS Code 集成 |
| Cursor | ✅ | 独立 IDE |
| Codex CLI | ✅ | 需 --ai-skills，使用 $speckit-* 命令 |
| Qwen Code | ✅ | 阿里云 |
| Windsurf | ✅ | Codeium |
| Kiro CLI | ✅ | AWS |
| Amp | ✅ | Ampcode |
| Pi Coding Agent | ✅ | Pi.ai |
| Tabnine CLI | ✅ | Tabnine |
| Mistral Vibe | ✅ | Mistral AI |
| opencode | ✅ | 开源 |
| Roo Code | ✅ | Roo |
| SHAI (OVHcloud) | ✅ | OVH |
| Antigravity | ✅ | Google，需 --ai-skills |
| Trae | ✅ | ByteDance |
| Junie | ✅ | JetBrains |
| Generic | ✅ | 自定义 agent，需 --ai-commands-dir |
🧩 扩展系统：让 Spec-Kit 更强大
Spec-Kit 的核心优势是其可扩展架构。社区已贡献 25+ 扩展，分为五大类：
📋 扩展分类
| 类别 | 说明 | 示例 |
|---|---|---|
| docs | 读取、验证或生成规范文档 | Understanding、DocGuard |
| code | 审查、验证或修改源代码 | Review、Verify、Checkpoint |
| process | 跨阶段编排工作流 | AIDE、Fleet、MAQA |
| integration | 与外部平台同步 | Jira、Azure DevOps、Linear |
| visibility | 报告项目健康度或进度 | Doctor、Status |
🔥 热门扩展推荐
1. AIDE (AI-Driven Engineering)
一个结构化的 7 步工作流，从零开始构建新项目：
vision → roadmap → progress tracking → work queue → work items → execution → feedback
2. Checkpoint
在实现过程中提交变更，避免最后只有一个超大 commit。
3. Cleanup
实现后的质量关卡：
- 审查变更
- 修复小问题（scout rule）
- 为中等问题创建任务
- 为大问题生成分析报告
4. Review
全面的代码审查，包含专门 agent：
- 代码质量
- 注释规范
- 测试覆盖
- 错误处理
- 类型设计
- 简化建议
5. Jira / Azure DevOps / Linear 集成
将规范中的用户故事和任务同步到项目管理工具。
6. V-Model Extension Pack
强制执行 V-Model：成对生成开发规范和测试规范，确保完整可追溯性。
7. Project Health Check (Doctor)
诊断 Spec-Kit 项目，报告结构、agent、功能、脚本、扩展和 Git 的健康问题。
安装扩展
# 搜索可用扩展 specify extension search # 安装扩展 specify extension add <extension-name>
🎨 预设系统：定制你的工作流
预设（Presets） 允许你自定义 Spec-Kit 的行为——覆盖模板、命令和术语，无需修改任何工具代码。
预设 vs 扩展
| 目标 | 使用 |
|---|---|
| 添加新命令或工作流 | 扩展 |
| 自定义规范/计划/任务的格式 | 预设 |
| 集成外部工具或服务 | 扩展 |
| 强制执行组织或监管标准 | 预设 |
| 发布可复用的领域模板 | 两者皆可 |
预设示例
1. Pirate Speak（海盗风格）
将所有输出转换为海盗语言：
spec.md→ “Voyage Manifest”plan.md→ “Battle Plan”tasks.md→ “Crew Assignments”
2. AIDE In-Place Migration
适配 AIDE 扩展用于技术迁移（X → Y 模式），添加：
- 迁移目标
- 验证关卡
- 知识文档
- 行为等价性标准
安装预设
# 搜索可用预设 specify preset search # 安装预设 specify preset add <preset-name>
模板优先级
┌─────────────────────────────────────────┐ │ ⬆ 最高优先级 │ │ 项目本地覆盖 │ │ .specify/templates/overrides/ │ ├─────────────────────────────────────────┤ │ 预设 │ │ .specify/presets/<id>/templates/ │ ├─────────────────────────────────────────┤ │ 扩展 │ │ .specify/extensions/<id>/templates/ │ ├─────────────────────────────────────────┤ │ ⬇ 最低优先级 │ │ Spec-Kit 核心 │ │ .specify/templates/ │ └─────────────────────────────────────────┘
💡 适用场景详解
🌱 从零开始（Greenfield）
场景：空白目录，构建全新应用。
流程：
specify init初始化项目/speckit.constitution建立原则/speckit.specify定义需求/speckit.plan选择技术栈/speckit.tasks生成任务/speckit.implement执行实现
示例项目：
- .NET CLI 工具 — 时区工具
- Spring Boot + React — LLM 性能分析平台
🔄 现有项目扩展（Brownfield）
场景：已有代码库，添加新功能。
关键优势：
- 无需先有规范或 constitution
- 可直接在现有分支上工作
- 支持大型多模块项目
示例项目：
- ASP.NET CMS 扩展 — 30 万行 C# 项目，添加 REST API
- Java 运行时扩展 — 42 万行 Java 项目，添加管理控制台
- Go/React Dashboard — NASA 地面支持系统，添加遥仪表板
🔬 多方案并行探索
场景：尝试不同技术栈实现同一需求。
方法：
- 创建多个分支
- 每个分支使用不同技术栈
- 对比实现结果
🏢 企业级开发
场景：需要合规、审计、设计系统约束。
支持能力：
- 组织标准预设
- 监管追溯性（V-Model）
- 设计系统集成
- 多团队协作（timestamp 分支编号）
📽️ 社区资源
视频教程
- Spec-Kit 视频概述 — 官方演示
社区扩展项目
- cc-sdd — Claude Code 插件，添加可组合 trait 和 Superpowers 质量关卡
- Spec Kit Assistant — VS Code 扩展，提供可视化编排器、任务清单、DAG 可视化
完整 Walkthrough
- Greenfield .NET CLI
- Greenfield Spring Boot + React
- Brownfield ASP.NET CMS
- Brownfield Java Runtime
- Brownfield Go/React
- Pirate Speak Preset Demo
- AIDE Extension Demo
🔧 高级用法
环境变量
# 为非 Git 仓库覆盖功能检测 export SPECIFY_FEATURE=001-photo-albums
分支编号策略
# 顺序编号（默认）：001, 002, 003 specify init my-project --ai claude --branch-numbering sequential # 时间戳编号：20260401-195400（适合分布式团队） specify init my-project --ai claude --branch-numbering timestamp
企业/离线安装
对于无法访问 PyPI 或 GitHub 的环境：
# 在联网机器上下载 wheel 包 pip download specify-cli # 将 wheel 包复制到离线机器安装 pip install specify-cli --no-index --find-links=./wheels
详细指南见 Enterprise Installation。
🎯 实验目标
Spec-Kit 的研究和实验重点：
- ✅ 使用多样化技术栈创建应用
- ✅ 验证 SDD 不绑定特定技术/语言/框架
- ✅ 演示任务关键型应用开发
- ✅ 整合组织约束（云提供商、技术栈、工程实践）
- ✅ 支持企业设计系统和合规要求
- ✅ 为不同用户群体构建应用
- ✅ 支持多种开发方法（从 vibe-coding 到 AI-native）
- ✅ 验证并行实现探索
- ✅ 提供稳健的迭代功能开发工作流
- ✅ 扩展升级和现代化任务流程
📚 学习资源
| 资源 | 链接 |
|---|---|
| 完整 SDD 方法论 | spec-driven.md |
| CLI 参考 | 本文档上方 |
| 扩展发布指南 | EXTENSION-PUBLISHING-GUIDE.md |
| 预设发布指南 | PUBLISHING.md |
| 升级指南 | upgrade.md |
🔗 相关链接
- GitHub 仓库：https://github.com/github/spec-kit
- 官方文档：https://github.github.io/spec-kit/
- 最新 Release：https://github.com/github/spec-kit/releases/latest
- 视频教程：https://www.youtube.com/watch?v=a9eR1xsfvHg
- 许可证：MIT
- Discord 社区：https://discord.com/invite/clawd
- 技能市场：https://clawhub.com
🦢 总结
Spec-Kit 不是另一个”AI 代码生成器”，而是一套结构化的开发方法论。它通过强制”先设计后实现”的流程，让 AI 助手产出更可靠、可维护的代码。
核心价值
| 传统 AI 编程 | Spec-Kit |
|---|---|
| 单次提示词生成 | 多轮 refinement |
| 代码与文档脱节 | 规范与实现对应 |
| 难以追溯需求 | 完整可追溯链 |
| 适合快速原型 | 适合生产系统 |
| 个人使用 | 团队协作友好 |
适合谁？
- ✅ 喜欢先设计后实现的开发者
- ✅ 需要可追溯性、合规性的企业项目
- ✅ 希望标准化团队开发流程的技术负责人
- ✅ 想要利用 AI 但保持控制力的工程师
不适合谁？
- ❌ 只想快速写个小脚本
- ❌ 不喜欢结构化流程的”vibe coder”
- ❌ 完全不想写文档的开发者
规范驱动开发的本质：让规范成为可执行的资产，而不是写完就丢的文档。