Spec Kit使用经验总结

AIcoding>AI编程知识>规范驱动编程
6k words

Spec Kit使用经验总结

1. 什么是 Spec Kit？

Spec Kit 是 GitHub 官方推出的一套「规范驱动开发（Spec-Driven Development, SDD）」工具包。它的目标是：

让“规范”成为事实来源，让代码变成规范的“表达层”，而不是相反。(GitHub)

简单说两句，它解决的是现在很常见的一种尴尬：

  • 你和 AI 聊得很开心，vibe coding 式地一顿生成
  • 代码能跑，但：
    • 和真正需求有偏差
    • 质量、安全性难保证
    • 文档缺失、架构混乱、后续接手困难(腾讯云)

Spec Kit 给出的答案是：用一套结构化的规范—计划—任务—实现工作流，把 AI 从“灵感玩具”变成“工程化生产力工具”。(Lilys AI)

其核心价值可以总结为四个短语：(博客园)

  • 规范即代码：规范是第一公民，代码只是规范的某种实现
  • AI 驱动开发：人写规范和原则，AI 负责生成计划、任务和代码
  • 多技术栈支持：前后端、多语言、多框架都可以用
  • 企业级就绪：强调治理、约束、可追溯、可审计

2. 规范驱动开发（SDD）简介

2.1 核心理念

Spec-Driven Development 做了一件“角色互换”的事：

传统：代码是唯一真理，规范只是脚手架；
SDD：规范才是源头，代码是规范的实现结果。(GitHub)

关键思想：

  1. 规范是事实来源（Source of Truth）
    • 产品需求、架构决策、非功能性要求都写在规范里
    • 代码只是一种“投影”，随时可以从更新后的规范重新生成(GitHub)
  2. 规范是可执行的
    • 规范 + 实施计划是足够精确的描述
    • AI 根据它们可以稳定生成代码、测试和文档(GitHub)
  3. 工作流变成：规范 → 计划 → 任务 → 实现
    • 不是“聊几句就让 AI 写代码”
    • 而是多步约束、逐层收敛，减少幻觉和跑偏(GitHub)
  4. 团队协作围绕规范进行
    • 分支、评审、回滚都围绕 specs/ 里的规范文档
    • 代码只是规范的产物，可以按需重生成或重构(GitHub)

2.2 与传统开发对比

传统流程（简化版）：

需求 → 设计 → 手写代码 → 测试 → 上线

SDD 流程：

需求 → 详细规范 → AI 生成计划与代码 → 系统化验证

差异点：(腾讯云)

  • 先规范、后代码，代码永远不能和规范脱节
  • AI 成为“执行层”，人更多关注需求、架构和校验
  • 变更先改规范，再由 AI 帮你更新实现，而不是在代码里“打补丁”

3. Spec Kit 由哪些部分组成？

Spec Kit 主要包含两大核心组件：(Microsoft Developer)

  1. Specify CLI（命令行工具）
    • 帮你在本地项目里一键拉起 SDD 脚手架
    • 下载模板、创建目录、生成脚本、配置 Agent 等
  2. 模板 + 脚本 + Agent 集成
    • 模板：规范模板、计划模板、任务模板等
    • 脚本：用于自动创建分支、检查前置条件、更新 Agent 上下文
    • Agent 集成与 Slash 命令：给 Claude Code、Copilot、Gemini 等 AI 编码工具注入 /speckit.* 命令，让它按 SDD 流程工作

初始化后，典型目录大致是这样：(Microsoft Developer)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
.github/
  prompts/                # 给 Agent 用的一组提示词模板
    plan.prompt.md
    specify.prompt.md
    tasks.prompt.md

.specify/
  memory/
    constitution.md       # 项目“宪法”，统一原则和约束
    constitution_update_checklist.md
  scripts/                # shell / PowerShell 脚本
  templates/              # 规范、计划、任务模板
    spec-template.md
    plan-template.md
    tasks-template.md

specs/
  001-some-feature/
    spec.md
    plan.md
    tasks.md
    ...

4. 安装与初始化

4.1 前置条件（典型）

  • 已安装 Python + uv 工具链
  • Git 仓库（如果不是，Specify 也可以帮你初始化）(Microsoft Developer)
  • 你常用的 AI 编码助手（Claude Code / Copilot / Gemini CLI / Cursor 等）

4.2 安装 Specify CLI

方式一：持久安装（推荐）(GitHub)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 安装
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 创建新项目
specify init <PROJECT_NAME>

# 在已有项目中初始化
specify init .
specify init --here

# 检查安装情况
specify check

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

方式二：一次性使用

1
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

4.3 初始化项目

典型命令：(GitHub)

1
2
3
4
5
6
7
8
9
10
# 交互式选择 AI Agent
specify init my-app

# 指定 Agent
specify init my-app --ai claude
specify init . --ai copilot

# 已有文件时强制初始化当前目录
specify init . --force
specify init --here --force

执行后，Spec Kit 会自动完成：

  • 检查环境与版本
  • 下载最新模板与脚本
  • 生成 .specify/、.github/ 等目录
  • 为你的 Agent 注入 /speckit.* 命令

5. Spec Kit 的开发流程（详细）

整体工作流可以概括为四个阶段：规范（Specify）→ 计划（Plan）→ 任务（Tasks）→ 实现（Implement）。(GitHub)

5.1 Step 0：定义项目宪法 /speckit.constitution

目的：定义这个项目不可动摇的原则，例如：

  • 测试要求（必须有端到端测试、覆盖率门槛等）
  • 性能与安全约束
  • 架构原则（例如 API 设计风格、日志规范）
  • 团队约定（如“所有应用默认 CLI-first”）(Microsoft Developer)

示例命令（在 Agent 里）：

1
2
/speckit.constitution
Create principles focused on code quality, testing standards, user experience consistency, and performance requirements.

结果：

  • 创建或更新 .specify/memory/constitution.md
  • 后续 /speckit.specify、/speckit.plan、/speckit.tasks 都会自动参照这些原则(GitHub)

5.2 Step 1：生成功能规范 /speckit.specify

作用：把一句话需求，变成结构化的功能规范（spec.md）。(GitHub)

例如在 Agent 中输入：

1
2
/speckit.specify
Build an application that can help me organize my photos in separate photo albums...

Spec Kit 会自动做的事情包括：(GitHub)

  1. 扫描现有规范，自动分配特性编号（比如 001）
  2. 自动创建分支 001-photo-albums（名称可读）
  3. 基于模板生成 specs/001-photo-albums/spec.md
  4. 用统一结构填充：
    • 用户故事 & 场景
    • 功能需求 & 非功能需求
    • 验收标准 & 边界情况
    • [NEEDS CLARIFICATION: ...] 的疑问位

模板明确要求：只写 WHAT / WHY，不写 HOW（技术栈、实现细节），防止过早陷入实现。(GitHub)

可选的下一步：

  • /speckit.clarify：驱动 AI 自动对规范中的模糊点提问，帮助你补全不清晰的地方，并把回答记录在规范中专门的 Clarifications 区域。(GitHub)

5.3 Step 2：生成技术方案 /speckit.plan

当规范比较稳定后，使用：

1
2
/speckit.plan
The application uses Vite with minimal libraries...

该命令会：(GitHub)

  1. 分析 spec.md 中的用户故事、验收标准
  2. 校验是否符合 constitution.md 中的原则（如架构、安全标准）
  3. 生成技术实施计划，包括：
    • plan.md —— 高层架构、技术选型、组件拆分
    • data-model.md —— 实体和数据模型
    • contracts/ —— API / 事件 / 协议规范（如 OpenAPI / WebSocket 事件等）
    • research.md —— 对比不同框架/库的调研结论
    • quickstart.md —— 项目启动指南与验证场景(GitHub)

模板中会强制通过一些“门”：(GitHub)

  • Simplicity Gate：控制项目和模块数量，防止过度设计
  • Anti-Abstraction Gate：禁止无意义抽象与“未来可能用到”的臃肿设计
  • Test-First 指引：优先产出契约、测试，再写实现代码

任何违反简洁与可维护性的地方都要在文档中说明理由（有点像“架构决策 ADR”）。

5.4 Step 3：生成任务列表 /speckit.tasks

在有了 plan 之后，使用：

1
/speckit.tasks

它会：(GitHub)

  1. 读取 plan.md、data-model.md、contracts/、research.md
  2. 把数据模型、接口、场景，拆成一条条可执行任务
  3. 自动标记哪些任务可并行执行（加 [P] 标签）
  4. 输出 specs/<feature>/tasks.md，供 Task agent 或人工执行

任务列表通常会按阶段组织，例如：

  • 环境与基础设施
  • 核心业务流程
  • 边界与错误处理
  • 测试与验收
  • 文档与运维

5.5 Step 4：执行实现 /speckit.implement

最后，使用：

1
/speckit.implement

让 Agent 根据 tasks.md 按步骤实现：(GitHub)

  • 逐步创建代码文件
  • 按文件/模块粒度提交
  • 与规范和计划保持对齐
  • 出问题时，你只需要回到规范/计划/任务层做调整，再重新生成相关部分

6. 模板如何“管住” AI ？

Spec Kit 的一个精髓是：它没有靠“更聪明的模型”，而是靠更强的结构化模板和校验来约束 LLM 行为。(GitHub)

模板里做了几件关键的事情：

  1. 强制分离 WHAT / WHY 与 HOW
    • 功能规范模板写死：
      • ✅ 描述需求、场景、用户价值
      • ❌ 禁止写具体技术栈和 API 设计
    • 只有在计划阶段才讨论技术细节
  2. 显式不确定性标记 [NEEDS CLARIFICATION]
    • 模板要求：对任何不确定项不要乱猜，用 [NEEDS CLARIFICATION: 具体问题] 标出
    • 避免 LLM 自作聪明，写出“看着合理但错得离谱”的内容
  3. 自检清单（Checklist）
    • 类似单元测试，但测试的是“规范质量”
    • 例如：
      • 是否还有未解决的 [NEEDS CLARIFICATION]
      • 需求是否可测量、可验证
      • 成功标准是否量化
  4. “宪法门”（Constitution Gates）
    • 在计划模板中，对照 constitution.md 做结构化检查
    • 比如有“简单性门”、“反过度抽象门”等，要求对任何复杂性做显式记录和说明
  5. Test-First 与文件生成顺序
    • Template 要求先生成契约与测试，再写实现
    • 鼓励“契约优先”的思路（类似 API-First + TDD）(GitHub)
  6. 禁止“功能脑补”
    • 模板里有“禁止 speculative features”的检查项
    • 任何不在需求中的功能都不会自动往里加，防止项目膨胀

效果：

  • 人和 AI 都被“框”在合理的工程流程里
  • 每一步输出都有结构化检查，防止遗漏与跑偏
  • 文档天然是“活文档”，和实现高度同步(GitHub)

7. 适用场景与收益

比较典型的适用场景：(GitHub)

  • 从 0 到 1 搭建新应用（Greenfield）
    • 先从高层需求开始
    • 生成完整规范 → 计划 → 实现
  • 探索多种实现方案
    • 同一份规范，用不同技术栈/架构生成多个版本
    • 对比性能、可维护性、成本等
  • 改造/扩展旧系统（Brownfield）
    • 用规范描述现有系统 + 新需求
    • 帮助 AI 做有约束的重构或功能扩展
  • 有较高治理要求的团队/组织
    • 需要审计、可追溯、符合合规要求
    • 多团队协作、多人维护的复杂项目

带来的收益可以简单列一下：

  • AI 生成代码的可控性和可预测性大幅提高
  • 团队有一套统一的、可以审查和演化的开发规范
  • 重构或换栈时，只需更新规范/计划，再生成实现
  • 新同事上手快，看 specs/ 就能理解系统

8. 与其他实践的关系

  • 与敏捷/迭代开发
    • 完全兼容，规范、计划和任务本身就适合小步快跑
    • 每个 Sprint 可以对应若干个 feature spec 分支(腾讯云)
  • 与 TDD / BDD
    • SDD 范围更大：从需求、架构到测试、实现全部覆盖
    • TDD 可以被看作“测试层面的规范驱动”，而 SDD 是“全栈规范驱动”
  • 与传统文档驱动开发
    • 核心差异在于：
      • 传统文档写完就“吃灰”，与代码慢慢脱节
      • SDD 的规范是可执行的，直接驱动代码生成 & 校验

9. 使用 Spec Kit 的实战建议

结合上面几篇文章和官方文档，落地时可以注意这些点：(Microsoft Developer)

  1. 第一步一定是 constitution.md
    • 把团队的一致性要求写清楚
    • 尤其是测试、日志、安全、错误处理这些“非功能性需求”
  2. 写规范时，不要纠结技术栈
    • /speckit.specify 阶段只谈业务，避免提前锁死架构
    • 技术偏好放到 /speckit.plan 中，由 AI 帮你权衡
  3. 认真处理 [NEEDS CLARIFICATION]
    • 把它当成“必修清单”，不用急着写代码
    • 真正的坑，往往藏在这些模糊点里
  4. 把 specs/ 当成评审入口
    • Code Review 前先做 Spec Review
    • 对于变更和回滚，参考的是规范版本，而不是散落在 PR 描述里的口头说明
  5. 从一个小项目练手
    • 比如简单的 Todo / Chat / 报表工具
    • 先熟悉整套流程，再上大项目
  6. 团队达成共识：不再“直接让 AI 写一堆代码”
    • 所有非 trivial 功能都走“规范→计划→任务→实现”路径
    • 把 vibe coding 留给快速原型或个人小脚本

10. 小结

如果用一句话概括：

Spec Kit = 把“规范驱动开发（SDD）”落地到日常 AI 编程的工程化工具包。

它帮你：

  • 在项目里一键搭起 SDD 脚手架（Specify CLI）
  • 用结构化模板把“想法”变成可执行的规范与计划
  • 通过 /speckit.* 命令驱动 AI 按步骤完成规范 → 计划 → 任务 → 实现
  • 让规范成为可以评审、可以演化、可以重放的“活文件”