当规格成为软件的源头：GitHub Spec Kit 技术深度解析

当规格成为软件的源头：GitHub Spec Kit 技术深度解析

在 AI 编码时代，最值钱的不是代码，而是精确描述"你到底想要什么"的能力。

翻开任何一本软件工程的教材，你都会看到类似的流程图：需求分析 → 系统设计 → 编码实现 → 测试部署。这套方法论已经统治了软件行业几十年。但现实中发生了什么？需求文档写完就锁进抽屉，设计图在第一次 code review 后就再也没人看，测试用例是上线前一天通宵补的。

代码成了唯一的真相，而规格沦为了点缀。

GitHub 的 Spec Kit 想要翻转这件事。

范式转移：从"代码为王"到"规格为王"

传统开发的根本矛盾

软件工程一直有一个无法消除的缝隙：规格和实现之间的鸿沟。

我们试过很多方法来缩小这个缝隙——更详细的 PRD、更严格的代码审查、更完善的敏捷流程。但这些都默认了一个前提：缝隙是不可避免的，我们只能尽量窄一点。

Spec-Driven Development（SDD，规格驱动开发）彻底否定了这个前提。它的核心主张是：消除缝隙，而不是缩小缝隙。

怎么做？让规格本身变成可执行的——规格不再是"给人看的参考文档"，而是"能直接生成代码的源头"。

这背后的逻辑是：当代码必须从规格中"长出来"时，两者之间就不再有鸿沟，只有转换关系。

为什么是现在？

三个趋势在 2025 年同时成熟，让 SDD 从理论变成了实践：

AI 代码生成能力的临界点。 大语言模型已经能可靠地理解自然语言规格，并将其转化为可工作的代码。这不是取代开发者，而是放大他们的效能——把"规格→代码"这段机械翻译自动化。

软件复杂度的指数级增长。 一个现代应用动辄集成几十个微服务、框架和第三方依赖。靠人力保持所有组件与原始意图的一致性，已经变得几乎不可能。SDD 通过规格驱动来提供系统性的对齐保障。

需求变化的速度空前加快。 Pivot 不再是例外，而是常态。传统开发把需求变更视为"干扰"，每次变更都要手动在文档、设计、代码之间传播。而 SDD 中，改规格、重新生成，就是标准流程的一部分。

Spec Kit 技术架构

Spec Kit 是 GitHub 官方开源的 SDD 工具包，它不是一个单一的代码生成器，而是一套完整的方法论基础设施。

核心组件

整个工具包由六个层次组成：

Specify CLI 是整个系统的入口。它是一个 Python CLI 工具（通过 uv 安装），负责项目初始化、集成管理、工作流编排等所有元操作。你不会直接用它写代码，但所有 SDD 流程都通过它来调度。

Templates 系统 是规格的骨架。每个命令（specify、plan、tasks 等）都对应一套结构化模板，确保输出不会遗漏关键信息——从非功能性需求到错误处理，从数据模型到 API 契约。

Integrations 层 连接 AI 编码代理。目前支持 30+ 工具——从 GitHub Copilot、Claude Code、Cursor 到 Codex CLI、Gemini CLI、Qwen Code，甚至包括国产的 Trae、Lingma、Kimi Code。每个集成都会设置好对应的命令文件、上下文规则和目录结构。

Extensions（扩展） 让你添加新能力——领域特定命令、外部工具集成、质量门禁。多个扩展可以独立安装和卸载。

Presets（预设） 定制 SDD 的工作方式——覆盖命令模板、术语对齐、组织标准适配，而不改变底层工具。

Workflows（工作流） 把多步骤的 SDD 流程编排成可重复的序列，支持条件分支、循环、fan-out/fan-in，甚至可以暂停和恢复。

优先级体系

这四层定制机制按优先级从高到低排列：

优先级 类型 位置
1 项目本地覆盖 .specify/templates/overrides/
2 Presets .specify/presets/templates/
3 Extensions .specify/extensions/templates/
4 Spec Kit 核心 .specify/templates/

这意味着你可以从"使用默认模板"开始，逐步通过预设和扩展来定制，最终实现完全的组织级标准化——而不用 fork 整个项目。

SDD 工作流：从想法到代码

六步核心流程

SDD 的核心流程可以用一条流水线来概括：

Constitution（建立宪法）→ Specify（写规格）→ Plan（做计划）→ Tasks（拆任务）→ Implement（写代码）→ Converge（对账）

每一步都有对应的 slash command，让我们用一个真实例子来走一遍。

Step 1: 建立项目宪法

/speckit.constitution 创建原则：代码质量标准、测试覆盖率 >80%、移动端优先的响应式设计、所有 API 必须有 OpenAPI 文档

这一步定义了项目的"基本法"——后续所有生成代码都受它约束。宪法不是写给人看的建议，而是写入 AI 上下文的硬性规则。当后续 plan 和 implement 阶段做出技术决策时，这些原则会被自动引用。

这相当于在提示词工程中设定 system prompt——先画好边界，再让 AI 在边界内发挥。

Step 2: 写规格（最关键的一步）

/speckit.specify 构建一个照片管理应用，可以按日期分组相册，支持拖拽重新排列，相册不嵌套，照片以网格预览

注意这里只描述 What（做什么）和 Why（为什么），完全不涉及技术栈。这一步会自动完成：

  • 扫描现有 specs 目录，确定下一个 feature 编号（001、002…）
  • 从描述中生成语义化的分支名并创建 Git 分支
  • 基于模板生成结构化的 feature 规格文档，放在 specs/[branch-name]/spec.md
  • 自动填充用户故事、验收标准、非功能性需求

AI 在这一步会追问你：相册容量有没有上限？拖拽时要不要显示放置预览？照片要不要支持排序？这些问题在传统开发中往往要到 code review 阶段才被发现。

Step 3: 制定技术计划

/speckit.plan 使用 Vite 构建，尽量用原生 HTML/CSS/JS，图片不上传，元数据存本地 SQLite

这一步把产品规格翻译成技术方案。AI 会：

  • 读取并分析 spec.md 中的需求和验收标准
  • 对照项目宪法，确保技术选型符合约束
  • 生成数据模型（data-model.md）
  • 生成 API 契约（contracts/ 目录）
  • 生成研究文档（research.md），包含库的对比、性能基准等

每一个技术决策都有记录的 rationale，追溯到具体的需求条目。这意味着当未来有人问"为什么选 SQLite 而不是 PostgreSQL"，答案就在文档里，而不是丢失在 Slack 历史消息中。

Step 4: 拆解任务

/speckit.tasks

从 plan.md 出发，自动生成可执行的任务列表。关键特性：

  • 并行标记：独立任务会被标记 [P]，标识可以安全并行的任务组
  • 依赖排序：有依赖关系的任务按正确顺序排列
  • 验收条件：每个任务都有明确的"完成标准"

输出是 specs/[branch-name]/tasks.md，一份结构化的执行清单。

Step 5: 执行实现

/speckit.implement

AI 按任务列表逐个实现。这个阶段的概念映射非常优雅：

  • 领域概念 → 数据模型
  • 用户故事 → API 端点
  • 验收场景 → 测试用例

测试不再是事后补的，而是从规格中"自然生长"出来的。因为验收条件在 spec 阶段就定义好了，implement 只是把它翻译成可执行的测试代码。

Step 6: 收敛对账

/speckit.converge

这是一个经常被忽视但极其重要的步骤：对比现有代码和 spec/plan/tasks，找出遗漏的工作项并追加为新任务。它回答的问题是："我们生成的代码，真的实现了规格中定义的所有东西吗？"

进阶能力

Clarify：在计划之前消除模糊

/speckit.clarify

运行在 specify 之后、plan 之前。AI 会系统性地分析规格中的模糊点、矛盾点和遗漏点，然后向你提问。这就像有一个经验丰富的架构师帮你做 design review，但在你写一行代码之前。

Analyze：交叉一致性验证

/speckit.analyze

运行在 tasks 之后、implement 之前。它检查 spec、plan、tasks 三个文档之间的一致性：

  • spec 中的每个需求，在 plan 中都有对应的技术方案吗？
  • plan 中的每个设计决策，在 tasks 中都有对应的任务吗？
  • 有没有孤立的任务（不追溯到任何需求）？

这相当于"英文写的单元测试"——在写代码之前先验证文档的质量。

Checklist：质量门禁

/speckit.checklist

生成定制化的质量检查清单，验证需求的完整性、清晰度和一致性。可以被纳入 CI 流程，成为自动化的质量门禁。

Workflow 引擎：可编排的 SDD 流水线

Spec Kit 不只是提供孤立的命令，它还有一个完整的 Workflow 引擎，把多步骤流程编排成可重复、可暂停、可恢复的流水线。

内置的 Full SDD Cycle

Spec Kit 自带一个完整 SDD 循环工作流，把 specify → plan → tasks → implement 串联起来，中间插入人工审核门禁：

schema_version: "1.0"
workflow:
  id: "speckit"
  name: "Full SDD Cycle"
  description: "Runs specify → plan → tasks → implement with review gates"

steps:
  - id: specify
    command: speckit.specify
    input:
      args: "{{ inputs.spec }}"

  - id: review-spec
    type: gate
    message: "Review the generated spec before planning."
    options: [approve, reject]
    on_reject: abort

  - id: plan
    command: speckit.plan

  - id: review-plan
    type: gate
    message: "Review the plan before generating tasks."
    options: [approve, reject]
    on_reject: abort

  - id: tasks
    command: speckit.tasks

  - id: implement
    command: speckit.implement

一行命令启动：

specify workflow run speckit -i spec="构建一个看板系统，支持拖拽任务管理"

支持的步骤类型

Workflow 引擎支持 10 种步骤类型：

类型 用途
command 调用 Spec Kit 命令
prompt 向 AI 发送任意提示
shell 执行 shell 命令
init 引导新项目
gate 人工审核门禁
if 条件分支
switch 多路分发
while 条件循环
do-while 至少执行一次的循环
fan-out / fan-in 并行分发与结果聚合

状态持久化

每个 workflow run 都会持久化状态到 .specify/workflows/runs/<run_id>/：

  • state.json — 当前运行状态和步骤进度
  • inputs.json — 已解析的输入值
  • log.jsonl — 逐步骤执行日志

这意味着当你在一个 gate 步骤暂停后，可以用 specify workflow resume <run_id> 从断点恢复。这在需要人工审核的场景中特别有用——你可以花一天时间审核 spec，然后一键继续。

实战效率对比

传统方式和 Spec Kit 方式的效率差异是显著的。以构建一个实时聊天功能为例：

传统方式：

步骤 耗时
写 PRD 文档 2-3 小时
创建设计文档 2-3 小时
手动搭建项目结构 30 分钟
写技术规格 3-4 小时
创建测试计划 2 小时
合计 约 12 小时

使用 Spec Kit：

步骤 耗时
/speckit.specify 写规格 5 分钟
/speckit.plan 做计划 5 分钟
/speckit.tasks 拆任务 5 分钟
合计 约 15 分钟

15 分钟内你得到了：完整的 feature 规格（含用户故事和验收标准）、详细的技术实现计划（含技术选型理由）、API 契约和数据模型、测试场景、所有文档都在 feature 分支中正确版本化。

当然，这不意味着 15 分钟就能上线一个聊天系统。后续的 implement、测试、调试仍然需要时间。但前置的文档和规划工作从 12 小时压缩到 15 分钟，这个量级的提升是实实在在的。

谁适合用 Spec Kit？

高度适配的场景

AI-Native 团队。 如果你已经在用 Copilot、Claude Code 或 Cursor 写代码，Spec Kit 是天然的升级——从"AI 帮你写函数"进化到"AI 帮你写整个 feature"。

提示词工程师。 SDD 的核心理念——"精确描述你要什么"——和提示词工程完全同构。规格本质上就是给 AI 的结构化提示词。

教学场景。 SDD 强制学生先想清楚"要什么"再动手，这培养了系统思维。学生不能跳过需求分析直接写代码，因为 Spec Kit 的流程不允许。

快速原型和 MVP。 "如果我改这个需求，重新实现要多久？"——在 SDD 中，答案是"改 spec，重新生成"。这使得探索多个技术方案的成本极低。

需要谨慎的场景

遗留系统改造。 Spec Kit 的价值在新项目中最大化。对于已有大量代码的遗留系统，你需要先为现有功能"补写"规格，才能享受 SDD 的好处——这个补写过程本身就很昂贵。

高度定制化的底层系统。 如果你写的是操作系统内核、编译器或数据库引擎，规格→代码的转换可能不如业务应用那么直接。

SDD 的深层启示

规格即提示词

站在提示词工程的视角看 SDD，会有一个有趣的发现：规格文档本质上就是给 AI 的结构化提示词。

  • Constitution = System Prompt（设定边界和规则）
  • Spec = User Prompt（描述具体任务）
  • Plan = Chain-of-Thought（让 AI 展示推理过程）
  • Tasks = Step-by-Step Decomposition（任务分解）
  • Converge = Self-Check（自我验证）

这意味着 SDD 最佳实践和提示词工程最佳实践高度重合。一个优秀的提示词工程师，天然就是优秀的规格编写者。

代码的终局

SDD 提出了一个深刻的问题：当代码可以从规格中自动生成时，代码还是资产吗？

在 SDD 的世界观中，代码更像是"编译产物"——可以随时从源头重新生成。真正的资产是规格、是团队对需求的理解、是架构决策的记录。

这意味着未来的开发者可能不再"写代码"，而是"写规格"。代码变成了一种中间表示，就像我们不再手写汇编一样。

从 0 到 1，从 1 到 N

SDD 的流程本质上是：

0 (idea) → 1 (spec) → implementation → 1' (new spec) → new implementation → 2 → 3 → N

第一次实现是 0→1，后续的每次修改都是改规格、重新生成。同一个规格可以生成不同的实现（用不同的技术栈、优化不同的维度），就像同一个设计图纸可以盖出不同材料的房子。

这让"重新开始"不再昂贵——你不需要从代码中剥离旧逻辑，只需要修改规格的对应部分，然后重新生成。

快速上手

# 1. 安装 uv（如果没有的话）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 安装 Specify CLI（替换为最新版本号）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.8.5

# 3. 初始化项目
specify init my-project --integration copilot
cd my-project

# 4. 启动你的 AI 编码代理，然后依次运行：
# /speckit.constitution   ← 定义项目原则
# /speckit.specify        ← 写规格
# /speckit.clarify        ← 消除模糊点
# /speckit.plan           ← 做技术计划
# /speckit.analyze        ← 一致性检查
# /speckit.tasks          ← 拆任务
# /speckit.implement      ← 写代码
# /speckit.converge       ← 对账

或者用 Workflow 一步到位：

specify workflow run speckit -i spec="你的需求描述"

结语

Spec Kit 不是一个代码生成工具。它是一种开发哲学的载体——规格才是软件的真正源头，代码只是它的投影。

这个哲学并不新（形式化方法领域已经探索了几十年），但 AI 代码生成能力的成熟让它第一次变得可操作。当 GitHub 这样的平台级玩家开始投入，意味着这不只是实验性的尝试，而是软件工程范式转移的信号。

对于每一个在 AI 时代写代码的人来说，值得思考的问题是：你花在描述"要什么"上的时间，是否配得上它的重要性？

Spec Kit 给出的答案是：把最好的精力放在规格上，剩下的交给机器。

GitHub 仓库：github/spec-kit
官方文档：github.github.io/spec-kit

Views: 2