spec-kit 使用笔记

是什么

GitHub 官方出品的 规格驱动开发（Spec-Driven Development, SDD） 工具包。

核心思路：在让 AI 写代码之前，先强制走一遍 规格 → 计划 → 任务 → 实现 的流水线，而不是直接用模糊 prompt 让 AI “随便写”（vibe coding）。

解决的问题：AI 编程助手在自由 prompt 下输出不稳定、难以预测。spec-kit 通过结构化规格文件让 AI 有据可依。

核心工作流

六步顺序执行，每步都有前置检查，缺少上一步产物会拒绝执行：

constitution → specify → clarify → plan → tasks → implement

示例：构建看板应用

/speckit.constitution 专注代码质量、测试覆盖率和性能要求

/speckit.specify 构建一个照片相册应用。相册按日期分组，支持拖拽排序，不支持嵌套相册，照片以瓦片方式预览。

/speckit.clarify

/speckit.plan 使用 Vite + 原生 HTML/CSS/JS，元数据存储在本地 SQLite，不支持图片上传。

/speckit.tasks

/speckit.implement

产物结构

每个功能在 .specify/specs/<feature-name>/ 下生成：

.specify/
├── memory/
│   └── constitution.md       # 项目原则
└── specs/
    └── <feature-name>/
        ├── spec.md            # 需求规格
        ├── plan.md            # 技术方案
        ├── tasks.md           # 任务列表
        ├── research.md        # 调研记录
        ├── data-model.md      # 数据模型
        └── api-contract.md    # API 契约

安装

重要：只从 GitHub 安装，PyPI 上同名包均为非官方包，存在安全风险。

# 推荐：固定版本安装
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

# 或 pipx
pipx install git+https://github.com/github/spec-kit.git@vX.Y.Z

# 验证
specify version

初始化项目

# 新项目（指定 AI 助手集成）
specify init <project-dir> --integration claude

# 现有项目
specify init . --integration claude

# 强制写入非空目录
specify init . --force --integration copilot

支持的集成：claude、copilot、cursor、codex、gemini、kiro 等 30+ 种。

适用场景

适合用 spec-kit：

• 非trivial 功能，直接 prompt 效果不稳定
• 团队协作，需要规格评审后再实现
• 需要从需求到代码的可追溯性
• 绿地项目从零开始搭建
• 遗留系统改造前先文档化现有行为

不适合用 spec-kit：

• 一次性原型、技术验证（overhead 太高）
• 极小改动（改个变量名、修个 typo）
• 这类场景直接 prompt 即可，或用 TinySpec 扩展（单文件轻量流程）

扩展生态

社区提供 70+ 扩展，覆盖：

• 项目管理集成：Jira、Azure DevOps、GitHub Issues
• 多 Agent 并行：MAQA 扩展，协调者 → 功能 Agent → QA Agent 并行跑
• 安全审查：内置安全检查步骤
• BDD 支持：Reqnroll 集成
• 云部署：Spec2Cloud（Azure）
• 遗留迁移：.NET Framework → 现代 .NET 7 阶段迁移

注意：社区扩展未经官方安全审查，使用前需自行检查源码。

注意事项

1. AI 过度发挥：Claude Code 等助手在 plan 阶段可能添加未要求的组件，务必审查 plan.md 再执行 implement。
2. 本地运行时依赖：/speckit.implement 会直接调用 dotnet、npm 等 CLI，缺少运行时会中途失败。
3. 上下文膨胀：长 SDD 会话会撑爆 Agent 上下文窗口，可用 Conduct 扩展将各阶段委托给子 Agent。
4. 非交互式环境：CI 中不传 --integration 参数时默认使用 Copilot 集成。

与其他方案对比

相关链接

• 仓库：https://github.com/github/spec-kit
• 社区扩展：https://speckit-community.github.io/extensions/
• 方法论文档：spec-driven.md（仓库内）