GitHub Spec Kit:让规格文档成为软件的第一公民

项目简介

Spec Kit 是由 GitHub 官方开源的一套 规格驱动开发（Spec-Driven Development，SDD）工具集，其核心理念是：

让规格文档成为软件的第一公民，代码是规格的”输出”而非目的本身。

它通过一个名为 specify 的 CLI 工具 + 一套 AI 编程助手的 Slash 命令，帮助开发者在与 AI 协作编程时，将需求 → 规格 → 计划 → 任务 → 实现的全流程结构化、可追溯、可重复。

解决什么问题？

传统 AI 辅助编程（俗称”Vibe Coding”）存在严重缺陷：

Spec Kit 的解法：在 AI 编程之前，用结构化的流程强制生成 spec（规格）、plan（实现计划）、tasks（任务清单），让 AI 在”轨道上”执行，而不是随意发挥。

核心理念：规格驱动开发（SDD）

SDD 的核心权力倒置：

传统开发：  需求文档 → [写代码] → 代码是真正的"产品"SDD：       规格文档 → [AI 生成代码] → 规格才是真正的"产品"

• • 规格（Spec） = 意图的表达，描述”做什么”和”为什么”
• • 计划（Plan） = 技术实现策略，描述”怎么做”
• • 任务（Tasks） = 原子化的可执行步骤
• • 代码 = 以上三者的”编译输出”，可以重新生成

当需求变更时，只需更新规格，重新生成计划和任务，AI 再次实现。这使得需求变更从”噩梦”变成”常规操作”。

诚实一刻：SDD 把”代码维护成本”转换成了”规格维护成本”——spec / plan / tasks 三层文档本身也是需要持续维护的资产。变更一个需求意味着至少改 3 个文件，再跑 2 道重新生成。对于需求稳定的小项目，这套流程的维护 overhead 可能比直接改代码还高。这不是否定 SDD，而是提醒：它解决的问题（需求频繁变更的大项目）和它引入的成本（多层文档维护）需要放在一起衡量。

工作流程总览

specify init → /speckit.constitution → /speckit.specify → /speckit.clarify                                                                    ↓                                            /speckit.plan → /speckit.analyze                                                                    ↓                                                        /speckit.tasks                                                                    ↓                                                        /speckit.implement

安装与环境要求

前置条件

• • 操作系统：Linux / macOS / Windows
• • Python 3.11+
• • Git
• • 包管理工具：推荐 uv^[1] 或 pipx^[2]
• • AI 编程助手：支持 30+ 种，包括 Claude Code、GitHub Copilot、Gemini CLI、Cursor、Codex CLI 等

安装 Specify CLI

方法一：持久安装（推荐）

# 安装指定稳定版本（推荐，将 vX.Y.Z 替换为最新 tag）uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z# 或安装最新 main 分支（可能包含未发布的变更）uv tool install specify-cli --from git+https://github.com/github/spec-kit.git# 使用 pipx 也可以pipx install git+https://github.com/github/spec-kit.git@vX.Y.Z

验证安装：

specify version

方法二：一次性运行（无需安装）

uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <PROJECT_NAME>

方法三：企业/离线环境

参见官方企业安装指南^[3]。

升级

uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z

如何使用：完整七步工作流

第 0 步：初始化项目

# 新建项目specify init <PROJECT_NAME># 或在现有项目目录初始化specify init . --integration copilot# 也可以用 --here flagspecify init --here --integration copilot# 强制在非空目录初始化specify init . --force --integration copilot

初始化后，你的 AI 编程助手将获得以下 Slash 命令：

第 1 步：建立项目治理原则（Constitution）

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

这会创建 .specify/memory/constitution.md，作为整个项目 AI 行为的”宪法”，后续所有步骤都会遵守这份原则。

宪法的九大条款（内置默认值）：

• • Article I：库优先原则（每个功能先作为独立库实现）
• • Article II：CLI 接口强制（所有库必须暴露 CLI 接口）
• • Article III：测试优先（不写测试不得实现）
• • Articles VII & VIII：简洁性 + 反过度抽象
• • Article IX：集成优先测试（用真实环境测试，不用 Mock）

第 2 步：创建规格文档（Spec）

重点：描述”做什么”和”为什么”，不要涉及技术栈。

/speckit.specify Build an application that can help me organize my photos in separatephoto albums. Albums are grouped by date and can be re-organized by dragging anddropping on the main page. Allow users to add descriptions and tags to albums.

执行后自动完成：

• • 创建语义化分支（如 001-photo-album-app）
• • 生成 .specify/specs/001-photo-album-app/spec.md
• • 包含用户故事、功能需求、验收标准

第 3 步：澄清规格（Clarify）

/speckit.clarify

AI 会提出针对性问题（结构化问卷），帮你找出规格中的模糊点，并将答案记录到规格文档的 Clarifications 节。

这一步应在生成计划之前完成，避免后期返工。

第 4 步：生成技术实现计划（Plan）

此时才引入技术栈。

/speckit.plan The application uses Vite with minimal number of libraries.Use vanilla HTML, CSS, and JavaScript as much as possible.Images are not uploaded anywhere and metadata is stored in a local JSON file.

执行后生成：

.specify/specs/001-photo-album-app/├── spec.md          # 功能规格├── plan.md          # 实现计划├── research.md      # 技术调研├── data-model.md    # 数据模型├── quickstart.md    # 验证场景└── contracts/       # API 契约    └── api-spec.json

第 5 步：生成任务清单（Tasks）

/speckit.tasks

自动生成 tasks.md，包含：

• • 按用户故事组织的任务列表
• • 依赖关系管理
• • 并行任务标记（[P]）
• • 每个任务对应的文件路径
• • TDD 结构（先写测试，再写实现）

第 6 步：执行实现（Implement）

/speckit.implement

AI 将：

1. 1. 验证所有前置条件（constitution / spec / plan / tasks 均存在）
2. 2. 按依赖顺序执行任务
3. 3. 遵守 TDD 原则
4. 4. 提供进度反馈

使用场景

最佳适用场景

酌情使用的场景

不建议使用的场景

完整示例：构建 Taskify 看板应用

场景描述

构建一个多用户 Kanban 看板系统，支持拖拽任务卡片、评论等功能。

执行过程

# 1. 初始化specify init taskify --integration copilot# 进入 Claude Code 或 Copilot，执行以下命令：

# 2. 建立项目原则/speckit.constitution Create principles focused on code quality, testing standards,user experience consistency, and performance requirements.

# 3. 描述需求（只描述 WHAT，不涉及技术）/speckit.specify Develop Taskify, a team productivity platform. Allow users to createprojects, add team members, assign tasks, comment and move tasks between boards inKanban style. Five predefined users: one PM and four engineers. No login required.Kanban columns: To Do, In Progress, In Review, Done. Tasks can be dragged betweencolumns. Users can add unlimited comments, edit/delete own comments only.

# 4. 澄清模糊点/speckit.clarify

# 5. 生成技术计划（此时引入技术栈）/speckit.plan Use .NET Aspire with Postgres as database. Frontend: Blazor Serverwith drag-and-drop task boards, real-time updates. REST APIs: Projects API,Tasks API, Notifications API.

# 6. 拆解任务/speckit.tasks

# 7. 执行实现/speckit.implement

产出的目录结构

taskify/├── CLAUDE.md└── .specify/    ├── memory/    │   └── constitution.md    ├── specs/    │   └── 001-create-taskify/    │       ├── spec.md    │       ├── plan.md    │       ├── research.md    │       ├── data-model.md    │       ├── quickstart.md    │       ├── tasks.md    │       └── contracts/    │           ├── api-spec.json    │           └── signalr-spec.md    ├── scripts/    └── templates/

局限性与权衡

再好的工具也有盲区。以下是在实际使用中需要正视的问题：

1. 文档维护税

SDD 把单一代码资产变成了 spec + plan + tasks + code 四份资产。需求变更时：

• • 传统开发：改需求 → 改代码（1 步）
• • SDD：改 spec → 重跑 plan → 重跑 tasks → 改代码（3-4 步）

对于需求频繁变更的大型项目，这笔税是划算的（变更可追溯、可验证）。但对于需求稳定或体量小的项目，文档维护本身就是不必要的开销。

2. “反过度工程”的自我矛盾

Constitution 强调简洁性和反过度抽象，但七步 SDD 流程本身对简单项目就是过度工程。Spec Kit 建议小任务用 TinySpec，本质上是承认了这个矛盾——但把问题外包给社区扩展，而非从设计层面解决。

3. 缺乏真实落地数据

截至 2026 年 4 月，Spec Kit 官方未提供任何关于团队采纳后的量化数据：

• • 缺陷率下降多少？
• • 交付速度变化趋势？
• • 规格与代码的实际漂移率？
• • 某步骤的平均耗时？

Star 数虽高（91k+），但 GitHub 官方出品的流量加成不可忽视。Star 数 ≠ 生产验证，选型时需要额外考察。

4. AI 对规格的理解偏差

规格文档本身也是自然语言，AI 对 spec 的理解可能和你的本意有偏差。SDD 增加了 /speckit.clarify 来缓解这个问题，但澄清过程本身也是 AI 驱动的，可能引入新的偏差——AI 问的问题不一定是你真正需要澄清的点。

5. 流程刚性 vs 开发灵活性

七步流程假设需求可以在编码前完全确定，但很多开发场景（算法实验、UX 探索、技术验证）需要边做边发现。在这些场景中强行套用 SDD，会变成在沙子上建城堡。

一句话总结：SDD 是重型武器，打坦克好用，打蚊子就浪费了。选不选它，取决于你的项目到底是坦克还是蚊子。

扩展系统：Extensions & Presets

Spec Kit 支持通过扩展和预设进行高度定制。

优先级覆盖顺序

Extensions（扩展）：添加新能力

# 搜索可用扩展specify extension search# 安装扩展specify extension add <extension-name># 直接通过 URL 安装specify extension add myext --from https://github.com/org/ext/archive/refs/tags/v1.0.0.zip# 列出已安装扩展specify extension list

精选社区扩展举例：

Presets（预设）：定制现有工作流

specify preset searchspecify preset add <preset-name>

预设用于调整模板格式，例如适配 Agile / Kanban / Waterfall 等不同方法论。

何时选择哪种

常见问题与解决方案

Q1：specify 命令找不到 / PATH 未配置

解决：

# 确认 uv tool 的 bin 目录在 PATH 中export PATH="$HOME/.local/bin:$PATH"# 或重新安装并确认uv tool install specify-cli --from git+https://github.com/github/spec-kit.gitspecify version

Q2：AI 助手中看不到 /speckit.* 命令

原因：specify init 未成功写入 AI 助手的配置目录。

解决：

# 检查是否生成了必要文件specify check# 重新初始化，明确指定 integrationspecify init . --integration copilot --force# 或specify init . --integration claude --force

Q3：AI 跳过了澄清直接开始实现

原因：没有明确运行 /speckit.clarify，或 AI 误判需求已足够清晰。

解决：在 /speckit.plan 之前，明确执行：

/speckit.clarify

如果要跳过澄清（如探索性原型），明确告知 AI：

/speckit.clarify skip - this is an exploratory prototype, proceed without clarification.

Q4：AI 实现时加入了没有要求的功能

原因：规格描述过于模糊，或 AI “好心”添加扩展。

解决：

1. 1. 在规格中明确标注边界：Out of Scope: ...
2. 2. 在 Constitution 中添加简洁性原则
3. 3. 在计划审查阶段（Step 5）明确提示 AI 检查过度工程：

Read the plan and identify any features or components that were NOT explicitlyrequested in the spec. List them and ask for my approval before including them.

Q5：规格与代码出现漂移（Spec Drift）

症状：实现完成后，规格文档与实际代码行为不一致。

解决：安装 spec-kit-sync 扩展：

specify extension add spec-kit-sync

然后执行同步检测：

/speckit.sync

Q6：Linux 上 Git 认证问题

wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.debsudo dpkg -i gcm-linux_amd64.2.6.1.debgit config --global credential.helper managerrm gcm-linux_amd64.2.6.1.deb

Q7：企业/离线环境无法访问 PyPI 或 GitHub

场景：公司网络限制无法直接访问 PyPI、GitHub，或安全策略要求所有依赖来自内部镜像。

解决：官方支持三种离线部署模式，详见企业离线安装指南^[3]：

# 方案 3 示例：指向企业内部 Catalogexport SPECKIT_CATALOG_URL="https://artifacts.your-company.com/spec-kit/catalog.json"

选型建议：小团队（< 10 人）优先方案 1；有 DevOps 基础设施的中大型团队优先方案 2；需要审计和控制社区扩展的大企业选方案 3。

与传统 AI 编程对比

延伸资源

• • 完整 SDD 方法论文档^[4]
• • 官方文档站^[5]
• • CLI 命令参考^[3]
• • 社区扩展浏览器^[6]
• • 社区 Presets^[7]
• • 视频演示^[8]
• • 提交 Issue / 获取支持^[9]

文档基于 github/spec-kit^[10]（91k Stars，GitHub 官方出品）整理，结合实际使用场景补充扩展。MIT License 开源，可自由使用。

引用链接

[1] uv: https://docs.astral.sh/uv/[2] pipx: https://pypa.github.io/pipx/[3] 企业安装指南: https://github.github.io/spec-kit/reference/overview.html[4] 完整 SDD 方法论文档: https://github.com/github/spec-kit/blob/main/spec-driven.md[5] 官方文档站: https://github.github.io/spec-kit/[6] 社区扩展浏览器: https://speckit-community.github.io/extensions/[7] 社区 Presets: https://github.github.io/spec-kit/community/[8] 视频演示: https://www.youtube.com/watch?v=a9eR1xsfvHg[9] 提交 Issue / 获取支持: https://github.com/github/spec-kit/issues/new[10] github/spec-kit: https://github.com/github/spec-kit