Spec-Kit 使用指南

什么是Spec-Kit？

Spec-Kit是GitHub开源的一个工具包，用于实现规格驱动开发（Spec-Driven Development）。它与AI编码工具（如GitHub Copilot、Claude Code、Gemini CLI）集成，帮助开发者构建更高质量的软件。

解决的核心痛点

• "氛围编码"问题：传统AI编码中，你描述目标，得到代码块，但往往"看起来对，但实际不工作"
• 缺乏结构化流程：从想法到实现缺乏清晰的步骤和检查点
• 质量不一致：生成的代码缺乏统一的质量标准和测试覆盖

主要功能

1. 规格优先开发：先写规格说明，再生成代码
2. 四阶段工作流：Specify（规格化） → Plan（规划） → Tasks（任务分解） → Implement（实现）
3. 强制测试驱动开发（TDD）：必须先生成测试，再生成实现代码
4. 与AI工具无缝集成：支持Claude Code、GitHub Copilot等

环境准备与安装

前提条件（以Claude Code + macOS为例）

• 系统要求：macOS（支持Apple Silicon和Intel芯片）
• Claude Code：已安装Claude Code CLI
• Claude订阅 ：Claude Pro（ <math xmlns="http://www.w3.org/1998/Math/MathML"> 20 / 月）或 C l a u d e M a x （ 20/月）或Claude Max（ </math>20/月）或ClaudeMax（100/月）
• Python环境：Python 3.8+

安装步骤

1. 安装uv包管理器

brew install uv

2. 验证Claude Code安装

claude doctor

3. 从零开始构建项目

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

(若已有项目)集成Spec-Kit

uvx --from git+https://github.com/github/spec-kit.git specify init --here

4. 启动Claude Code

# 进入项目文件夹
cd <PROJECT_NAME>

# 启动claude code
claude

5. 验证安装

在Claude Code中检查是否有/specify命令可用。

关键命令

命令	功能	使用时机	输出文件
/specify	描述功能需求	项目开始时	spec.md
/plan	技术规划	需求明确后	plan.md
/tasks	任务分解	规划完成后	tasks.md

完整工作流程

阶段0：Build（构建）

目标：设置项目环境和初始化Spec-Kit

1. 按照上述安装步骤完成环境配置
2. 确认所有命令可用
3. 准备开始规格驱动开发

阶段1：Specify（规格化）

目标：明确项目需求和规格

执行命令

使用/specify命令描述你要构建的内容：

• 专注于什么 和为什么，而不是技术栈
• 描述用户旅程和体验
• 定义成功标准

示例：

/specify 我需要构建一个用户注册系统，允许用户通过邮箱注册账号，验证邮箱地址，并在注册成功后自动登录

审查和修改

执行/specify命令后，Claude Code会生成详细的规格文档（spec.md）。你需要审查并修改：

重点关注：

• 业务逻辑准确性：是否符合你的业务需求
• 功能完整性：是否遗漏重要功能
• 边界条件：错误处理、异常情况
• 性能要求：响应时间、并发用户数等
• 安全要求：认证、授权、数据保护

阶段2：Plan（规划）

目标：制定技术实现计划

执行命令

使用/plan命令提供技术实现规划：

示例：

/plan 使用Node.js + Express.js后端，MongoDB数据库，JWT认证，nodemailer发送验证邮件

审查技术计划

Claude Code会生成详细的技术计划，包括：

• 架构设计：系统整体架构
• 技术栈选择：前后端技术栈
• 数据库设计：数据模型和关系
• API端点规划：RESTful API设计
• 部署策略：部署和运维方案

阶段3：Tasks（任务分解）

目标：将规格和计划分解为可执行任务

执行命令

/tasks 将上述规格和计划分解为可执行的开发任务

任务列表管理

生成的任务列表需要你：

• 优先级排序：调整任务执行顺序
• 任务细化：对复杂任务进一步分解
• 依赖关系：确认任务间的依赖关系

阶段4：Implement（实现）

目标：基于TDD原则实现代码

代码生成原则

让Claude生成代码时遵循：

• 必须先写测试（TDD原则）
• 获得测试批准后再生成实现代码
• 通过迭代测试和审查完善代码

代码生成哲学

• 可观察性优于不透明性：一切都必须可以通过CLI界面进行检查
• 简单胜过聪明：从简单开始，只有在必要时才增加复杂性
• 集成优于隔离：在真实环境中进行测试，而不是在人工环境中
• 模块化优于整体：每个功能都是一个具有明确边界的库

最佳实践

1. 需求先行：始终从用户需求和业务价值开始
2. 测试驱动：严格遵循TDD，先写测试后写代码
3. 渐进式开发：通过阶段性检查点确保质量
4. 持续验证：在每个阶段验证输出质量
5. 文档同步：保持规格文档与实际实现同步
6. 版本控制：每个阶段完成后提交代码

与传统开发的区别

传统AI编码	Spec-Kit方式
描述→代码→希望有效	规格→计划→测试→实现
缺乏结构	四阶段结构化流程
事后测试	测试驱动开发
质量不一致	规格保证质量
临时性方案	可维护的长期解决方案
单次交互	迭代式改进

实际使用场景

1. 新功能开发：完整的四阶段流程，适合复杂功能开发
2. Bug修复：简化流程，重点关注测试和验证
3. 代码重构：先明确规格，再进行重构
4. API设计：详细的规格定义和测试用例
5. 团队协作：规格文档作为团队沟通的统一语言
6. 项目交接：完整的规格和文档便于项目移交

项目文件结构

使用Spec-Kit后，你的项目通常会包含：

my-project/
├── spec.md              # 项目规格文档
├── plan.md              # 技术实现计划
├── tasks.md             # 任务分解列表
├── tests/               # 测试文件
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── src/                 # 源代码
├── docs/                # 项目文档
└── README.md           # 项目说明

故障排除

常见问题

1. /specify命令不可用

解决方案：

• 检查是否正确初始化了Spec-Kit
• 重新运行初始化命令
• 确认Claude Code版本兼容

2. 生成的规格不符合预期

解决方案：

• 使用更具体的描述
• 提供更多上下文信息
• 迭代修改，多次执行/specify

3. 技术计划不合理

解决方案：

• 在/plan命令中提供更详细的技术约束
• 明确现有技术栈和限制
• 手动修改生成的plan.md

4. 任务分解粒度不当

解决方案：

• 手动调整tasks.md中的任务粒度
• 合并过小的任务，分解过大的任务
• 明确任务间的依赖关系

性能优化

• 使用上下文优化命令减少重复加载：
  • get-steering-context
  • get-spec-context
  • get-template-context

进阶技巧

1. 规格版本控制

为重要的规格变更创建版本标记：

## 版本历史
- v1.0: 基础用户注册功能
- v1.1: 添加社交登录支持
- v1.2: 增加多语言支持

2. 模板复用

为常见的项目类型创建规格模板：

• Web应用模板
• API服务模板
• 移动应用模板

3. 团队协作

• 建立规格审查流程
• 定期同步规格文档
• 使用规格作为团队沟通工具

总结

Spec-Kit通过引入规格驱动开发，将Claude Code从"聊天式编码工具"转变为"结构化软件开发伙伴"。它强调：

• 先思考，再编码
• 测试优先，质量保证
• 文档驱动，团队协作
• 迭代改进，持续优化

---

本文档基于Spec-Kit官方文档和实践经验整理，如有疑问请参考官方GitHub仓库