跳到主要内容

规范驱动开发（Spec-Driven Development）

规范驱动开发（SDD）是一种创新的软件开发方法，它将需求规格说明书转化为可执行的指令，让 AI 代理能够自动完成从需求分析到代码实现的全过程。GitHub 的 spec-kit 项目是这一方法论的最佳实践工具。

什么是规范驱动开发​

规范驱动开发核心理念是：让开发者专注于"做什么"（What），而让 AI 代理处理"怎么做"（How）。通过标准化的文档模板和工作流程，SDD 确保了需求、设计、实现和测试的一致性。

传统开发 vs 规范驱动开发​

方面传统开发规范驱动开发
需求收集零散的文档、邮件、会议结构化的规范文档
设计过程分离的设计文档自动生成的技术方案
代码实现手工编写AI 自动生成
测试策略后期添加测试驱动，自动生成
文档维护经常过时与代码同步更新

GitHub spec-kit 核心组件​

spec-kit 由五个核心子系统组成：

1. specify CLI 工具​

# 安装 CLI 工具
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 初始化新项目
specify init my-project --ai claude

# 检查环境
specify check

CLI 工具提供三个主要命令：

  • init：初始化项目并下载模板
  • check：验证环境配置
  • version：显示版本信息

2. 项目结构（.specify/ 目录）​

.specify/
├── memory/
│   └── constitution.md          # 项目治理原则
├── scripts/
│   ├── create-new-feature.sh    # 创建功能和分支
│   ├── update-agent-context.sh  # 更新 AI 上下文
│   ├── setup-plan.sh            # 初始化规划工件
│   └── check-prerequisites.sh   # 验证环境
├── templates/
│   ├── spec-template.md         # 需求规范模板
│   ├── plan-template.md         # 实施计划模板
│   └── tasks-template.md        # 任务分解模板
└── specs/
    └── NNN-feature-name/        # 功能特定工件
        ├── spec.md              # 需求和用户故事
        ├── plan.md              # 技术实施计划
        ├── tasks.md             # 可执行任务列表
        └── contracts/           # API 规范
            └── api-spec.json

3. 斜杠命令系统​

spec-kit 提供了 8 个核心斜杠命令，每个命令对应开发流程的一个阶段：

命令用途输出工件
/speckit.constitution建立项目原则constitution.md
/speckit.specify创建功能规范spec.md, Git 分支
/speckit.clarify解决歧义更新的 spec.md
/speckit.plan技术规划plan.md, data-model.md
/speckit.analyze一致性验证验证报告
/speckit.tasks任务分解tasks.md
/speckit.implement执行实施源代码、测试
/speckit.checklist质量验证自定义检查清单

4. AI 代理集成层​

spec-kit 支持 17+ 种 AI 代理，包括：

  • Claude Code：通过 .claude/commands/ 目录
  • GitHub Copilot：通过 .github/prompts/ 目录
  • Gemini CLI：通过 .gemini/commands/ 目录
  • Cursor IDE：通过 .cursor/rules/ 目录

5. 模板和脚本系统​

  • 跨平台支持：提供 Bash 和 PowerShell 脚本
  • YAML 前置元数据：结构化模板格式
  • 自动化工作流：Git 分支管理、目录创建、上下文更新

完整工作流程示例​

让我们通过一个实际例子来体验规范驱动开发的完整流程。

第一步：建立项目原则​

/speckit.constitution 创建一个注重简洁性、测试优先开发和最少依赖的项目原则。优先考虑代码质量而非开发速度。强调清晰的文档和可维护的架构。

生成的 constitution.md 示例：

# 项目章程

## 第一条：库优先开发
所有功能都必须作为可导入的库来实现...

### 理由
支持可重用性和可测试性...

### 要求
- 所有核心逻辑都在库模块中
- CLI 包装器调用库函数

## 第二条：CLI 接口强制要求
每个库都必须提供 CLI 包装器...

## 第三条：测试优先指令
必须在实现之前编写测试...

## 第七条：简洁性门槛
最多 3 个不同的项目/组件...

第二步：创建功能规范​

/speckit.specify 构建一个照片相册管理器。用户可以创建相册，将照片添加到相册，并以网格布局查看照片。相册按日期组织。用户可以在相册之间拖放照片。每张照片显示缩略图，可以点击查看完整尺寸。

这将触发以下自动化流程：

  1. 创建新分支 001-photo-albums
  2. 生成结构化的 spec.md 文件
  3. 创建检查清单目录

生成的规范包含：

  • 用户场景：具体的用户流程
  • 功能需求：可测试的需求（如"用户可以创建最多100个字符的相册名"）
  • 成功标准：可衡量的成果（如"用户可以在30秒内上传100张照片"）
  • 关键实体：数据模型概念（相册、照片、用户）
  • 假设：未指定细节的默认值

第三步：技术规划​

/speckit.plan 使用 Vite 配合原生 JavaScript、HTML 和 CSS。使用 sql.js（浏览器兼容）在 SQLite 数据库中存储照片元数据。使用 FileReader API 处理照片上传。使用原生 HTML5 API 实现拖放功能。不使用外部 UI 框架。

此步骤会生成多个工件：

  • plan.md：技术实施路线图
  • data-model.md：实体关系模型
  • research.md：技术决策和库选择理由
  • contracts/api-spec.json：API 规范

第四步：任务分解​

/speckit.tasks

生成的 tasks.md 按阶段组织任务：

## 第一阶段：项目设置

### 用户故事：US-1 - 相册管理

**任务 T-1.1**：创建带 SQLite 模式的相册模型
- 文件：`src/models/Album.js`
- 依赖：无
- 创建带 id、name、created_at、photo_count 的相册表

**任务 T-1.2**：[P] 创建带元数据的照片模型
- 文件：`src/models/Photo.js`
- 依赖：无
- 创建带 id、album_id、file_path、thumbnail_path 的照片表

**任务 T-1.3**：初始化 SQLite 数据库连接
- 文件：`src/database/connection.js`
- 依赖：T-1.1, T-1.2
- 使用 sql.js 创建内存数据库

**检查点 T-1-VALIDATE**：运行数据库模式测试
- 验证相册和照片表存在
- 测试模型上的 CRUD 操作

第五步：执行实施​

/speckit.implement

AI 代理将：

  1. 验证先决条件（Node.js、npm 等）
  2. 按依赖顺序执行任务
  3. 并行执行标记为 [P] 的任务
  4. 在每个阶段后运行验证检查
  5. 自动处理构建和测试命令

第六步：质量验证​

实施完成后，系统会：

  • 运行完整的测试套件
  • 启动应用程序
  • 验证规范中的所有用户故事
  • 生成质量报告

在 Claude Code 中使用 spec-kit​

安装和配置​

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

# 2. 验证环境
specify check

# 3. 初始化新项目
specify init my-sdd-project --ai claude --script sh

# 4. 进入项目目录
cd my-sdd-project

# 5. 启动 Claude Code
claude

最佳实践​

  1. 先建章法：始终从 /speckit.constitution 开始，建立项目原则
  2. 明确需求：在 /speckit.specify 中尽可能详细地描述功能
  3. 技术决策：在 /speckit.plan 中明确技术栈和架构决策
  4. 任务细化：检查生成的 tasks.md 是否涵盖了所有实施细节
  5. 迭代优化：使用 /speckit.clarify 解决实施过程中的歧义

高级技巧​

1. 多项目管理​

使用统一的 constitution.md 跨项目维护一致性：

# .specify/memory/constitution.md
project_scope:
  max_components: 3
  preferred_languages: [TypeScript, Python]

quality_gates:
  test_coverage: "> 80%"
  documentation: "required"

architecture_principles:
  - "库优先开发"
  - "CLI 接口强制要求"
  - "测试优先指令"

2. 自定义模板​

修改 .specify/templates/ 中的模板以适应团队需求：

# .specify/templates/spec-template.md
---
name: "功能规范模板"
version: "1.0"
sections:
  - overview
  - user_scenarios
  - functional_requirements
  - success_criteria
  - api_contract
  - testing_strategy
---

## 功能需求

### FR-{N}: {需求标题}
**需求**：{具体需求描述}
**验收标准**：
- [ ] 标准 1
- [ ] 标准 2
**测试方法**：{如何验证该需求}

3. 集成 CI/CD​

# .github/workflows/spec-driven.yml
name: Spec-Driven Development
on:
  push:
    paths:
      - '.specify/specs/**/spec.md'
      - '.specify/specs/**/plan.md'

jobs:
  validate-specs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install specify-cli
        run: |
          pip install specify-cli
      - name: Validate specifications
        run: |
          specify validate --all-specs

规范驱动开发的优势​

1. 一致性保证​

  • 所有功能都遵循相同的文档结构
  • 需求、设计、实现保持同步
  • 减少沟通成本和理解偏差

2. 质量提升​

  • 测试驱动的方法确保代码质量
  • 自动化的检查清单避免遗漏
  • 持续的验证保证功能正确性

3. 效率提升​

  • AI 自动执行重复性任务
  • 模板化加速文档编写
  • 自动化的工作流减少手工操作

4. 知识沉淀​

  • 结构化的文档便于知识传承
  • 决策过程被完整记录
  • 最佳实践通过模板传播

常见问题和解决方案​

Q1: 如何处理复杂的功能需求？​

A: 将大功能分解为多个小的用户故事，每个故事使用独立的规范文档。例如：

  • 001-user-authentication
  • 002-user-authorization
  • 003-user-profile-management

Q2: 如何处理技术栈变更？​

A: 在 /speckit.plan 中详细记录技术决策的原因，使用 research.md 记录评估过程。如果需要变更，更新这些文档并重新运行 /speckit.tasks。

Q3: 如何确保生成的代码质量？​

A:

  1. 在 constitution.md 中建立严格的代码质量标准
  2. 使用 /speckit.checklist 创建自定义质量检查
  3. 集成代码审查流程到 CI/CD
  4. 定期审查和优化模板

Q4: 如何处理团队协作？​

A:

  1. 使用统一的 constitution.md 建立团队共识
  2. 为不同类型的功能创建专门的模板
  3. 建立规范审查流程
  4. 使用 Git 分支策略隔离功能开发

总结​

规范驱动开发通过标准化、自动化的工作流，显著提升了软件开发的效率和质量。GitHub spec-kit 为这一方法论提供了强大的工具支持，使其可以在实际项目中落地应用。

结合 Claude Code 的 AI 能力，开发者可以专注于创新和价值创造，而将重复性的实现工作交给 AI 自动完成。这种开发方式特别适合：

  • 快速原型开发
  • 标准化的企业应用
  • 需求频繁变更的项目
  • 注重文档和知识传承的团队

相关推荐​

如果您对规范驱动开发感兴趣，以下资源可能会帮助您：

  1. BMAD 方法论：AI 代理驱动的敏捷开发框架，提供了 19 种专业 AI 角色，可以与规范驱动开发形成互补

相关资源​

本节内容基于 GitHub spec-kit v0.2.0 版本编写。随着项目发展，部分功能可能会有所调整，请参考官方文档获取最新信息。