GitHub Spec-Kit 使用指南
规范驱动开发（Spec-Driven Development） - 让 AI 编码更可控、更高效
一、什么是 Spec-Kit？
1.1 简介
Spec-Kit 是 GitHub 官方开源的规范驱动开发工具包，旨在改变传统的 AI 编码方式。
- 官方仓库 : github.com/github/spec...
- 支持的 AI 工具: Claude Code、GitHub Copilot、Cursor、Gemini CLI、Windsurf 等
1.2 核心理念
| 传统开发 | Spec-Driven 开发 |
|---|---|
| 想法 → 直接写代码 → 调试 → 补文档 | 想法 → 写规范 → AI 生成方案 → AI 实现 → 验证 |
| 代码是源头，文档是副产品 | 规范是源头，代码是规范的实现 |
| "Vibe Coding" - 凭感觉写 | 结构化、可预测、可追溯 |
1.3 为什么需要 Spec-Kit？
传统 AI 编码的问题：
- AI 理解不准确，生成的代码与预期不符
- 缺乏上下文，AI 无法理解项目架构约束
- 多人协作时，AI 生成的代码风格不一致
- 难以追溯需求和实现的对应关系
Spec-Kit 的解决方案：
- 规范即合约：AI 必须按照规范生成代码
- Constitution（章程）：定义项目的架构约束和编码规范
- 结构化流程：Specify → Plan → Tasks → Implement
- 质量门禁：每个阶段都有验证点
二、安装与配置
2.1 前置要求
- Node.js 18+ 或 Python 3.10+（用于 CLI）
- Git
- AI 编码工具（推荐 Claude Code）
2.2 安装方式
方式一：使用 uvx（推荐，无需安装）
bash
# 直接运行，无需安装
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --ai claude方式二：使用 uv 全局安装
bash
# 安装 CLI
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
# 初始化项目
specify init my-project --ai claude方式三：使用 npm/bun
bash
# 使用 bun
bun install -g @spec-kit/cli
# 或使用 npm
npm install -g @spec-kit/cli
# 初始化项目
specify init my-project --ai claude2.3 初始化项目
bash
# 新项目 + Claude Code
specify init my-project --ai claude
# 在当前目录初始化
specify init . --ai claude
# 跳过 git 初始化
specify init my-project --ai claude --no-git
# 其他 AI 工具
specify init my-project --ai copilot # GitHub Copilot
specify init my-project --ai cursor-agent # Cursor
specify init my-project --ai gemini # Gemini CLI2.4 初始化后的目录结构
text
my-project/
├── .specify/ # Spec-Kit 配置目录
│ ├── memory/
│ │ └── constitution.md # ⭐ 项目章程（架构约束）
│ ├── scripts/
│ │ ├── bash/ # Bash 脚本
│ │ └── powershell/ # PowerShell 脚本
│ └── templates/
│ ├── spec-template.md # 规范模板
│ ├── plan-template.md # 方案模板
│ └── tasks-template.md # 任务模板
├── specs/ # 规范文档存放目录
│ └── 001-feature-name/
│ ├── spec.md # 功能规范
│ ├── plan.md # 技术方案
│ └── tasks.md # 任务列表
└── .claude/commands/ # Claude Code 自定义命令
├── specify.md
├── plan.md
├── tasks.md
└── implement.md三、工作流程
3.1 六阶段流程
text
Constitution → Specify → Clarify → Plan → Tasks → Implement
↓ ↓ ↓ ↓ ↓ ↓
项目章程 功能规范 需求澄清 技术方案 任务拆分 代码实现3.2 核心命令
| 阶段 | 命令 | 作用 | 输出物 |
|---|---|---|---|
| 1. Specify | /specify |
定义功能规范（WHAT） | spec.md |
| 2. Clarify | /clarify |
澄清模糊需求 | 更新 spec.md |
| 3. Plan | /plan |
生成技术方案（HOW） | plan.md |
| 4. Tasks | /tasks |
拆分可执行任务 | tasks.md |
| 5. Implement | /implement |
执行代码实现 | 源代码 |
| 6. Analyze | /analyze |
质量检查 | 分析报告 |
3.3 详细流程说明
阶段一：编写 Constitution（章程）
Constitution 是项目的"宪法"，定义了：
- 技术栈和架构约束
- 编码规范和命名规则
- 依赖策略
- 设计原则
示例（.specify/memory/constitution.md）：
markdown
# 项目章程
## 技术栈
- 后端：Spring Boot 2.7 + MyBatis Plus + Dubbo 3.3
- 数据库：MySQL 8.0 + Redis
- 前端：Vue 3 + Element Plus
## 架构约束
- 分层架构：Controller/DubboApi → Service → Mapper
- Entity 必须放在 xxx.api.entity 包下
- 禁止在 Controller/DubboApi 中写业务逻辑
## 编码规范
- 使用 Spring Java Format 格式化代码
- 方法必须有 JavaDoc 注释
- 增删改操作必须添加 @Transactional
## 命名规则
- Entity：大驼峰，如 UserInfo
- Service 接口：I{Entity}Service，如 IUserInfoService
- Mapper：{Entity}Mapper，如 UserInfoMapper阶段二：Specify（功能规范）
bash
# 在 Claude Code 中执行
/specify输入功能描述后，AI 会生成：
- 功能分支（如
001-user-login） - 规范目录（
specs/001-user-login/） - 规范文档（
spec.md）
spec.md 示例：
markdown
# 功能规范：用户登录
## 背景
当前系统没有用户登录功能，需要实现基于手机号+验证码的登录流程。
## 用户故事
- 作为用户，我希望通过手机号和验证码登录，以便访问我的个人中心。
- 作为用户，我希望在验证码错误时收到明确提示。
## 验收标准
1. [ ] 用户输入手机号，点击发送验证码，后端生成并发送（模拟）。
2. [ ] 验证码有效期 5 分钟。
3. [ ] 登录成功返回 JWT Token。
4. [ ] 登录失败提示具体原因（验证码错误/过期）。
## 业务规则
- 手机号必须是 11 位数字。
- 同一手机号 1 分钟内只能请求一次验证码。阶段三：Plan（技术方案）
在明确了"做什么"之后，下一步是确定"怎么做"。
bash
# 在 Claude Code 中执行
/plan输入 ：spec.md + constitution.md 或直接回车
输出 ：plan.md
plan.md 示例：
markdown
# 技术方案：用户登录
## 架构决策
- 使用 Redis 存储验证码，Key 格式：`auth:code:{phone}`。
- 使用 JJWT 库生成 Token。
- 遵循 Controller -> Service -> Manager -> Mapper 分层。
## 数据库变更
- 无需新增表，复用 `user_info` 表。
## API 设计
1. POST /api/v1/auth/code
- Req: { phone: string }
- Res: { success: boolean }
2. POST /api/v1/auth/login
- Req: { phone: string, code: string }
- Res: { token: string, user: UserInfo }
## 模块设计
- `AuthController`: 处理 HTTP 请求。
- `AuthService`: 核心业务逻辑（校验、颁发 Token）。
- `SmsManager`: 对接短信网关（Mock 实现）。阶段四：Tasks（任务拆分）
将技术方案拆解为 AI 可以独立执行的原子任务（Atomic Tasks）。
bash
# 在 Claude Code 中执行
/tasks输入 ：plan.md 或直接回车
输出 ：tasks.md
tasks.md 示例：
markdown
# 任务列表
## 1. 基础设施
- [ ] Task 1.1: 添加 JJWT 和 Redis 依赖到 `pom.xml`。
- [ ] Task 1.2: 配置 Redis 连接参数。
## 2. 核心逻辑
- [ ] Task 2.1: 创建 `SmsManager` 并实现发送模拟逻辑。
- [ ] Task 2.2: 创建 `AuthService` 接口及实现，编写 `sendCode` 方法。
- [ ] Task 2.3: 在 `AuthService` 中实现 `login` 方法（含 Token 生成）。
## 3. 接口层
- [ ] Task 3.1: 创建 `AuthController` 并暴露 REST 接口。
- [ ] Task 3.2: 编写 Controller 层单元测试。阶段五：Implement（执行实现）
AI 逐个读取任务并执行。
bash
# 在 Claude Code 中执行
/implement执行逻辑：
- AI 读取
tasks.md中第一个未完成的任务。 - 读取相关文件上下文。
- 编写代码。
- 运行测试（如果定义了验证步骤）。
- 标记任务为
[x]。 - 重复上述步骤，直到所有任务完成。
阶段六：Analyze（质量检查）
bash
# 在 Claude Code 中执行
/analyze对生成的代码进行质量分析，检查是否符合 constitution.md 中的规范，例如：
- 是否遗漏了 JavaDoc？
- 是否使用了被禁止的类？
- 事务注解是否添加？
四、最佳实践
4.1 什么时候使用 Spec-Kit？
- 推荐：复杂功能开发、需要多人协作、对代码质量有严格要求。
- 不推荐：简单的 Bug 修复、临时脚本、纯文案修改。
4.2 存量项目接入（Brownfield）
对于已有项目，不需要一次性补全所有文档。可以采用增量接入策略：
- 初始化 Spec-Kit。
- 配置
constitution.md以反映当前项目的最佳实践。 - 在开发新功能时，按照 Specify -> Plan -> Tasks -> Implement 流程进行。
- 对于旧代码的重构，可以先让 AI 读取旧代码生成
spec.md（逆向工程），再进行修改。
五、高级特性
5.1 自定义规范模板
你可以创建自己的规范模板，以适应不同的项目需求或团队标准。
python
# spec_templates/my_template.py
TEMPLATE = """
项目名称: {project_name}
技术栈: {tech_stack}
功能模块: {features}
性能要求: {performance}
"""5.2 集成 CI/CD
Spec-Kit 可以与 CI/CD 工具集成，确保所有提交的规范和代码都符合标准。
yaml
# .github/workflows/spec-kit.yml
name: Spec-Kit Validation
on: [push]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Validate Specifications
run: specify validate5.3 团队协作模式
通过共享规范库实现团队协作，确保所有人使用统一的规范。
bash
# 导出规范
specify export --output team-specs.json
# 导入团队规范
specify import team-specs.json六、与现有工作流整合
6.1 与 Claude Code 集成
初始化后，Claude Code 自动获得 /specify、/plan、/tasks、/implement 命令。
6.2 与 Git 工作流整合
bash
# 1. 开始新功能
/specify "实现用户登录功能"
# AI 自动创建分支：001-user-login
# 2. 完成规范和方案
/plan
/tasks
# 3. 实现代码
/implement
# 4. 代码审查
/review-code
# 5. 提交 PR
git add .
git commit -m "feat: 实现用户登录功能"
git push6.3 与现有项目规范整合
将公司现有规范整合到 Constitution 中：
markdown
# .specify/memory/constitution.md
## 引用公司规范
本项目遵循《城市停车微服务框架规范》，详见 CLAUDE.md
## 补充约束
- Entity 必须在 xxx.api.entity 包下
- 使用 ThreadPoolFactory 创建线程池
- 分页查询必须调用 startDubboPage()七、常见问题 (FAQ)
Q1: Spec-Kit 支持哪些编程语言？ Spec-Kit 是语言无关的，支持所有主流编程语言，包括 Python, Java, JavaScript, TypeScript, Go, Rust 等。它通过自然语言描述规范，因此不受限于特定编程语言。
Q2: 发现代码逻辑走不通怎么办？
千万不要直接改代码！ 这会破坏"规范即源码"的原则，导致文档与代码脱节。 正确做法：
- 回滚 ：回到
Plan阶段。 - 修改 ：更新
plan.md中的技术决策或tasks.md中的任务拆分。 - 重生成：让 AI 重新生成受影响的代码。
Q3: 如何避免 Spec 文档腐烂？
- 定期归档 ：Sprint 结束后，将完成的
specs/下的文档移动到docs/archive/，保持工作区整洁。 - 反哺章程 ：如果某个 Spec 引入了新的通用模式（例如确立了"新的权限控制方案"），应将其总结并更新到
.specify/memory/constitution.md中，使其成为后续开发的标准。
Q4: 团队如何协作？
- 产品经理 (PM) : 负责 Review
spec.md，重点关注验收标准（Acceptance Criteria）是否覆盖业务需求。 - 架构师 / Tech Lead : 负责 Review
plan.md，把控技术方案、数据库设计和 API 定义是否符合架构规范。 - 开发者 : 负责执行
tasks.md，并监督 AI 生成的代码质量，进行最终的 Code Review。
七、参考资料
- 官方仓库: github.com/github/spec...
- 官方博客: github.blog/ai-and-ml/g...
- Martin Fowler 文章: martinfowler.com/articles/ex...
- Microsoft 教程: developer.microsoft.com/blog/spec-d...
- 本文档参考来源: blog.csdn.net/a309220728/...
八、总结
Spec-Kit 不仅仅是一个工具，更是一种工程化思维 的体现。它通过强制的结构化流程，解决了 AI 编程中常见的"幻觉"、"上下文丢失"和"不可控"问题。
- 对于个人开发者：它是你的"外脑"，帮你理清思路，保持代码整洁。
- 对于团队：它是无形的"架构师"，确保所有 AI 生成的代码都遵循统一的团队规范。