GitHub Spec Kit 规格驱动开发实战：让 AI 编码 Agent 从 Vibe Coding 走向工程化治理

2026 年 5 月 27 日，GitHub 正式开源 Spec Kit——一个面向 AI 编码 Agent 的 规格驱动开发（Spec-Driven Development, SDD） 工具包。截至 7 月初，该项目已斩获 11.8k Star，成为继 Claude Code、Cursor 之后 AI 编码工具链最受关注的新项目。

Spec Kit 的出现并非偶然——2026 年的 AI 编码生态陷入了"Vibe Coding 困境"：开发者向 Claude Code 描述需求，AI 生成代码，看似高效，但当需求变更、团队协作、合规审计、生产部署时，没有人知道代码为什么是这样写的，"聊天记录即真相"的反模式严重阻碍了 AI 编码的工业化落地。

Spec Kit 用 四阶段闭环（Specify → Plan → Tasks → Implement） + Constitution 项目宪法 + 30+ Agent 适配 的设计，让规格成为单一真相源（Single Source of Truth），让 AI 编码回归工程化治理。

一、为什么需要 Spec-Driven Development？

1.1 Vibe Coding 的三大痛点

传统 Vibe Coding 流程（聊天记录即真相）:
┌──────────────┐
│ Developer    │
│ "做一个用户  │
│ 管理系统"     │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ Claude Code  │
│ 生成代码     │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ "再加个权限  │
│  控制"        │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ AI 修改代码  │
│ (有副作用)   │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ "为什么这个  │
│  文件这样写?" │
└──────┬───────┘
       │
       ▼
   找不到答案
   (聊天记录已滚动)

痛点 1：决策丢失

AI 生成的代码背后是无数次微决策（库选择、命名规范、错误处理策略），但这些决策只存在于 LLM 的概率分布中，不在仓库里。下次维护时，开发者只能"猜"AI 当时的想法。

痛点 2：需求蔓延

Vibe Coding 中，需求以自然语言对话形式追加，AI 容易在不同上下文窗口中理解不一致，导致代码偏离原始设计。

痛点 3：协作失序

团队成员想知道"这个模块的边界在哪"，只能翻聊天记录或读代码——规格文档不存在。

1.2 Spec-Driven Development 的核心理念

SDD 流程：规格即真相源
┌──────────────────────────────────────────────────────┐
│  Stage 1: Specify（规格化）                            │
│  └─► 编写 spec.md：用户故事 + 验收标准 + 边界条件        │
│       (Markdown，可版本控制)                            │
└──────────────────┬───────────────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────────────┐
│  Stage 2: Plan（技术方案）                             │
│  └─► 编写 plan.md：架构选型 + 数据模型 + 接口设计        │
│       (基于 spec.md，由 AI 协助生成)                     │
└──────────────────┬───────────────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────────────┐
│  Stage 3: Tasks（任务分解）                            │
│  └─► 编写 tasks.md：可执行任务清单                      │
│       (AI Agent 直接读取并执行)                         │
└──────────────────┬───────────────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────────────┐
│  Stage 4: Implement（实现）                           │
│  └─► AI Agent 按 tasks.md 逐步实现                     │
│       (每步可回溯到对应的 spec 条款)                    │
└──────────────────────────────────────────────────────┘

核心承诺：

• 规格（spec.md）是单一真相源，所有决策可追溯
• AI Agent 不能偏离规格要求
• 团队成员无需读聊天记录就能理解项目

二、Spec Kit 快速上手

2.1 安装 specify CLI

# 方法 1：uvx（推荐）
uv tool install specify-cli --from git+https://github.com/github/spec-kit

# 方法 2：pipx
pipx install specify-cli

# 方法 3：Homebrew（macOS/Linux）
brew tap github/spec-kit
brew install specify

# 验证安装
specify --version
# specify-cli 0.4.2

2.2 在项目中初始化 Spec Kit

# 进入项目目录
cd ~/projects/my-saas-app

# 初始化 Spec Kit（创建 .specify/ 目录）
specify init

# 输出：
# ✓ Created .specify/memory/constitution.md
# ✓ Created .specify/templates/
# ✓ Created .specify/scripts/

# 查看生成的结构
tree .specify/
# .specify/
# ├── memory/
# │   └── constitution.md    # 项目宪法
# ├── templates/
# │   ├── spec-template.md
# │   ├── plan-template.md
# │   └── tasks-template.md
# └── scripts/
#     └── check-prerequisites.sh

2.3 四阶段工作流实战

Stage 1：Specify（编写规格）

specify specify "构建一个支持多租户的博客系统后端 API"

Spec Kit 会自动生成 specs/001-multi-tenant-blog-api/spec.md：

# Feature Specification: 多租户博客系统后端 API

## User Scenarios & Testing

### User Story 1 - 租户注册与认证 (Priority: P1)
作为 SaaS 运营商，我希望租户能自助注册并管理 API Key，
以便快速开始使用博客服务。

**Acceptance Scenarios**:
1. **Given** 一个新访问者提交注册表单
   **When** 邮箱和密码通过验证
   **Then** 系统创建租户账号并返回初始 API Key
2. **Given** 租户尝试使用过期的 API Key
   **When** 调用任意 API
   **Then** 系统返回 401 错误

### User Story 2 - 文章 CRUD (Priority: P1)
作为租户管理员，我希望创建/读取/更新/删除文章，
以便管理博客内容。

## Functional Requirements

- FR-001: 系统 MUST 支持基于 API Key 的认证
- FR-002: 系统 MUST 实现租户数据完全隔离
- FR-003: 系统 MUST 提供文章的 CRUD 接口
- FR-004: 系统 MUST 支持 Markdown 格式
- FR-005: 系统 MUST 在 100 QPS 下 p99 延迟 < 200ms

## Key Entities

- **Tenant**: 租户（id, name, api_key_hash, created_at）
- **Article**: 文章（id, tenant_id, title, content, status）
- **ApiKey**: API 密钥（id, tenant_id, key_hash, expires_at）

Stage 2：Plan（技术方案）

specify plan "使用 Go 1.27 + Gin + PostgreSQL + Redis 实现"

生成 specs/001-multi-tenant-blog-api/plan.md：

# Implementation Plan: 多租户博客系统后端 API

## Architecture Overview
- **后端语言**: Go 1.27（启用 json/v2）
- **Web 框架**: Gin
- **数据库**: PostgreSQL 16 + Row-Level Security（租户隔离）
- **缓存**: Redis 7
- **认证**: API Key + HMAC 签名

## Tech Stack Decisions
| 决策 | 选项 | 理由 |
|------|------|------|
| 框架 | Gin | 性能 3x Echo，社区成熟 |
| ORM | sqlc | 类型安全，编译期检查 |
| 迁移 | golang-migrate | 简单可靠 |
| 监控 | OpenTelemetry | 标准化 |

## Data Model
```sql
CREATE TABLE tenants (
    id UUID PRIMARY KEY,
    name TEXT NOT NULL,
    api_key_hash TEXT NOT NULL UNIQUE,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE articles (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL REFERENCES tenants(id),
    title TEXT NOT NULL,
    content TEXT NOT NULL,
    status TEXT NOT NULL DEFAULT 'draft',
    created_at TIMESTAMPTZ DEFAULT NOW()
);

ALTER TABLE articles ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON articles
    USING (tenant_id = current_setting('app.tenant_id')::UUID);

API Design

Method	Path	Description
POST	/v1/tenants	注册租户
POST	/v1/articles	创建文章
GET	/v1/articles/:id	读取文章
PUT	/v1/articles/:id	更新文章
DELETE	/v1/articles/:id	删除文章

Performance Budget

• p50 latency: < 50ms
• p99 latency: < 200ms
• Throughput: 1000 QPS

**Stage 3：Tasks（任务分解）**

```bash
specify tasks

生成 specs/001-multi-tenant-blog-api/tasks.md：

# Tasks: 多租户博客系统后端 API

- [ ] T001 创建 Go module 和目录结构
- [ ] T002 配置 PostgreSQL 连接和迁移框架
- [ ] T003 实现 Tenant 数据模型和 Repository
- [ ] T004 实现 API Key 生成和验证中间件
- [ ] T005 实现 POST /v1/tenants 接口
- [ ] T006 实现 Article 数据模型和 Repository
- [ ] T007 实现 RLS 策略
- [ ] T008 实现 POST /v1/articles 接口
- [ ] T009 实现 GET /v1/articles/:id 接口
- [ ] T010 实现 PUT /v1/articles/:id 接口
- [ ] T011 实现 DELETE /v1/articles/:id 接口
- [ ] T012 添加 Prometheus metrics
- [ ] T013 编写单元测试（覆盖率 > 80%）
- [ ] T014 编写集成测试
- [ ] T015 性能压测（验证 p99 < 200ms）
- [ ] T016 编写 OpenAPI 文档

Stage 4：Implement（AI 自动实现）

# 使用 Claude Code 实现
claude-code "请按 tasks.md 顺序实现，每完成一个任务在前面打勾 [x]"

三、Constitution：项目宪法

Spec Kit 最有价值的创新是 Constitution（项目宪法） 机制——用一份 Markdown 文档定义项目的不可违反原则。

3.1 默认 Constitution 内容

.specify/memory/constitution.md：

# Project Constitution: 多租户博客系统

## Article I: Code Quality Standards
- 所有公共函数 MUST 有 GoDoc 注释
- 测试覆盖率 MUST >= 80%
- 代码 MUST 通过 golangci-lint 默认规则

## Article II: Security Requirements
- 所有 API MUST 验证 API Key
- 密码 MUST 使用 bcrypt 哈希（cost >= 12）
- SQL 查询 MUST 使用参数化（禁止拼接）
- 敏感配置 MUST 从环境变量读取

## Article III: Performance Standards
- API p99 延迟 MUST < 200ms
- 数据库查询 MUST < 50ms
- 单实例 MUST 支持 1000 QPS

## Article IV: Observability
- 所有请求 MUST 有 Trace ID
- 错误 MUST 记录到结构化日志
- 关键指标 MUST 暴露到 Prometheus

## Article V: Tenant Isolation
- 租户数据 MUST 完全隔离
- 跨租户访问 MUST 拒绝（HTTP 403）
- 数据库 MUST 启用 Row-Level Security

3.2 Constitution 的强制执行

AI Agent 在实现时，必须遵守 Constitution——如果 AI 提出违反 Constitution 的方案，Spec Kit 会自动拒绝：

specify check constitution

# 输出：
# ✓ Code Quality: pass
# ✓ Security: pass
# ✓ Performance: pass
# ✗ Observability: 发现 3 个 Trace ID 缺失
# ✗ Tenant Isolation: 1 个查询未使用 tenant_id
# 
# Total: 3 violations, must fix before commit

四、与 30+ AI 编码 Agent 集成

Spec Kit 的最大优势之一是 Agent 中立——它通过模板化指令与所有主流 AI 编码工具协作。

4.1 支持的 AI 编码 Agent 列表

Agent	集成方式	适用场景
Claude Code	原生集成	复杂项目、深度重构
GitHub Copilot	插件	日常补全、单元测试
Cursor	.cursorrules	全栈项目
Gemini CLI	环境变量	Google 生态
Windsurf	配置文件	团队协作
Cody	VS Code 扩展	企业级
Codeium	IDE 插件	免费方案
Continue.dev	VS Code / JetBrains	开源

4.2 Claude Code 集成实战

Step 1：生成 Claude Code 命令模板

specify generate claude
# 生成 .claude/commands/specify.md 等模板

Step 2：使用 Claude Code 执行任务

claude-code /specify-spec specs/001-multi-tenant-blog-api
claude-code /specify-plan specs/001-multi-tenant-blog-api
claude-code /specify-tasks specs/001-multi-tenant-blog-api
claude-code /specify-implement specs/001-multi-tenant-blog-api

Step 3：自定义 Slash Command

.claude/commands/specify-implement.md：

# /specify-implement 命令

请按以下流程实现 specs/$1 目录下的功能：

1. 读取 spec.md 理解需求
2. 读取 plan.md 理解技术方案
3. 读取 tasks.md 获取任务清单
4. 逐个实现 tasks.md 中的任务
5. 每完成一个任务，更新 tasks.md 的 checkbox
6. 完成后运行测试，确保通过
7. 提交时使用 Conventional Commits 格式

4.3 Cursor 集成实战

.cursorrules：

# Spec Kit Integration
当用户提到 "/specify" 时，加载 .specify/memory/constitution.md 和当前 specs/ 目录下的所有 spec.md。

实现代码前必须先：
1. 阅读 spec.md 理解需求
2. 阅读 plan.md 确认技术方案
3. 验证代码不违反 constitution.md

五、生产级工作流

5.1 团队协作 SDD 流程

┌─────────────────────────────────────────────────────┐
│  SDD 团队协作流程                                    │
├─────────────────────────────────────────────────────┤
│  1. Product Manager 编写 spec.md                    │
│     └─► PR 提交到 main 分支                         │
│         └─► Tech Lead Review spec.md               │
│             └─► PM 修改 → 通过                      │
│                                                     │
│  2. Tech Lead 编写 plan.md                          │
│     └─► 基于 spec.md，AI 协助生成                   │
│         └─► Architect Review plan.md                │
│             └─► Tech Lead 修改 → 通过              │
│                                                     │
│  3. AI Agent 生成 tasks.md                          │
│     └─► Tech Lead Review tasks.md                   │
│         └─► AI 按 tasks.md 实现                     │
│                                                     │
│  4. DevOps Review 代码 + 部署                       │
└─────────────────────────────────────────────────────┘

5.2 Git Hook 集成

.git/hooks/pre-commit：

#!/bin/bash
# Spec Kit pre-commit check

# 检查是否有新的 spec 文件
if git diff --cached --name-only | grep -q "specs/.*/spec.md"; then
    echo "🔍 Detected new spec, running Spec Kit checks..."
    specify check all
    if [ $? -ne 0 ]; then
        echo "❌ Spec Kit checks failed, commit aborted"
        exit 1
    fi
fi

# 检查 constitution 是否被遵守
specify check constitution --staged

5.3 CI/CD 集成

.github/workflows/spec-check.yml：

name: Spec Kit Check
on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Specify CLI
        run: |
          curl -fsSL https://raw.githubusercontent.com/github/spec-kit/main/install.sh | bash
      - name: Check Specification Quality
        run: specify check all
      - name: Check Constitution Compliance
        run: specify check constitution
      - name: Validate Tasks Completeness
        run: specify check tasks --completed-only

六、SDD vs 其他方法论

方法论	核心理念	工具支持	适合场景
TDD	测试驱动	pytest/junit	已有清晰需求
BDD	行为驱动	Cucumber/Behave	业务规则复杂
DDD	领域驱动	Event Storming	业务建模
SDD	规格驱动	GitHub Spec Kit	AI 编码时代
Vibe Coding	直觉对话	Claude Code	快速原型

经验法则：

• 生产项目 → SDD + TDD
• 探索性项目 → Vibe Coding → 稳定后转 SDD
• 遗留项目维护 → SDD 渐进式迁移

七、实战案例：3 个团队的 SDD 落地

7.1 案例 1：金融科技公司

• 背景：50 人团队，10+ 微服务
• 痛点：AI 生成的代码无法通过合规审计
• 方案：用 Spec Kit 建立 constitution + spec 模板 库
• 效果：合规审计通过率从 60% → 95%

7.2 案例 2：SaaS 初创公司

• 背景：3 人团队，6 个月从 MVP 到 100 万 ARR
• 痛点：需求变更频繁，AI 代码与产品需求脱节
• 方案：每周更新 spec.md，AI 按 spec 生成
• 效果：开发速度提升 40%，bug 率降低 30%

7.3 案例 3：游戏工作室

• 背景：20 人团队，Unity 项目
• 痛点：策划需求与代码实现脱节
• 方案：策划写 spec.md，开发读 spec.md 实现
• 效果：跨团队沟通成本降低 50%

八、Spec Kit 的局限与未来

8.1 当前局限

• 学习曲线：团队需要适应"先写规格再写代码"
• 模板维护：constitution.md 需要持续更新
• AI 偏差：AI 仍可能误解规格，需要人工 review
• 小项目开销：对 < 1000 行的小项目可能过度

8.2 2026 年路线图

根据 GitHub 公开 roadmap：

• 2026 Q3：Visual Spec Editor（VS Code 插件）
• 2026 Q4：Multi-repo Constitution（跨仓库共享原则）
• 2027 Q1：AI 自动 spec 生成（从对话/PR/Issue 提取）
• 2027 Q2：Spec Diff（规格变更可视化对比）

九、参考资料

• GitHub Spec Kit 官方仓库
• Spec Kit 官方文档
• Spec-Driven Development 论文
• GitHub Blog: Meet GitHub Spec Kit
• Claude Code 官方文档
• Cursor 官方文档
• Constitution 模式参考
• Vibe Coding 反模式分析

---

结语：Spec Kit 的本质不是工具，而是工程化思维的回归——在 AI 编码时代，规格文档不是负担，而是让 AI 与人类协作的"契约"。如果你正在被 Vibe Coding 的混乱所困扰，不妨从 constitution.md + spec.md + plan.md + tasks.md 四份文档开始，让 AI 编码从"魔法"变回"工程"。