跟着 AI 学（三）- spec-kit +claude code 从入门到出门

潘小安2025-11-02 19:29

什么是 spec-kit

pec-kit 是一种基于"规范驱动开发"（Specification-Driven Development）理念的工程方法论，通过一套结构化的命令和文档模板，将软件开发从模糊的需求转化为可执行的代码。

spec-kit 的核心价值在于将混沌的软件开发过程 转变为结构化的、可预测的流水线。它不是为了增加额外的工作量，而是通过前期必要的投入（写清楚规格和计划），来换取后期巨大的收益（减少返工、提升质量、加速交付）。

它特别适合于：

  • 需要高质量和高可靠性的项目（如金融、医疗系统）。
  • 有多方协作的复杂项目（涉及前后端、移动端、多个团队）。
  • 希望建立良好工程文化的初创公司或成长型团队。

最终，spec-kit 帮助团队从"救火队员"转变为"建筑师"，把精力集中在创造价值上，而不是疲于应对由混乱流程带来的各种问题。

claude code + spec-kit

  • spec-kit: 提供标准化的文档模板、工作流命令和质量检查机制
  • Claude Code: 理解和执行 spec-kit 命令，生成文档，分析代码，执行开发任务

spec-kit 的核心工作流可以概括为一个清晰的五步循环：

markdown 复制代码 
Specify → Clarify → Plan → Tasks → Implement
       ↑___________________________________|
                   Analyze (Quality Gate)

每个步骤都有明确的输入和输出，并由专门的命令（slash command）驱动。这个流程确保了在编码前完成充分的需求分析和技术设计，避免了传统开发中常见的"边写边想"导致的返工和质量问题。

详细步骤说明

1. Specify: 创建功能规格 (spec.md)

目标: 将模糊的自然语言需求转化为结构化的、可执行的功能规格说明书。

触发命令 : /speckit.specify <feature description>

输入:

  • 自然语言的功能描述（如 "帮我做一个学生选课系统"）
  • 可选参数：--short-name 指定分支短名称，--number 指定分支编号

输出:

  • 新的 Git 分支（格式 ###-feature-name）
  • 在 specs/###-feature-name/ 目录下创建 spec.md 文件
  • 设置环境变量 SPECIFY_FEATURE

内部流程:

  1. 分支命名 : Claude Code 解析功能描述，生成有意义的分支名称。例如 "学生选课系统" 会生成 001-student-course-selection。
  2. 文件初始化 : Claude Code 基于 .specify/templates/spec-template.md 创建 spec.md，自动填充上下文摘要、用户故事框架等。
  3. 环境设置 : 导出 SPECIFY_FEATURE 环境变量，供后续命令使用。

关键产出 - spec.md 结构:

markdown 复制代码 
# Feature Specification: [FEATURE NAME]

## 上下文摘要 (Context Summary)
- **背景**: 当前状态和问题
- **目标用户**: 功能的使用者
- **核心问题**: 要解决的关键痛点
- **预期价值**: 功能带来的量化收益

## User Scenarios & Testing
- 按优先级排序的用户故事（P1, P2, P3...），每个都必须是独立可测试的

## Requirements
- 编号的功能需求列表（FR-001, FR-002...），明确使用 MUST/SHOULD
- 关键实体定义

## Success Criteria
- 可测量的成功指标（SC-001, SC-002...）

目的: 统一团队对需求的理解，防止因理解偏差导致的开发错误。

2. Clarify: 需求澄清与确认

目标: 识别并解决 spec.md 中的所有模糊点和不确定性。

触发命令 : /speckit.clarify

触发时机 : 当 spec.md 中存在 [NEEDS CLARIFICATION] 标记时，或团队认为需求不够明确时。

工作流程:

  1. 问题提取 : Claude Code 扫描 spec.md，找出所有需要进一步解释的地方（如未指定的技术方案、模糊的业务规则）。
  2. 用户提问: Claude Code 向产品负责人或相关干系人提出具体问题，获取确切答案。
  3. 文档更新 : Claude Code 将用户的回答整合回 spec.md，替换原有的 [NEEDS CLARIFICATION] 标记。
  4. 验证闭环 : 确认所有澄清项都已解决，spec.md 达到"可实施"状态。

示例:

diff 复制代码 
- FR-008: 系统 MUST 在选课冲突时 [NEEDS CLARIFICATION: conflict resolution strategy]
+ FR-008: 系统 MUST 在选课冲突时提示用户时间冲突，并阻止重复选课

目的: 确保需求完全明确，为后续的技术设计提供坚实基础，避免"假设性开发"。

3. Plan: 制定技术实施计划 (plan.md)

目标: 将经过确认的需求转化为具体的技术实现方案。

触发命令 : /speckit.plan

输入 : 已完成的 spec.md（已通过澄清阶段）

输出:

  • plan.md: 详细的实施计划
  • （可选）research.md, data-model.md, quickstart.md, contracts/api.openapi.yaml

内部流程 (Phase-Based):

Phase 0: 技术调研 (Research)

  • 任务: Claude Code 调研备选技术栈（如 React vs Vue）、第三方服务集成方式。
  • 输出 : research.md，记录决策理由和风险评估。

Phase 1: 设计 (Design)

  • 任务: Claude Code 设计数据模型、API 契约、项目目录结构。
  • 输出 :
    • data-model.md: 数据库 Schema 和 ER 图（如 Course, Student, Enrollment 等实体）
    • contracts/api.openapi.yaml: OpenAPI 规范，前后端契约
    • quickstart.md: 开发环境搭建指南

Phase 2: 整合与输出

  • 任务 : Claude Code 综合所有信息，生成最终的 plan.md。
  • 输出 : plan.md，包含技术上下文、项目结构、部署策略等。

关键检查点 - Constitution Check : 在 plan.md 中有一个强制检查环节，确保技术方案符合 constitution.md 的原则，例如：

  • ✅ 清晰沟通优先
  • ✅ 文档规范
  • ✅ 用户体验至上
  • ✅ 隐私与安全不可协商
  • ✅ 测试优先
  • ✅ 可观测性
  • ✅ 简单优先

目的: 在动手编码前完成充分的技术设计，降低实现风险，确保架构合理性。

4. Tasks: 生成任务分解清单 (tasks.md)

目标: 将宏观的设计方案分解为微观的、可执行的开发任务。

触发命令 : /speckit.tasks

输入:

  • 必需: plan.md
  • 推荐: spec.md（用户故事）、data-model.md、contracts/

输出 : tasks.md，一份详尽的任务清单。

任务组织结构:

ini 复制代码 
## Phase 1: Project Setup
- [ ] T001 Create backend directory
- [ ] T002 Initialize Node.js project
...

## Phase 2: Foundational Infrastructure
- [ ] T024 Define Prisma schema for Student and Course models
- [ ] T025 Implement JWT authentication middleware
...

## Phase 3: User Story 1 - 浏览课程列表 (Priority: P1)
- [ ] T061 [US1] Implement course listing service
- [ ] T062 [US1] Implement course search API
...

## Phase 4: User Story 2 - 选课和退课 (Priority: P1)
- [ ] T078 [US2] Implement enrollment service
- [ ] T079 [US2] Add conflict detection logic
...

关键特性:

  • [P] 标记: 表示该任务可以与其他任务并行执行。
  • [USX] 标记: 将任务关联到具体的用户故事，便于追踪。
  • 依赖关系: 通过章节顺序（Setup → Foundational → User Stories）隐式定义。
  • MVP 范围: 明确指出哪些 Phase 构成了最小可行产品（MVP）。

目的: 提供一张清晰的"施工图纸"，指导开发者有序、高效地完成工作，支持增量交付。

5. Implement: 执行开发任务

执行之前，可以使用内置 /comapct 指令压缩之前的上下文，保留一个上下文的 snpshot，给接下来的 implement 流程预留 context 空间。

目标 : 完成 tasks.md 中列出的所有任务，将设计变为现实。

触发命令 : /speckit.implement

工作流程:

  1. 读取任务 : Claude Code 解析 tasks.md 文件，获取任务列表。
  2. 顺序执行: Claude Code 按照任务的依赖关系（通常是章节顺序）逐个处理。
  3. 任务执行 :
    • Claude Code 对于每个任务，调用相应的工具（Read, Edit, Write）来修改代码。
    • 运行相关的单元测试或集成测试以验证更改。
    • 使用 git add 和 git commit 提交已完成的任务。
  4. 进度跟踪 : Claude Code 实时更新 tasks.md，将完成的任务标记为 [x]。
  5. 循环直至完成: 重复上述过程，直到所有任务都被标记为完成。

自动化程度:

  • Claude Code 主要用于生成样板代码、修改配置文件、重命名等重复性高、逻辑简单的任务。
  • 复杂的业务逻辑和算法实现（如选课冲突检测算法）仍需人工编写，但 tasks.md 提供了明确的指引。

目的: 最大化开发效率，减少手动操作错误，确保开发过程与计划一致。

6.### 质量保障: /speckit.analyze

在整个工作流中，/speckit.analyze 命令扮演着"质量门禁"的角色。Claude Code 可以在任何关键节点运行此命令，对所有相关文档进行一致性分析。

检查内容:

  • 完整性 : 是否缺少必要的文档（如 plan.md）？
  • 一致性 : spec.md 中的需求是否都在 plan.md 中有对应的设计？tasks.md 是否覆盖了所有设计要点？
  • 合规性 : 技术方案是否违反了 constitution.md 中的任何不可协商原则？
  • 可行性: 任务分解是否合理，是否存在过于宽泛或模糊的任务？

输出: Claude Code 生成一份包含 LOW/MEDIUM/HIGH 严重性问题的分析报告，帮助团队在早期发现问题。

示例问题:

  • MEDIUM: spec.md 中提到的"选课人数限制"功能在 tasks.md 中没有对应任务
  • HIGH: plan.md 中使用了敏感数据明文存储，违反了 constitution.md 的"隐私与安全不可协商"原则

增量交付与并行开发

spec-kit 的工作流天然支持现代软件开发的最佳实践：

增量交付 (Incremental Delivery)

  • MVP First: 优先实现 P1 用户故事（如登录、浏览课程、选课）。
  • 独立可测试: 每个用户故事完成后即可测试和演示，无需等待整个功能完成。
  • 快速反馈: 早期就能获得用户反馈，及时调整方向。

示例:

  • 第一周: 完成用户登录 + 课程列表浏览（可独立演示）
  • 第二周: 完成选课功能（在第一周基础上增量添加）
  • 第三周: 完成课程评价和推荐（P2 功能，可选）

并行开发 (Parallel Development)

  • 跨阶段并行: 不同的团队或个人（或多个 Claude Code 会话）可以同时负责不同 Phase 的任务（如前端做 UI，后端做 API）。
  • 跨用户故事并行: 一旦"基础设施"（Foundational）完成，多个 P2/P3 用户故事可以并行开发。
  • 任务内并行 : 标记为 [P] 的任务可以在同一 Phase 内并行执行。

这种模式极大地提升了开发速度和资源利用率。

实际案例：学生选课系统开发全流程

以下是一个完整的实战示例，展示如何使用 spec-kit + Claude Code 从零开始开发学生选课系统。

Day 1: 需求定义

bash 复制代码 
用户: /speckit.specify 帮我做一个学生选课系统，学生可以浏览课程、选课、退课，并查看自己的课表

Claude Code 输出:

  • 创建分支 001-student-course-selection
  • 生成 specs/001-student-course-selection/spec.md
  • 包含 8 个用户故事（US1-US8），按 P1/P2/P3 分级
  • 包含 25 个功能需求（FR-001 ~ FR-025）

发现问题 : spec.md 中有 3 处 [NEEDS CLARIFICATION]：

  1. 学生选课是否有人数上限？
  2. 时间冲突时如何处理？
  3. 是否需要课程评价功能？

Day 2: 需求澄清

bash 复制代码 
用户: /speckit.clarify

Claude Code 提问:

  1. Q: 学生选课是否有人数上限？ A: 是的，每门课程有 capacity 字段，选课人数达到上限后不能再选

  2. Q: 时间冲突时如何处理？ A: 系统应该检测时间冲突并阻止选课，提示用户"与已选课程 XXX 时间冲突"

  3. Q: 是否需要课程评价功能？ A: 这是 P2 功能，先实现核心选课功能

Claude Code 输出:

  • 更新 spec.md，移除所有 [NEEDS CLARIFICATION] 标记
  • 添加 FR-026: 系统 MUST 在选课时检测人数上限
  • 添加 FR-027: 系统 MUST 在选课时检测时间冲突

Day 3: 技术设计

bash 复制代码 
用户: /speckit.plan

Claude Code 执行:

  • Phase 0: 调研技术栈

    • 前端: React + TypeScript + Ant Design
    • 后端: Node.js + Express + Prisma + PostgreSQL
    • 理由: 团队熟悉，符合"简单优先"原则

  • Phase 1: 设计数据模型

    • 生成 data-model.md，包含 Student, Course, Enrollment 三个核心实体
    • ER 图显示关系: Student ↔ Enrollment ↔ Course

  • Phase 1: 定义 API 契约

    • 生成 contracts/api.openapi.yaml
    • 10 个 REST API 端点（GET /courses, POST /enrollments 等）

  • Constitution Check: ✅ 全部通过

Claude Code 输出:

  • 生成 plan.md（12 页）
  • 生成 research.md（技术选型理由）
  • 生成 data-model.md（数据库设计）
  • 生成 quickstart.md（环境搭建指南）

Day 4: 任务分解

bash 复制代码 
用户: /speckit.tasks

Claude Code 输出:

  • 生成 tasks.md，包含 156 个任务
  • 分为 7 个 Phase:
    • Phase 1: Project Setup (T001-T023)
    • Phase 2: Foundational Infrastructure (T024-T060)
    • Phase 3: US1 - 浏览课程列表 (T061-T075)
    • Phase 4: US2 - 选课和退课 (T076-T098)
    • Phase 5: US3 - 查看课表 (T099-T115)
    • Phase 6: US4 - 课程搜索 (T116-T132)
    • Phase 7: Polish & Documentation (T133-T156)

Day 5: 质量检查

bash 复制代码 
用户: /speckit.analyze

Claude Code 分析报告:

  • ✅ 完整性: 所有文档齐全
  • ✅ 一致性: spec.md 的 27 个需求都在 plan.md 中有设计，tasks.md 覆盖所有设计
  • ⚠️ MEDIUM: FR-026（人数上限检查）在 tasks.md 中只有后端任务，缺少前端错误提示任务
  • ✅ 合规性: 符合所有 constitution 原则

用户操作: 要求 Claude Code 补充缺失任务

makefile 复制代码 
用户: 请在 tasks.md 的 Phase 4 中添加前端错误提示任务

Claude Code: 添加 T099-A: [US2] Display enrollment capacity error in frontend

Day 6-10: 开发实施

选项 1: 全自动实施（适合简单项目）

bash 复制代码 
用户: /speckit.implement

Claude Code 自动完成所有 156 个任务（样板代码为主）

选项 2: 分阶段手动实施（推荐）

makefile 复制代码 
用户: 请帮我完成 Phase 1 和 Phase 2 的所有任务

Claude Code 完成基础设施搭建（T001-T060）

makefile 复制代码 
用户: 请帮我完成 Phase 3 (US1 - 浏览课程列表)

Claude Code 完成第一个用户故事（T061-T075）

此时可以运行系统，测试课程列表功能，获得早期反馈。

Day 11: 验收和上线

  • 运行完整测试套件
  • 创建 Pull Request
  • Code Review（基于 spec.md 和 constitution.md）
  • 合并到主分支
  • 部署到生产环境

最终交付:

  • ✅ 4 个 P1 用户故事全部完成
  • ✅ 测试覆盖率 85%+
  • ✅ 完整的 API 文档（OpenAPI）
  • ✅ 完整的开发文档（spec.md, plan.md）
  • ✅ 0 个 P1/P2 bug

总结：spec-kit + Claude Code 的核心优势

  1. 结构化流程: spec-kit 提供清晰的工作流，Claude Code 严格执行，避免遗漏
  2. 质量保证: Constitution Check 和 Analyze 确保符合最佳实践
  3. 高效协作: 文档自动生成，团队成员理解一致
  4. 增量交付: 支持 MVP 优先，快速获得反馈
  5. 可追溯性: 从需求到代码的完整链路可追溯（FR-XXX → Task TXXX → Git Commit）

适用场景:

  • 中等复杂度的 B2B/B2C 应用（如选课系统、订单管理、CRM）
  • 需要高质量和可维护性的项目
  • 多人协作或需要频繁交接的项目
  • 初创团队希望建立工程规范

不适用场景:

  • 非常简单的原型（过度设计）
  • 算法研究型项目（需求不明确）
  • 遗留系统重构（缺少清晰的功能边界）
相关推荐
金梦人生8 小时前
让 CLI 更友好：在 npm 包里同时支持“命令行传参”与“交互式对话传参”
前端·npm
Mintopia8 小时前
🐋 用 Docker 驯服 Next.js —— 一场前端与底层的浪漫邂逅
前端·javascript·全栈
Mintopia8 小时前
物联网数据驱动 AIGC：Web 端设备状态预测的技术实现
前端·javascript·aigc
一个W牛9 小时前
报文比对工具（xml和sop）
xml·前端·javascript
鸡吃丸子9 小时前
浏览器是如何运作的？深入解析从输入URL到页面渲染的完整过程
前端
作业逆流成河9 小时前
🔥 enum-plus 3.0：介绍一个天花板级的前端枚举库
前端·javascript·前端框架
爱喝水的小周9 小时前
《UniApp 页面导航跳转全解笔记》
前端·uni-app
蒜香拿铁9 小时前
Angular【组件】
前端·javascript·angular.js
ByteCraze9 小时前
一文讲透 npm 包版本管理规范
前端·arcgis·npm
热门推荐
01GitHub 镜像站点02BongoCat - 跨平台键盘猫动画工具03UV安装并设置国内源04Linux下V2Ray安装配置指南05安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）06KGG转MP3工具|非KGM文件|解密音频07jdk21下载、安装（Windows、Linux、macOS）08GitLab 零基础入门指南：从安装到项目管理全流程09NVIDIA显卡驱动、CUDA、cuDNN 和 TensorRT 版本匹配指南10在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）