SpecKit 完整学习指南

目录

  1. 什么是 SpecKit
  2. 核心概念
  3. 系统架构
  4. 核心组件
  5. 工作流程
  6. 安装与配置
  7. 使用指南
  8. 最佳实践
  9. 实战案例

什么是 SpecKit

SpecKit 是由 GitHub 开源的规范驱动开发（Spec-Driven Development, SDD）工具包，它通过将”规范变为可执行”的方式，彻底改变了传统的软件开发流程。

核心理念

传统开发流程：需求 → 编码 → 测试 → 文档

SpecKit 开发流程：规范 → AI 执行 → 自动实现 → 持续演进

主要特点

  • 规范即源码：规范不再是一次性的设计文档，而是项目的核心资产
  • AI 原生：深度集成 14+ 种 AI 编码助手（Claude Code, GitHub Copilot, Cursor 等）
  • 结构化开发：通过明确的阶段和命令，确保开发过程可控、可追溯
  • 开源免费：MIT 许可证，GitHub 28K+ stars

核心概念

Spec-Driven Development (SDD)

规范驱动开发是一种以规范为中心的开发方法论，包含三个层次：

1. Spec-First（规范优先）

在开发之前编写详细的规范文档，用于指导 AI 辅助开发。

2. Spec-Anchored（规范锚定）

开发完成后保留规范，用于功能演进和维护。

3. Spec-as-Source（规范即源码）

规范成为唯一的源文件，人类只修改规范，AI 负责更新代码。

系统架构

整体架构图

架构层次说明

1. 开发者层

  • 开发者通过 CLI 或 AI 助手与 SpecKit 交互
  • AI 助手负责理解规范并生成代码

2. SpecKit 核心

  • Specify CLI: 命令行工具，提供项目初始化和检查功能
  • Slash Commands: 结构化命令集，控制开发流程各阶段
  • 模板系统: 提供标准化的文档模板

3. 规范体系

五个核心制品（Artifacts），形成完整的规范链：

  • Constitution → Specification → Plan → Tasks → Implementation

4. 输出产物

根据规范自动生成的代码、测试和文档

核心组件

组件关系图

1. 基础命令（CLI）

specify init <project-name>

初始化新项目，创建 .speckit/ 目录和配置文件。

功能：

  • 创建项目骨架
  • 配置 AI 助手集成
  • 生成默认模板

示例：

specify init my-app

specify check

检查系统环境和依赖。

功能：

  • 验证 AI 助手配置
  • 检查必要工具安装
  • 显示当前项目状态

2. 核心命令（Slash Commands）

/speckit.constitution

定义项目的不可协商规则和开发指南。

用途：

  • 编码规范（代码风格、命名约定）
  • 架构原则（DRY、SOLID 等）
  • 安全要求
  • 性能标准
  • 测试策略

示例内容：

/speckit.specify

描述要构建的功能，关注”是什么”和”为什么”。

关键要素：

  • 用户故事
  • 功能需求
  • 非功能需求
  • 边界条件
  • 验收标准

示例：

/speckit.clarify

通过系统化提问消除规范中的模糊性。

工作方式：

  • AI 自动识别不明确的需求
  • 提出具体的澄清问题
  • 记录答案到 Clarifications 部分

示例交互：

AI: 关于"账户锁定"功能，请澄清：
1. 锁定持续时间是多久？
2. 锁定后是否发送通知邮件？
3. 管理员是否可以手动解锁账户？

Developer:
1. 锁定 30 分钟后自动解锁
2. 发送包含解锁链接的通知邮件
3. 管理员可通过后台解锁

AI: 已记录澄清内容到 specification.md

/speckit.plan

制定技术实现方案，选择技术栈和架构。

包含内容：

  • 技术栈选型
  • 系统架构设计
  • 数据模型设计
  • API 设计
  • 第三方集成方案

示例：

/speckit.tasks

将计划分解为可执行的独立任务。

任务特征：

  • 原子性：每个任务独立完成一个功能点
  • 可测试：每个任务都有明确的验证标准
  • 有序性：任务按依赖关系排序
  • 并行标记：使用 [P] 标记可并行执行的任务

示例：

/speckit.implement

执行所有任务，构建功能。

执行策略：

  • 按照任务顺序逐个实现
  • 在每个检查点验证测试通过
  • 遵循 TDD（测试驱动开发）原则

工作流程：

  1. 读取 tasks.md
  2. 按顺序执行每个任务
  3. 运行相关测试验证
  4. 记录实现进度
  5. 处理依赖关系

3. 辅助命令

/speckit.analyze

验证规范、计划和任务之间的一致性。

检查项：

  • 规范中的需求是否都有对应任务
  • 任务是否符合技术方案
  • 是否存在冲突或遗漏

/speckit.checklist

生成质量验证清单。

清单内容：

  • 功能完整性检查
  • 代码质量标准
  • 安全性检查
  • 性能基准测试
  • 文档完整性

工作流程

完整开发流程图

阶段详解

阶段 1：基础建设（Foundation）

目标：建立清晰、无歧义的项目基础

输出：

  • constitution.md - 项目原则
  • specification.md - 功能规范
  • clarifications.md - 需求澄清

阶段 2：技术设计（Design）

目标：制定详细的技术实现方案

输出：

  • plan.md - 完整技术方案

阶段 3：任务分解（Breakdown）

目标：将大型功能分解为可管理的小任务

输出：

  • tasks.md - 结构化任务列表

阶段 4：自动实现（Implementation）

目标：自动化代码生成和测试验证

输出：

  • 源代码
  • 测试代码
  • 文档

迭代式开发流程

安装与配置

系统要求

  • Python: 3.8+ （用于 Specify CLI）
  • uv: Python 包管理器
  • Git: 版本控制
  • AI 助手: 以下任意一种
    • Claude Code
    • GitHub Copilot
    • Cursor
    • Windsurf
    • Gemini CLI
    • Qwen Code
    • 其他支持自定义命令的 AI 编码助手

安装步骤

1. 安装 uv 包管理器

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. 安装 SpecKit CLI

持久化安装（推荐）:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

一次性运行:

uvx --from git+https://github.com/github/spec-kit.git specify-cli init my-project

3. 验证安装

specify --version
specify check

项目初始化

创建新项目

# 初始化项目
specify init my-awesome-app

# 进入项目目录
cd my-awesome-app

# 查看生成的结构
tree .speckit

生成的目录结构：

my-awesome-app/
├── .speckit/
│   ├── commands/
│   │   ├── constitution.md
│   │   ├── specify.md
│   │   ├── clarify.md
│   │   ├── plan.md
│   │   ├── tasks.md
│   │   ├── implement.md
│   │   ├── analyze.md
│   │   └── checklist.md
│   ├── templates/
│   │   ├── constitution.template.md
│   │   ├── specification.template.md
│   │   ├── plan.template.md
│   │   └── tasks.template.md
│   └── config.yml
└── README.md

配置 AI 助手

Claude Code 配置

在 Claude Code 中，SpecKit 的命令会自动识别，无需额外配置。

GitHub Copilot 配置

确保安装了 GitHub Copilot Chat 扩展，命令会自动可用。

Cursor 配置

  1. 打开 Cursor 设置
  2. 启用自定义命令支持
  3. SpecKit 命令会自动加载

使用指南

快速开始示例

让我们通过一个完整的例子来演示 SpecKit 的使用。

场景：构建一个待办事项 API

Step 1: 初始化项目

specify init todo-api
cd todo-api

Step 2: 定义项目宪法

在 AI 助手中执行：

/speckit.constitution

AI 会引导你定义项目原则，示例输入：

我们要构建一个 RESTful 待办事项 API，请遵循以下原则：
- 使用 Node.js + TypeScript + Express
- 遵循 SOLID 原则和 Clean Architecture
- 所有 API 使用 OpenAPI 3.0 规范
- 单元测试覆盖率 > 80%
- 使用 JWT 进行身份验证
- 所有响应使用标准 JSON 格式
- 错误处理遵循 RFC 7807（Problem Details）

生成的 constitution.md:

Step 3: 编写功能规范

执行：

/speckit.specify

输入需求：

我需要实现待办事项的 CRUD 功能：
- 用户可以创建、查看、更新、删除待办事项
- 每个待办事项包含：标题、描述、状态（待办/完成）、创建时间、更新时间
- 用户只能操作自己的待办事项
- 支持按状态筛选
- 支持分页查询

生成的 specification.md:

Step 4: 澄清需求

执行：

/speckit.clarify

AI 会提出问题，示例：

AI: 我需要澄清以下细节：

1. 对于"标题最大 200 字符"，是按字符计数还是字节？是否包含 emoji？
2. 删除待办事项是硬删除还是软删除（标记为已删除但保留数据）？
3. 分页查询时，如果请求的页码超出范围，应该返回什么？
4. 是否需要待办事项的搜索功能（按标题/描述搜索）？
5. JWT token 的过期时间是多久？

Developer 回答：
1. 按 Unicode 字符计数，支持 emoji
2. 硬删除，直接从数据库删除
3. 返回空数组，不报错
4. 暂时不需要，后续版本再加
5. Access token 1小时，Refresh token 7天

AI 会将澄清内容追加到 specification.md。

Step 5: 制定技术方案

执行：

/speckit.plan

生成的 `plan.md`:

Step 6: 分解任务

执行：

/speckit.tasks

生成的 `tasks.md`:

Step 7: 执行实现

执行：

/speckit.implement

AI 会按照任务顺序逐个实现，示例输出：

开始执行任务...

✓ Task 1.1: Initialize project structure [完成]
  - 创建 package.json
  - 配置 TypeScript
  - 设置 ESLint 和 Prettier

✓ Task 1.2: Configure Prisma and database [完成]
  - 创建 Prisma schema
  - 配置数据库连接

✓ Task 1.3: Create database migration [完成]
  - 生成初始迁移
  - 应用迁移到数据库

✓ Task 2.1: Implement error handling middleware [完成]
  - 创建错误中间件
  - ✓ 5/5 单元测试通过

...

✓ Task 4.5: Create Todo routes [完成]
  - 定义 API 路由
  - ✓ 12/12 集成测试通过

✓ Task 5.1: Create Express application [完成]
  - 配置 Express 应用
  - 整合所有路由和中间件

🎉 所有任务已完成！

测试覆盖率: 85.3%
总测试数: 67
通过: 67
失败: 0

最佳实践

1. 规范编写最佳实践

✅ 好的规范

## User Story: Password Reset

**As a** registered user
**I want** to reset my password via email
**So that** I can regain access if I forget my password

**Acceptance Criteria**:
- [ ] User requests reset by providing email
- [ ] System sends reset link valid for 1 hour
- [ ] Link contains secure token (JWT with email claim)
- [ ] User can set new password (minimum 8 chars, 1 uppercase, 1 number)
- [ ] Old password immediately invalidated
- [ ] User receives confirmation email after reset

**Edge Cases**:
- Email not found → Show generic success message (security)
- Token expired → Show error with option to request new link
- Token already used → Show error`}
  client:only="react"
/>

#### ❌ 差的规范
```markdown
## Password Reset

Users should be able to reset password somehow.
Send an email with a link.

问题：

  • 缺少验收标准
  • 没有明确的用户故事格式
  • 未定义安全要求
  • 没有边界条件

2. 任务分解最佳实践

✅ 好的任务

❌ 差的任务

### Task: Add password reset

Implement password reset functionality.

**Files**: Some service files

**Test**: Make sure it works

问题：

  • 文件路径不明确
  • 没有依赖关系
  • 测试标准模糊
  • 缺少详细步骤

3. 测试驱动开发（TDD）

推荐流程：

示例：

4. 持续演进策略

Spec-as-Source 工作流

优势：

  • 规范始终是最新的
  • 减少代码审查时间（关注规范而非实现细节）
  • 更容易onboard新成员
  • 规范可用于生成文档、测试等

5. 团队协作最佳实践

规范审查流程

审查重点：

  1. 规范清晰度（其他人能理解吗？）
  2. 任务完整性（有遗漏吗？）
  3. 测试覆盖率（关键路径都测了吗？）
  4. 向后兼容性（会破坏现有功能吗？）

6. 常见陷阱和解决方案

陷阱 1: 规范过于宽泛

❌ 差的规范:
"用户应该能够管理待办事项"

✅ 好的规范:
"用户可以创建、查看、更新、删除自己的待办事项。
每个待办事项包含标题（必填，最多200字符）、描述（可选，最多2000字符）、
状态（待办/完成）。用户只能看到和操作自己创建的待办事项。"

陷阱 2: 忽略边界条件

❌ 缺少边界条件:
"API 返回待办事项列表"

✅ 包含边界条件:
"API 返回待办事项列表，支持分页（默认20条/页，最多100条/页）。
如果请求页码超出范围，返回空数组。
如果用户没有待办事项，返回空数组而非404。"

陷阱 3: 任务粒度不当

❌ 任务太大:
"Task: 实现整个待办事项系统"

✅ 任务合理:
"Task 4.1: 创建 Todo Repository（数据访问层）"
"Task 4.2: 实现 Todo Service（业务逻辑层）"
"Task 4.3: 创建 Todo Controller（控制器层）"

陷阱 4: 过早优化

❌ 在规范阶段讨论实现细节:
"使用 Redis 缓存所有查询结果以提高性能"

✅ 在计划阶段决定技术方案:
Specification: "API 响应时间应 < 200ms"
Plan: "使用 Redis 缓存热点数据，TTL 5分钟"

实战案例

案例 1: 微服务架构项目

场景: 构建电商平台的订单服务

Constitution 片段

# Order Service Constitution

## Microservices Principles
- Service owns its database (no shared databases)
- Communicate via async messaging (RabbitMQ)
- API Gateway for external access
- Circuit breaker for fault tolerance
- Distributed tracing with OpenTelemetry

## Event-Driven Architecture
- Publish domain events to message broker
- Event sourcing for order state changes
- CQRS pattern for read/write separation

Specification 片段

## US-1: Place Order

**Acceptance Criteria**:
- [ ] Validate inventory via Product Service (sync HTTP)
- [ ] Reserve inventory via InventoryReserved event
- [ ] Calculate total via Pricing Service (sync HTTP)
- [ ] Process payment via Payment Service (async)
- [ ] Publish OrderPlaced event
- [ ] Implement saga pattern for distributed transaction
- [ ] Rollback on any step failure

Plan 片段

案例 2: 前端应用开发

场景: 使用 React + TypeScript 构建仪表板

Constitution 片段

Tasks 片段

案例 3: CLI 工具开发

场景: 构建代码生成器 CLI

Specification 片段

总结

SpecKit 的核心价值

适用场景

✅ 非常适合：

  • 新功能开发
  • API 服务构建
  • 微服务架构
  • 大型重构
  • 团队协作项目

⚠️ 需要调整：

  • 快速原型（可简化为 Spec-First）
  • 紧急 bug 修复（先修复再补规范）
  • 实验性项目（规范可以更轻量）

❌ 不太适合：

  • 一次性脚本
  • 简单配置修改
  • 文档更新

学习路径建议

进一步学习资源

附录

A. 命令速查表

命令用途输出文件
specify init初始化项目.speckit/ 目录
specify check检查环境终端输出
/speckit.constitution定义项目原则constitution.md
/speckit.specify编写功能规范specification.md
/speckit.clarify澄清需求更新 specification.md
/speckit.plan制定技术方案plan.md
/speckit.tasks分解任务tasks.md
/speckit.implement执行实现源代码 + 测试
/speckit.analyze一致性检查终端输出
/speckit.checklist质量清单checklist.md

B. 常见问题

Q: SpecKit 是否支持非英语？ A: 支持。规范文档可以使用任何语言，AI 助手会根据其训练数据理解。

Q: 是否必须使用所有命令？ A: 不是。核心流程是 specify → plan → tasks → implement，其他命令可选。

Q: 如何处理遗留项目？ A: 可以逐步引入。先为新功能编写规范，再逐渐覆盖现有代码。

Q: SpecKit 与传统 PRD 的区别？ A: PRD 是一次性文档，SpecKit 的规范是可执行的、持续演进的源文件。

Q: 是否可以自定义命令？ A: 可以。修改 .speckit/commands/ 目录下的命令文件即可。

C. 工具对比

特性SpecKit传统开发低代码平台
灵活性⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
开发速度⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
代码质量⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
学习曲线⭐⭐⭐⭐⭐⭐⭐⭐⭐
AI 集成⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
可维护性⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐

版本: 1.0.0 最后更新: 2025-01-15 贡献者: SpecKit Community

本文档基于 SpecKit 官方文档和社区最佳实践编写，持续更新中。