spec-kit

从「 vibe coding 」到「规格先行」：GitHub Spec Kit 重新定义 AI 编程工作流

你是否有这样的经历：对 AI 编程助手说一句话，它噼里啪啦写了几百行代码，看起来像模像样，一运行——满屏红字报错。更要命的是，你甚至说不清到底是需求没说清楚，还是 AI 理解偏了。

这正是 GitHub Spec Kit 试图解决的核心问题。

图1：GitHub Spec Kit 官方 Logo

Spec Kit（全称 GitHub Spec Kit）是 GitHub 于 2025 年开源的一套规格驱动开发（Spec-Driven Development，SDD）工具包，旨在为 AI Coding Agent 提供一套结构化的、以规格说明书为核心的开发流程。它既不是又一个 AI 代码生成器，也不是简单的 Prompt 模板集合——而是一套完整的方法论 + 工具链，让 AI 编程从「凭感觉猜」升级为「有据可依」。

该项目自 2025 年 8 月上线以来，迅速获得开发者社区关注，GitHub Stars 已突破 10.5 万，被 Visual Studio Magazine 评为「GitHub 开源的重要里程碑」，微软 DevBlogs 也多次深度报道。

背景：AI 编程的「快乐陷阱」

2023-2024 年，AI 编程助手（如 GitHub Copilot、Claude Code）席卷全球。开发者发现：只需要用自然语言描述需求，AI 就能生成代码——效率惊人。

但问题也随之浮现：

模糊意图是 AI 编程的最大敌人。 当你让 AI「写一个用户登录功能」，它默认了 Session 还是 JWT？Token 过期策略是什么？密码强度要求？这些细节 AI 不会主动问，它会「聪明地」选一个最常见的方案——而这个方案未必适合你的项目。开发者在 Review 时才发现不对，改来改去比从头写还累。

传统的解决方案是「先写需求文档」。但传统需求文档的问题在于：文档和代码是脱节的——文档写了代码没按走，或者代码改了文档忘了同步，最后文档变成摆设。

Spec Kit 的核心洞察是：规格说明书应该是「可执行的」，而不只是给人类看的参考文档。 在 SDD 流程中，规格说明书直接驱动 AI Agent 的行为——AI 根据规格生成实现，而不是根据模糊的指令猜测需求。

SDD 流程的核心五步：

1. Constitution（宪章）：团队定义开发原则，如「TDD 优先」「优先函数式」「先写测试再写代码」
2. Spec（规格）：用自然语言描述系统应该做什么，AI 帮你把它格式化为结构化的规格文档
3. Plan（计划）：基于规格，AI 生成技术实现方案——选什么框架、怎么分层、接口设计
4. Tasks（任务）：将计划拆解为小颗粒度、可独立测试的开发任务
5. Implement（实现）：AI Agent 逐个完成任务

这个流程既适合 AI，也适合人——规格文档成了开发团队和 AI 之间的「共同语言」。

架构解析：CLI + 模板引擎 + 集成层

Spec Kit 的技术架构分为三层：

第一层：Specify CLI（命令行工具）

核心是 specify 命令行工具，基于 Python 开发（要求 Python >= 3.11），通过 uv tool install 一键安装：

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@latest

CLI 负责初始化项目（specify init）、驱动工作流命令（/speckit.specify 等）、管理扩展和预设。依赖非常轻量：typer（CLI 框架）、rich（终端美化）、pyyaml、packaging 等——没有重型 ML 依赖。

第二层：模板与命令系统

模板引擎将项目资产（Prompt 模板、命令脚本、VSCode 配置）打包进 Python wheel，分发到 templates/、scripts/、workflows/ 等目录。核心模板包括：

• spec-template.md：规格文档模板
• plan-template.md：技术方案模板
• tasks-template.md：任务拆分模板
• checklist-template.md：质量检查清单

每个模板都经过精心设计，包含详细的引导性 Prompt，帮助 AI 生成高质量输出而非泛泛而谈。

第三层：AI 集成层（Integrations）

这是 Spec Kit 最有特色的设计——集成层让同一套 SDD 流程可以对接不同的 AI Coding Agent。

集成层采用适配器模式，每个 AI Agent 是一个独立的子包（src/specify_cli/integrations/<key>/），继承自基类 IntegrationBase。基类提供统一的初始化/清理逻辑，子类只需声明元数据（支持的命令格式、上下文文件名等）。

目前内置支持的 Agent 包括 Claude Code（SkillsIntegration）、GitHub Copilot（自定义）、Gemini CLI（TomlIntegration）、Cursor Agent、WindSurf、Goose、Qwen、Kiro CLI 等 10+ 主流 AI Coding Agent，覆盖 Markdown、Toml、YAML 三种命令格式。

图2：Spec Kit 在 Claude Code 中的初始化流程演示

扩展系统（Extensions）允许第三方开发者在不修改核心代码的情况下添加新功能，通过 specify extension add <name> 安装。官方还内置了 Git 扩展（自动生成规范的 Commit Message）。

核心功能：从「随便写」到「规范做」

规格生成（Spec Generation）

当你告诉 AI「我要做一个图片分享社交应用」，传统做法下 AI 会立刻开始写代码。但 SDD 流程下，AI 先跟你一起「打磨规格」：经过多轮澄清，最终规格文档会精确到每个功能的输入、输出、边界条件。这种「先说清楚再做」的模式大幅减少了后期返工。

Diff-Aware 升级

当你修改了规格文档后，运行 specify integration upgrade，AI 会对比新旧规格的差异，只重写受影响的代码部分，而不是整块重构。这个功能对大型项目尤其有价值。

项目 Constitution（宪章）

Constitution 是团队开发准则的集合，比如「所有函数必须有类型注解」「禁止使用裸 except」「优先组合而非继承」。这些准则被嵌入到 AI 的每一步操作中，确保 AI 的输出符合团队规范，而不只是「能跑就行」。

质量检查清单（Checklist）

在进入实现阶段前，/speckit.checklist 命令会触发 AI 进行自我审查：当前规格是否完整？技术方案是否与规格一致？任务拆分是否合理？这个检查点显著提高了交付质量。

多 Agent 支持

你可以在不同项目使用不同的 AI Agent——Spec Kit 保证工作流一致性。迁移项目时，只需切换集成包，规格文档和项目结构完全复用。

局限与争议

Spec Kit 并非银弹，以下场景需谨慎评估：

1. 轻量级项目的过度工程风险

如果只是写一个几十行的小脚本，用 SDD 五步流程显得笨重。Spec Kit 官方也提供了简化版 Lean 路径，但与完整流程相比仍有差距。

2. 规格文档本身的维护成本

规格文档写得好，AI 输出才好。但写好规格本身就需要经验和投入。对于没有规范文档习惯的团队，初期可能会感到「多此一举」。

3. 集成深度的局限性

当前集成层主要是 Prompt 层面的适配——告诉 AI「在什么场景调用什么命令」。但不同 Agent 的能力边界不同，同一个 Prompt 在不同 Agent 上效果可能有差异。

4. Windows 环境适配

CLI 脚本同时支持 Bash 和 PowerShell，理论上跨平台。但 Docker 环境仍是官方推荐的生产级开发环境，Windows 原生环境可能遇到一些边界情况。

行业意义：把 AI 编程从「艺术」变成「工程」

2025-2026 年，AI 编程助手已经成为开发者的标配工具。但行业也普遍意识到「AI 写代码容易，写好代码难」——模糊需求导致的 AI 幻觉代码（hallucinated code）是线上故障的重要来源之一。

Spec Kit 的出现代表了一个重要趋势：将软件工程的最佳实践（需求规格、设计评审、代码审查）引入 AI 编程时代。它的核心价值不在于某个具体功能，而在于它建立了一种可复用的工作流——无论你用 Claude Code、Copilot 还是 Gemini CLI，都能在同一套框架下获得一致的高质量输出。

从数据看，该项目自 2025 年 8 月发布以来，增长迅猛：10.5 万 Stars、200+ 贡献者、424 个 Open Issues（活跃社区）、每月稳定更新。更重要的是，它催生了一个生态——社区扩展（如 Autospec、BMAD 集成）、社区预设（Presets）、社区集成不断涌现。

GitHub 将其定位为「AI 时代的开发工作台」并非虚言——在 AI 代码生成质量参差不齐、Prompt Engineering 高度依赖个人经验的当下，一套结构化的开发方法论的价值，不亚于当年 TDD（测试驱动开发）理念对传统软件工程的冲击。