105K Star！GitHub Spec Kit 深度解析：Spec-Driven Development 如何终结 Vibe Coding

105K Star！GitHub Spec Kit 深度解析：Spec-Driven Development 如何终结 Vibe Coding

原文链接：github.com/github/spec… | Stars: 105,593+ | License: MIT

---

一、问题引入：Vibe Coding 为什么不行？

2025 年以来，"Vibe Coding" 成了 AI 编程社区的关键词。它的典型场景是：开发者打开 Cursor 或 Copilot Chat，输入一句模糊的需求描述，AI 哗哗地生成几百行代码，你觉得"卧槽牛逼"，跑起来发现有一半功能不符合预期。于是你继续在 Chat 里追问——"能不能再加个暗色模式？"、"这个 API 返回值能不能改成分页？"……几个回合下来，代码变成了打满补丁的意大利面。

这不是 AI 的问题，这是工作流的问题。

Vibe Coding 的本质是从实现出发反推需求——你看到代码了，才想起来"好像少了个功能"。它的核心缺陷有三：

1. 需求漂移（Requirements Drift）：每次追加 prompt 都在悄悄改变系统边界，没人记录变化轨迹。
2. 缺乏一致性验证：AI 不知道哪段代码是"临时方案"，哪段是"正式架构"。3 轮对话后，同一个概念可能有 3 种不同的实现。
3. 不可复现：同样的 prompt，换个模型版本、换个上下文窗口长度，生成结果截然不同。这不是工程，这是赌博。

Spec-Driven Development（SDD）的答案是：让规范成为可执行的一等公民，代码服务于规范，而非反过来。

正如 GitHub Spec Kit 官方哲学所述：

"For decades, code has been king. Specifications served code—they were the scaffolding we built and then discarded once the 'real work' of coding began. Spec-Driven Development inverts this power structure. Specifications don't serve code—code serves specifications."

这是一次权力结构的倒转。

---

二、Spec-Driven Development 核心哲学

2.1 权力倒转：规范不再服务于代码

传统软件开发中，PRD（产品需求文档）和设计文档的地位是什么？我告诉你——用完即弃。Team Lead 花两天写完一份 20 页的技术方案，团队看一遍，然后它就被扔进 Confluence 的角落吃灰。代码才是"真理"，文档只是"良好愿望"。

SDD 彻底颠覆了这个关系：

传统模式：PRD → 设计文档 → 编码（文档随时过时）
SDD 模式：规范（Spec）→ 执行计划（Plan）→ 生成代码（代码是规范的可执行表达）

在 SDD 的视角下，规范不是"参考"，而是源文件。变更不是改代码，而是先改规范，再重新生成代码。调试不再是追 bug，而是查规范覆盖不到的场景。重构不再是重写代码，而是重组规范结构。

这种转变之所以现在可行，是因为三个技术条件的成熟：

• AI 语言理解能力达到阈值：自然语言规范可以可靠地生成工作代码。
• 软件复杂度指数级增长：手动维护意图和实现的一致性越来越不可能。
• 迭代速度要求越来越高：Pivot 不再是例外，而是常态。

2.2 核心原则一览

SDD 有六条核心原则，每一条都在对抗传统开发的痼疾：

原则	解释	对抗的开发痼疾
规范即 Lingua Franca	规范是主要产物，代码是其表达式	"代码才是真理"
可执行规范	规范必须精确到能生成工作系统	"需求文档就是形式"
持续精炼	一致性验证是持续过程，非一次性关卡	"评审完了就完了"
研究驱动上下文	Agent 自动调研技术选项和约束	"我忘了调研那个库"
双向反馈	线上指标反哺规范迭代	"出问题了打个 Hotfix"
分支探索	从同一规范生成多种实现方案	"只能选定一种"

---

三、Spec Kit 架构详解

3.1 整体架构：CLI + Agent 指令 + 模板引擎

Spec Kit 不是一个"平台"，它是一个本地 CLI 工具包。安装方式只有一行：

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

它做的事情很简单但设计精巧：

• specify init 在项目根目录创建 .specify/ 目录，包含模板、脚本和 Agent 指令
• 通过 Constitution → Specify → Plan → Tasks → Implement 五步流程驱动开发
• 支持 Extensions（扩展） 和 Presets（预设） 两套定制体系

它本质上是一个模板生成和 Agent 指令分发系统。Spec Kit 本身不调用任何 LLM——它只是把正确的 prompt、模板和上下文注入到你的 AI Coding Agent 中。

3.2 五步工作流详解

Step 1: Constitution（项目宪章）

/speckit.constitution 创建一个项目宪章（constitution.md），定义项目的核心原则和开发规范。这不是什么空话文档——它是一种约束系统（Guardrails），会在后续所有步骤中被引用。

# PhotoGallery Constitution

## Core Principles

### I. Library-First
Every feature starts as a standalone library
Libraries must be self-contained, independently testable

### II. Test-First (NON-NEGOTIABLE)
TDD mandatory: Tests written → User approved → Tests fail → Then implement

### III. Simplicity
Start simple, YAGNI principles
Complexity must be justified in plan.md

这个宪章的威力在于：当 AI 在后续步骤做技术决策时，会逐条对照宪章。如果某个设计违反了"Test-First"原则，Plan 阶段的 Constitution Check 会直接标记为违规。

Step 2: Specify（需求规范）

/speckit.specify 接收用户描述，生成结构化的需求规范。这一步的魔法在于它生成的不是自由文本，而是严格按照模板的结构化文档：

# Feature Specification: Photo Album Manager

**Feature Branch**: `001-photo-album-manager`

## User Scenarios & Testing

### User Story 1 - Create & View Albums (Priority: P1)

**Why this priority**: Core MVP functionality

**Independent Test**: Create an album, verify it appears in the album list

**Acceptance Scenarios**:
1. **Given** the app is loaded, **When** user clicks "New Album", 
   **Then** an empty album is created and displayed
2. **Given** an existing album, **When** user opens it, 
   **Then** all photos in that album are displayed in a tile grid

注意几个关键设计：

• 优先级分明的 User Stories：P1/P2/P3，确保 MVP 可独立交付
• Given-When-Then 验收场景：这些就是"活文档"，直接可转换为测试用例
• 独立可测试性：每个 User Story 都能单独实现、测试、部署
• 自动分支管理：CLI 自动创建 feature 分支（如 001-photo-album-manager）

Step 3: Plan（技术实现计划）

/speckit.plan 从需求规范生成技术实现计划。这是把"what"转成"how"的关键步骤。

## Technical Context

**Language/Version**: TypeScript 5.0+
**Primary Dependencies**: Vite (bundler), vanilla CSS, no frameworks
**Storage**: SQLite (via better-sqlite3)
**Testing**: Vitest
**Target Platform**: Web (Desktop + Mobile)

## Constitution Check

| Principle | Status | Notes |
|-----------|--------|-------|
| I. Library-First | ✅ Pass | Each module is a standalone lib |
| II. Test-First | ✅ Pass | Tests will be generated before implementation |
| III. Simplicity | ✅ Pass | No unnecessary frameworks, vanilla JS/HTML/CSS |

## Project Structure

src/
├── models/       # Album, Photo entities
├── services/     # Business logic layer
├── ui/           # UI components
└── lib/          # Shared utilities

tests/
├── contract/     # API contract tests
├── integration/  # Integration tests
└── unit/         # Unit tests

Plan 的输出还包括：

• research.md：自动生成的技术调研（库版本对比、性能基准）
• data-model.md：数据模型定义
• contracts/：API 契约（OpenAPI/JSON Schema）
• quickstart.md：快速验证场景

这些文档不是写一次就扔掉的——每次规范变更，它们会同步更新。

Step 4: Tasks（任务拆分）

/speckit.tasks 分析 plan 和其他设计文档，生成可执行的任务列表。

# Tasks: Photo Album Manager

## Phase 1: Setup
- [ ] T001 Create project structure per plan.md
- [ ] T002 Initialize TypeScript project with Vite
- [ ] T003 [P] Configure Vitest and ESLint

## Phase 2: Foundational
- [ ] T004 Setup SQLite database schema
- [ ] T005 [P] Create base Album/Photo models
- [ ] T006 [P] Setup API routing and middleware

## Phase 3: User Story 1 - Create & View Albums (P1) 🎯 MVP
- [ ] T007 [P] [US1] Create Album model in src/models/album.ts
- [ ] T008 [P] [US1] Create Photo model in src/models/photo.ts
- [ ] T009 [US1] Implement AlbumService in src/services/album.ts
- [ ] T010 [US1] Implement AlbumList UI in src/ui/AlbumList.ts
- [ ] T011 [US1] Add validation and error handling

## Phase 4: User Story 2 - Drag & Drop Reorder (P2)
- [ ] T012 [P] [US2] Implement drag-and-drop service
- [ ] T013 [US2] Add reorder UI to main page

亮点：

• [P] 标记：可并行执行的任务，ID 差异大的可安全并发
• [US1] 标记：任务归属到具体 User Story，支持独立交付
• Phase 隔离：Setup → Foundational → 每个 User Story 一个 Phase
• 🎯 MVP 标记：Phase 3 完成后即可交付 MVP

Step 5: Implement（执行实现）

/speckit.implement 按 task 顺序执行所有实现任务。AI Agent 会逐一读取任务、执行、验证，并把结果写入代码。

3.3 可选命令：质量保障三件套

除了核心五步，Spec Kit 还提供了三个质量保障命令：

/speckit.clarify    → 澄清模糊需求（Plan 之前建议运行）
/speckit.analyze    → 跨产物一致性 + 覆盖率分析（Tasks 之后、Implement 之前）
/speckit.checklist  → 生成自定义质量检查表（"对英文的单元测试"）

这三个命令的设计哲学是：在 AI 写代码之前，先用 AI 检查规范。 这比写完后 Code Review 高效得多。

---

四、实战示例：从 0 构建 Photo Album 应用

让我们用一个完整例子走一遍 SDD 五步流程。

4.1 初始化项目

# 安装 Specify CLI
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.8.14

# 初始化项目
specify init photo-gallery --integration copilot
cd photo-gallery

初始化后，项目目录结构如下：

photo-gallery/
├── .specify/
│   ├── memory/
│   │   └── constitution.md         # 项目宪章
│   ├── templates/
│   │   ├── spec-template.md        # 需求规范模板
│   │   ├── plan-template.md        # 技术计划模板
│   │   ├── tasks-template.md       # 任务列表模板
│   │   ├── checklist-template.md   # 检查表模板
│   │   └── overrides/              # 项目级覆盖
│   ├── scripts/
│   │   └── bash/                   # 自动化脚本
│   ├── extensions/                 # 已安装扩展
│   └── presets/                    # 已安装预设
├── .github/
│   └── copilot-instructions.md     # Copilot 上下文指令
└── specs/                          # 此后所有规范文档在此

4.2 Step 1: 建立宪章

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

AI 生成 constitution.md：

# Photo Gallery Constitution

## Core Principles

### I. Component-First Architecture
Every UI element is a self-contained component with its own styles
Components must be independently testable and reusable

### II. Test-Driven Development (NON-NEGOTIABLE)
All features start with failing tests
Red-Green-Refactor cycle strictly enforced
Coverage < 80% requires justification in plan.md

### III. Progressive Enhancement
Core functionality works without JavaScript
Enhanced features gracefully upgrade the experience
Accessibility is NOT optional - WCAG AA minimum

## Technical Constraints

- No external CDN dependencies (air-gapped capable)
- SQLite only (no server databases)
- Bundle size < 200KB gzipped
- First Contentful Paint < 1.5s

4.3 Step 2: 编写需求规范

/speckit.specify Build an application that can help me organize my photos 
  in separate photo albums. Albums are grouped by date and can be 
  re-organized by dragging and dropping on the main page. Albums are never 
  in other nested albums. Within each album, photos are previewed in a 
  tile-like interface.

AI 自动完成：

1. 创建分支 001-photo-album-manager
2. 生成 specs/001-photo-album-manager/spec.md
3. 填充完整的 User Stories 和验收标准

4.4 Step 3: 创建技术计划

/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 SQLite database.

AI 生成的技术计划中，你会看到类似这样的 Constitution Check：

## Constitution Check

| Principle | Status | Evidence |
|-----------|--------|----------|
| I. Component-First | ✅ PASS | Plan defines independent Web Components |
| II. TDD | ✅ PASS | Vitest configured, test structure defined |
| III. Progressive Enhancement | ✅ PASS | HTML-first approach, JS enhancement layer |
| IV. No CDN | ✅ PASS | All deps bundled via Vite |
| V. WCAG AA | ✅ PASS | Semantic HTML, ARIA labels in component spec |

4.5 Step 4-5: 生成任务并执行

/speckit.tasks    # 生成 tasks.md
/speckit.implement # 执行所有任务

整个流程从 idea 到可运行代码，实际交互时间不超过 30 分钟。这不是速通——每一步产出的文档都经得起 Code Review。

---

五、源码解读亮点

Spec Kit 的源码（Python 3.11+，基于 Typer + Rich + PyYAML）有几个值得学习的设计。

5.1 模板占位符系统

Spec Kit 的模板不是普通的 Markdown 文件。它们包含运行时的占位符系统：

# 来自 __init__.py 的核心渲染逻辑
def _install_shared_infra_impl(
    project_path,
    version,
    core_pack,
    repo_root,
    console,
    force=False,
    invoke_separator=".",
    ...
):
    """
    Page templates are processed to resolve __SPECKIT_COMMAND_<NAME>__
    placeholders using invoke_separator ("." for markdown agents,
    "-" for skills agents).
    """

这意味着同一个模板可以适配不同的 Agent 调用风格：

# Markdown Agent（如 Copilot）: __SPECKIT_COMMAND_PLAN__ → /speckit.plan
# Skills Agent（如 Codex）:    __SPECKIT_COMMAND_PLAN__ → $speckit-plan

5.2 集成注册表模式

Spec Kit 的 30+ Agent 集成是通过一个可扩展的注册表实现的：

def _build_agent_config() -> dict[str, dict[str, Any]]:
    """Derive AGENT_CONFIG from INTEGRATION_REGISTRY."""
    from .integrations import INTEGRATION_REGISTRY
    config: dict[str, dict[str, Any]] = {}
    for key, integration in INTEGRATION_REGISTRY.items():
        if integration.config:
            config[key] = dict(integration.config)
    return config

# 支持 TOML 和 Markdown 两种命令格式
_TOML_AGENTS = frozenset({"gemini", "tabnine"})

这种设计让新增一个 Agent 集成变得极其简单——只需要在 INTEGRATION_REGISTRY 中注册配置项即可。

5.3 Manifest 追踪和文件安全

Spec Kit 维护一个 speckit.manifest.json 来追踪每个安装文件的 SHA-256 哈希：

# 卸载时的安全检查
# - Unmodified files are removed automatically.
# - Modified files (where you've made manual edits) are preserved.
# - Use --force to remove all integration files regardless of modifications.

这意味着：

• 升级时只覆盖"你未曾碰过的文件"
• 你自己修改过的模板会被保留（毕竟那是你的 customization）
• --force 强制覆盖所有文件

5.4 Presets 优先级覆盖链

Spec Kit 有一个精密的模板解析优先级链：

优先级	组件类型	位置	用途
1 (最高)	项目级覆盖	.specify/templates/overrides/	单项目临时调整
2	Presets	.specify/presets/templates/	组织级标准覆盖
3	Extensions	.specify/extensions/templates/	新增能力
4 (最低)	核心	.specify/templates/	SDD 默认模板

运行时从栈顶向下查找，找到第一个匹配的就使用。这个设计让层级重叠变得可预测。

---

六、社区生态

6.1 30+ Agent 集成

Spec Kit 支持的 AI Coding Agent 列表堪称全明星阵容：

Claude Code    ← Anthropic 旗舰
GitHub Copilot ← 微软生态
Gemini CLI     ← Google 生态
Cursor         ← 编辑器新贵
Codex CLI      ← OpenAI
Windsurf       ← 另一编辑器流派
Qwen Code      ← 阿里通义
Trae           ← 字节跳动
Lingma         ← 阿里灵码
Kimi Code      ← 月之暗面
... 以及 AWS Q、Devin CLI、IBM Bob、Kiro CLI、Tabnine CLI 等

值得注意的是，中国厂商的 Agent（Qwen Code、Trae、Lingma、Kimi Code）都已经在官方支持列表中。这说明 Spec Kit 正在成为 AI 编码的通用协议层。

6.2 Extensions：扩展能力边界

Extensions 为 Spec Kit 添加原生不支持的功能：

specify extension search          # 搜索可用扩展
specify extension add <name>      # 安装扩展
specify extension list            # 列出已安装扩展

典型的 Extension 场景：

• Jira 集成：在 Plan 阶段自动关联 Jira Ticket
• V-Model 测试追溯：确保每个需求都有对应的测试
• 安全审查门控：在 Implement 前强制执行安全扫描
• 项目健康诊断：分析规范完整性和实现覆盖率

6.3 Presets：定制工作流

Presets 改变 Spec Kit 的行为方式——不改能力，只改模板和术语：

specify preset search             # 搜索可用预设
specify preset add <name>         # 安装预设

Presets 可以做这些事：

• 合规导向：重写 Spec 模板以包含监管追溯字段
• 方法论适配：引入 Agile/Kanban/DDD 的术语和工作流
• 安全门控：在 Plan 模板中强制加入安全审查清单
• 多语言本地化：把整个工作流翻译成中文/日文/其他语言
• 趣味定制：社区有个 pirate-speak-preset，把整个工作流变成海盗口吻（"Arr! The plan be ready!"）

6.4 Workflows：自动化多步骤流程

Spec Kit 还支持 Workflows——可复用的多步骤自动化流程：

specify workflow run <name>       # 运行工作流

Workflows 支持条件逻辑、循环、fan-out/fan-in、暂停/恢复等控制流。这让复杂的 SDD 流程（尤其是涉及多人协作的场景）可以被标准化和复用。

---

七、总结与展望

7.1 Spec Kit 的三层价值

对个人开发者：告别 Vibe Coding 的随机性。用 30 分钟的结构化规范工作替代数小时的 prompt 调试。每一次开发都留下完整的 Spec → Plan → Tasks → Code 追溯链。

对团队：规范成为团队的通用语言。PM 修改验收标准 → Plan 自动标记受影响的技术决策 → Code Review 对照原始规范，而非凭空评审。

对行业：Spec Kit 证明了"规范驱动"的工程可行性。105K Star 不是一个花哨 Demo 的数量级——这是全球开发者对"AI 时代需要新的工程方法论"的投票。

7.2 局限与挑战

1. 强依赖 LLM 能力：SDD 的质量上限取决于你用的 AI 模型。用 Claude 4 和用本地小模型跑出来的规范质量天差地别。
2. Brownfield 项目挑战：SDD 对从 0 开始的 Greenfield 项目效果最好。对于已有 100 万行代码的遗留系统，从"逆向规范"开始需要额外的工作量。
3. 企业约束复杂：虽然 Spec Kit 有 Presets 机制，但真正将组织级的安全、合规、架构约束注入 AI 生成的代码，仍需大量的前置配置工作。

7.3 未来方向

从 Spec Kit 的 Issues 和 Roadmap 看，几个方向值得关注：

• 多 Agent 协作：不同 Agent 负责不同阶段（Claude 写 Spec，Copilot 做 Implement）
• Spec 版本对比和 Diff：像代码 Diff 一样看到规范变更的影响面
• 在线指标 → Spec 自动化：线上性能瓶颈自动变成新的非功能需求
• 更丰富的社区 Extensions 和 Presets 生态：类似 VS Code 插件市场的繁荣

7.4 我的建议

如果你现在正用 AI 写代码，我的建议是：花 10 分钟跑一遍 specify init。不是因为它能立刻让你的代码质量翻倍——而是因为它会改变你思考问题的方式。

SDD 最核心的转变是心智模型：从 "AI 帮我写代码" 到 "AI 帮我定义规范，代码自然会好"。这就像从用手电筒探路，到先把灯打开——后者显然高效得多。

代码是苍白的，规范才是活的。在 AI 能写代码的时代，写什么 比 怎么写 重要一百倍。

---

参考

• GitHub Spec Kit 官方仓库
• Spec Kit 完整文档
• Spec-Driven Development 方法论
• Spec Kit CLI Reference
• Supported AI Coding Agent Integrations
• Community Extensions
• Community Presets