Spec-Kit — 规格驱动开发（SDD）

GitHub 官方开源工具包（v0.4.3），将规格驱动开发引入 AI Agent 工作流程。 Repo: https://github.com/github/spec-kit | License: MIT

什么是规格驱动开发？

Spec-Kit 颠覆了传统的 AI 编码范式：规格为一等公民，代码是派生产物。 它摒弃了直接向 AI 发送模糊提示的“氛围编码”（vibe coding），转而采用结构化流水线：

Constitution → Specify → Clarify → Plan → Tasks → Implement

每个阶段均有明确的输入、输出及质量关卡（quality gates）。

前置条件

CLI 安装

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

# 验证安装
specify check

系统要求：Python 3.11+、uv、Git，以及一个受支持的 AI agent。

Agent 支持

Spec-Kit 支持 30+ 种 AI agent。我们技术栈中关键的几个如下：

工作流命令

核心流水线

可选命令

CLI 参考手册

specify init

# 新项目
specify init my-project --ai claude

# 现有目录
specify init . --ai claude --force

# 启用 Codex 技能
specify init my-project --ai codex --ai-skills

# 跳过 git init
specify init my-project --ai claude --no-git

# 使用时间戳编号分支
specify init my-project --ai claude --branch-numbering timestamp

specify check

校验以下内容：git 及所有在 AGENT_CONFIG 中配置的 CLI agent。

扩展与预设管理

# 扩展
specify extension search                    # 浏览可用扩展
specify extension add                 # 安装扩展

# 预设
specify preset search                       # 浏览可用预设
specify preset add                    # 安装预设

项目结构

执行 specify init 后生成的目录结构如下：

project-root/
├── .specify/
│   ├── memory/
│   │   └── constitution.md          # 项目原则（Step 1）
│   ├── scripts/
│   │   ├── check-prerequisites.sh
│   │   ├── common.sh
│   │   ├── create-new-feature.sh    # 创建特性分支 + spec 目录
│   │   ├── setup-plan.sh
│   │   └── update-claude-md.sh
│   ├── templates/
│   │   ├── constitution-template.md
│   │   ├── spec-template.md
│   │   ├── plan-template.md
│   │   └── tasks-template.md
│   ├── extensions/
│   │   ├── catalog.json
│   │   └── /templates/
│   └── presets/
│       └── /templates/
├── specs/
│   └── 001-feature-name/
│       ├── spec.md                   # 功能规格（Step 2）
│       ├── plan.md                   # 技术方案（Step 4）
│       ├── research.md               # Phase 0 研究输出
│       ├── data-model.md             # 数据模型设计
│       ├── quickstart.md             # 快速入门指南
│       ├── contracts/                # API 合约
│       │   ├── api-spec.json
│       │   └── signalr-spec.md
│       └── tasks.md                  # 任务拆解（Step 5）
├── .claude/commands/
│   ├── speckit.constitution.md
│   ├── speckit.specify.md
│   ├── speckit.plan.md
│   ├── speckit.tasks.md
│   └── speckit.implement.md
└── [source code]

模板详情

Constitution（memory/constitution.md）

定义项目的不可协商原则。所有规格必须符合该文件。

结构如下：

• 核心原则（I、II、III…）—— 每条均含清晰描述
• 附加约束—— 技术栈、合规性、安全性等要求
• 开发工作流—— 代码审查机制、测试关卡等
• 治理机制—— 修订规则、合规性验证方式

仅 CEO/CTO 可修订。版本号格式：X.Y.Z | Ratified: YYYY-MM-DD

Spec（spec.md）

关键章节包括：

• 特性分支名：NNN-feature-name
• 用户场景与测试—— 按优先级排序的用户故事（P1、P2、P3），每条均可独立测试
• 边界情况—— 边界条件、错误场景
• 需求—— 功能性需求 + 非功能性需求
• 评审与验收清单—— 验证关卡

Plan（plan.md）

• 摘要—— 主要需求 + 技术路径
• 技术上下文—— 编程语言、依赖项、存储、测试框架、平台环境
• Constitution 校验—— 必须在 Phase 0 前通过
• 项目结构—— 文件树
• 实现细节—— 分阶段实现说明

Tasks（tasks.md）

格式：[ID] [P?] [Story] Description

• [P] = 可并行执行
• [Story] = 关联的用户故事（US1、US2…）
• 按用户故事组织，支持独立实现

扩展与预设

模板解析优先级（从高到低）

项目本地覆盖项 (.specify/templates/overrides/)
    ↓
预设 (.specify/presets//templates/)
    ↓
扩展 (.specify/extensions//templates/)
    ↓
核心模板 (.specify/templates/)

值得关注的社区扩展

值得关注的预设

Paperclip 集成

通过 API 重新指派（请使用此方式，而非 shell 脚本）

PAPERCLIP_API="http://localhost:3100/api"

# 按 agent ID 重新指派
curl -s -X PATCH "$PAPERCLIP_API/issues/$ISSUE_ID" 
  -H "Content-Type: application/json" 
  -d "{"assigneeAgentId": "$TARGET_AGENT_ID"}"

# 在 issue 下评论
curl -s -X POST "$PAPERCLIP_API/issues/$ISSUE_ID/comments" 
  -H "Content-Type: application/json" 
  -d "{"body": "已完成工作的描述"}"

Issue 生命周期

Dev → implement → reassign code-reviewer → CTO review → reassign qa → PM confirms → done
Bug: Dev → fix → reassign cto → reassign qa → done

最佳实践

1. 先写规格，再写代码—— 抵制“先写代码，后补文档”的倾向
2. Constitution 即法律—— 所有 PR 必须验证其合规性
3. 用户故事需分级优先—— P1 即 MVP，每条故事均可独立测试
4. 保持规格持续有效—— 实现发生变更时及时更新规格，切勿视而不见
5. 任务粒度合理—— 每个任务耗时不超过 2–4 小时，大任务应拆分
6. 善用扩展—— 安装 verify + cleanup 扩展以启用自动化质量关卡
7. 实施前务必验证—— 运行 /speckit.analyze + /speckit.checklist
8. 规划前先澄清—— /speckit.clarify 可显著减少返工

常见陷阱

• 跳过 Constitution 步骤 → Agent 做出不一致决策
• 规格过于笼统 → AI 幻觉生成功能或遗漏边界情况
• 省略 Clarify 步骤 → Plan 包含错误假设
• 任务过大 → AI 上下文丢失，产出有缺陷代码
• 变更后未更新规格 → 规格与代码出现漂移
• 规划阶段忽略 Constitution → 架构违规

升级

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

参考资料

• 官方仓库：https://github.com/github/spec-kit
• 方法论深度解析：仓库内 spec-driven.md
• GitHub 博客：https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
• 扩展目录： extensions/catalog.community.json
• 预设目录： presets/catalog.community.json
• Addy Osmani 的规格撰写指南：https://addyosmani.com/blog/good-spec/