跟着 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）
  • 需要高质量和可维护性的项目
  • 多人协作或需要频繁交接的项目
  • 初创团队希望建立工程规范

不适用场景:

  • 非常简单的原型（过度设计）
  • 算法研究型项目（需求不明确）
  • 遗留系统重构（缺少清晰的功能边界）
相关推荐
passerby606123 分钟前
完成前端时间处理的另一块版图
前端·github·web components
掘了30 分钟前
「2025 年终总结」在所有失去的人中，我最怀念我自己
前端·后端·年终总结
崔庆才丨静觅33 分钟前
实用免费的 Short URL 短链接 API 对接说明
前端
崔庆才丨静觅1 小时前
5分钟快速搭建 AI 平台并用它赚钱！
前端
崔庆才丨静觅1 小时前
比官方便宜一半以上！Midjourney API 申请及使用
前端
Moment1 小时前
富文本编辑器在 AI 时代为什么这么受欢迎
前端·javascript·后端
崔庆才丨静觅2 小时前
刷屏全网的“nano-banana”API接入指南！0.1元/张量产高清创意图，开发者必藏
前端
剪刀石头布啊2 小时前
jwt介绍
前端
爱敲代码的小鱼2 小时前
AJAX（异步交互的技术来实现从服务端中获取数据）：
前端·javascript·ajax
一切尽在，你来2 小时前
第二章 预告内容
人工智能·langchain·ai编程
热门推荐
01GitHub 镜像站点02Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services03openclaw配置教程（linux+局域网ollama）04Linux下V2Ray安装配置指南05OpenClaw Chrome扩展使用教程 - 浏览器中继控制06UV安装并设置国内源07Claude Code Skills 实用使用手册08一文了解国产算子编程语言 TileLang，TileLang 对国产开源生态的影响与启示09Vue-skills的中文文档10让 Trae IDE 智能体 “读懂”文档 Excel+PDF+DOCX ：mcp-documents-reader 工具使用指南