Step 1. 环境准备与安装

What

安装 Spec-Kit 工具和相关依赖，确保你的开发环境支持规范驱动开发工作流。

Why

spec-kit 依赖于 Python 3.11+、AI 编程代理（如 Copilot、Claude、Gemini、Cursor 等）、脚本工具和包管理器。只有正确安装这些组件，才能体验自动化和结构化开发流程。

How

  1. 安装 Python 3.11+
  2. 安装 uv 包管理器
    • 命令：pip install uv
  3. 安装 git 工具
    • 命令：git --version
  4. 准备 AI 编程代理
  5. 克隆 spec-kit 仓库（可选）
    • git clone https://github.com/github/spec-kit.git
  6. 初始化项目
    • 推荐用 uvx 脚本自动拉取：
      1. uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
      • 支持 --script sh 或 --script ps 强制脚本类型（bash/zsh 或 PowerShell）

Spec-Kit使用教程详解 - 图1

Step 2. 创建规范（Spec）

What

用 /specify 命令描述你要做的产品或功能，关注“做什么”和“为什么”，不涉及技术实现。

Why

这是 SDD 的灵魂环节，所有开发工作都围绕规格展开。通过结构化规范，可以让 AI 和工具自动识别、生成后续工程产物。

How

  1. 运行 AI 编程代理（如 Copilot/Claude）并进入项目目录
  2. 用 /specify 命令撰写需求
    • 示例：
      1. /specify Build an application that helps organize photos into albums by date, supports drag-and-drop sorting, shows album tiles, and does not nest albums.
  3. 补充细节和场景
    • 说明用户如何使用、涉及哪些数据对象、业务约束等
    • 示例：
      1. /specify Users can preview photos in each album, move albums between dates, and all actions should be undoable.
  4. AI 自动生成 specs 文件夹和分支
    • 结构类似：
      1. ├── specs
      2. │   └── 001-photo-album-organizer
      3. │       └── spec.md

Step 3. 需求澄清与完整性检查

What

检查自动生成的规范文档，补充澄清点（[NEEDS CLARIFICATION]），完善功能需求和测试场景。

Why

确保所有需求都明确、无歧义且可测试，是高质量工程的基础。

How

  1. 打开 specs/xxx/spec.md，查找 [NEEDS CLARIFICATION] 标记
  2. 逐条补充说明或与 AI 交互澄清
    • 示例：
      1. /specify Album date definition: is it creation date, import date, or user可自定义？
  3. 补充/校验测试场景
    • 如：用户能否批量移动照片？是否支持多用户？
  4. 检查评审清单（Review & Acceptance Checklist）
    • 确认所有需求都可测试，有明确成功标准

Step 4. 技术实现计划（Implementation Plan）

What

用 /plan 命令生成详细的技术方案，包括技术选型、架构设计、接口合约、数据模型等。

Why

将业务需求转化为可执行的技术方案，是工程落地的关键环节。

How

  1. 用 /plan 命令描述技术方案
    • 示例：
      1. /plan Use Vite + vanilla HTML/CSS/JS for frontend, local SQLite db for metadata, images stored locally, no cloud upload.
  2. AI 根据规格与技术约束生成 plan.md、data-model.md、contracts/ 等文件
    • 结构示例：
      1. ├── specs
      2. │   └── 001-photo-album-organizer
      3. │       ├── plan.md
      4. │       ├── data-model.md
      5. │       ├── contracts/
      6. │       │   └── api-spec.json
      7. │       └── spec.md
  3. 补充/审查实现细节与架构决策
    • 说明每个技术选型的理由
    • 检查是否符合项目“宪法”原则（如模块化优先、CLI接口强制、测试优先等）

Step 5. 任务分解与并行执行

What

用 /tasks 命令自动生成开发任务列表，支持并行任务标记，便于团队分工与进度管理。

Why

结构化任务分解可以提高开发效率，减少遗漏和重复劳动。

How

  1. 运行 /tasks 命令
    • 自动分析 plan.md、contracts、data-model 等，输出 tasks.md
  2. 查看并分配任务
    • 任务文件格式清晰，支持 [P] 并行标记
    • 示例任务列表片段：
      1. - [ ] [P] Create SQLite schema for albums/photos
      2. - [ ] Implement drag-and-drop logic in frontend
      3. - [ ] Write API endpoints for CRUD operations
      4. - [ ] Write integration tests for album reordering
  3. 同步到团队任务管理工具（如 GitHub Projects、Jira、Trello 等）

Step 6. 测试优先与实现落地

What

严格按照测试优先原则，先编写/完善测试用例，确保所有功能均有对应测试；实现代码以通过测试为目标。

Why

测试优先可大幅提升工程质量，减少后期返工与隐患。

How

  1. 根据 contracts 和 tasks，逐步编写/完善测试代码
    • 包括 API 合约测试、集成测试、端到端测试、单元测试等
  2. 实现业务逻辑，使所有测试全部通过
    • 遇到测试失败，优先修正实现而不是修改测试
  3. 持续交互与 AI 反馈，优化实现和测试覆盖率

Step 7. 迭代优化与持续反馈

What

在项目运行和交付过程中，根据用户反馈、性能监控等数据持续优化规格和实现。

Why

让工程始终保持与业务目标一致，快速响应市场和用户变化。

How

  1. 收集生产环境指标和用户反馈
    • 性能瓶颈、bug、用户行为等
  2. 更新规格和技术方案，触发自动再生成
    • 重新运行 /specify、/plan、/tasks，更新所有相关文档和代码
  3. 形成持续迭代闭环，保持工程活力和质量

总结

spec-kit 的使用流程高度自动化和结构化，每步都围绕“规格”展开。你可以用它实现敏捷开发、团队协作、质量保障和快速创新。