Spec Kit 安装与使用指南
文档定位：Spec Kit 的安装、初始化、需求规格、技术计划、任务拆分、实现推进、测试 bug 修复和收尾说明。
1. Spec Kit 是什么
Spec Kit 是 GitHub 推出的规格驱动开发工具集。它通过 specify CLI、模板、脚本和 agent 命令，把需求先转成规格、计划和任务，再让 AI 或开发者按这些文件实现。
核心流程：
Specify → Plan → Tasks → Implement
团队真实项目中建议扩展为：
Constitution → Specify → Clarify → Plan → Checklist → Tasks → Analyze → Implement → Converge → Self Test
与 OpenSpec / Superpowers 的关系：Spec Kit 管规格驱动项目模板（spec/plan/tasks）；OpenSpec 管变更档案（proposal/spec/design/tasks）；Superpowers 管 AI 执行纪律。三者搭配方式见
superpowers-guide.md§3。
2. 安装 Specify CLI
推荐使用 GitHub 仓库来源安装，不要安装 PyPI 上非官方维护的同名包。
使用 uv（推荐）：
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
specify version
specify self check
临时试用：
uvx --from git+https://github.com/github/spec-kit.git specify version
使用 pipx：
pipx install git+https://github.com/github/spec-kit.git
specify version
3. 初始化项目
进入项目根目录：
cd <project-root>
初始化 Codex skills：
specify init . --integration codex --integration-options="--skills" --script sh
如果目录非空且确认要合并模板：
specify init . --force --integration codex --integration-options="--skills" --script sh
如果只是想生成模板，不依赖本地 agent 检测：
specify init . --force --integration codex --integration-options="--skills" --script sh --ignore-agent-tools
初始化后常见目录：
.specify/
.specify/memory/constitution.md
.specify/scripts/bash/
.specify/templates/
.agents/skills/speckit-specify/SKILL.md
.agents/skills/speckit-plan/SKILL.md
.agents/skills/speckit-tasks/SKILL.md
.agents/skills/speckit-implement/SKILL.md
4. 命令在哪里执行
Spec Kit 分两类操作：
| 类型 | 执行位置 | 示例 |
|---|---|---|
| 安装和初始化 | Terminal | specify init . --integration codex |
| 需求、计划、任务、实现 | Codex 对话框 | $speckit-specify、$speckit-plan |
当前项目如果使用 Codex skills，命令通常写成：
$speckit-specify
$speckit-plan
$speckit-tasks
$speckit-implement
官网文档中常见 slash command（如
/speckit.specify），两者含义接近，只是当前 Codex 环境的触发方式不同。
5. 命令与产物
| 命令 | 主要产物 | 用途 |
|---|---|---|
$speckit-constitution | .specify/memory/constitution.md | 创建或更新项目原则 |
$speckit-specify | specs/<feature>/spec.md | 根据 PRD 生成需求规格 |
$speckit-clarify | 更新 spec.md | 澄清需求歧义 |
$speckit-plan | plan.md、research.md、data-model.md、contracts/、quickstart.md | 生成技术实现方案 |
$speckit-checklist | checklists/<domain>.md | 生成需求质量检查清单 |
$speckit-tasks | tasks.md | 生成可执行任务拆分 |
$speckit-analyze | 对话输出分析报告 | 实现前检查 spec / plan / tasks 一致性 |
$speckit-implement | 业务代码、测试、SQL、配置等 | 按 tasks.md 执行实现 |
$speckit-converge | 追加 convergence tasks | 实现后收敛缺口 |
6. 推荐流程
1. 切任务分支
2. 如项目首次接入或规则变化，执行 $speckit-constitution
3. 执行 $speckit-specify 生成 spec.md
4. 执行 $speckit-clarify 澄清歧义
5. 执行 $speckit-plan 生成技术方案
6. 执行 $speckit-checklist 检查需求质量
7. 根据 checklist 补齐 spec.md
8. 执行 $speckit-tasks 生成任务拆分
9. 执行 $speckit-analyze 做一致性检查
10. 根据 analyze 补齐 spec / plan / tasks
11. 执行 $speckit-implement
12. 执行 $speckit-converge
13. 如 converge 追加任务，再执行 $speckit-implement
14. 交付前 review 和自测
7. 常用提示词
| 场景 | 提示词 |
|---|---|
| 生成 spec | $speckit-specify PRD：<PRD 链接或内容>。请只生成需求规格，不进入实现。请明确 Out of Scope。 |
| 生成 plan | $speckit-plan 请基于当前仓库技术栈、目录结构、数据库变更方式和测试框架生成实现方案。不要更换技术栈。 |
| 生成 tasks | $speckit-tasks 请基于当前 spec.md 和 plan.md 生成可执行 tasks.md。任务必须包含具体文件路径、依赖顺序、测试任务和验证命令。 |
| 实现 | $speckit-implement 请按 tasks.md 顺序执行，并汇总完成项、阻塞项、验证命令和结果。 |
8. 如何调整需求
需求调整指业务范围、验收口径或非目标变化。
操作顺序：
收到需求调整
→ 回到 $speckit-specify 或直接更新 specs/<feature>/spec.md
→ 如有歧义，执行 $speckit-clarify
→ 如果影响技术实现，重新执行或更新 $speckit-plan 产物
→ 更新 $speckit-tasks 产物
→ 执行 $speckit-analyze 检查一致性
→ 再进入实现
提示词：
需求有调整：<说明调整内容>。
请先更新 spec.md，明确新增、删除或修改的验收口径。
如果影响技术方案，请同步更新 plan.md、research.md、data-model.md 或 contracts。
最后更新 tasks.md，并执行 analyze 检查一致性。
不要直接改代码。
9. 如何调整技术方案
技术方案调整指业务需求不变，但实现方式变化。
操作顺序：
发现技术方案需要调整
→ 对照 spec.md 判断业务行为是否变化
→ 业务行为不变：更新 plan.md / research.md / data-model.md / contracts
→ 业务行为变化：先回到 spec.md
→ 更新 tasks.md
→ 执行 $speckit-analyze
提示词：
技术方案需要调整：<说明原方案和新方案>。
请先判断 spec.md 是否受影响。
如果业务验收口径不变，只更新 plan.md、research.md、data-model.md、contracts 和 tasks.md。
如果验收口径变化，先更新 spec.md。
更新后执行 analyze 检查一致性。
10. 如何调整 Tasks
如果不改变需求和技术方案，只调整执行步骤、任务拆分、测试顺序或验证命令，主要改 tasks.md。
操作顺序：
发现 tasks 不合理
→ 判断是否影响 spec.md
→ 判断是否影响 plan.md
→ 不影响时，只更新 tasks.md
→ 调整任务拆分、依赖顺序、测试命令和验收步骤
→ 执行 $speckit-analyze
提示词：
tasks 需要调整：<说明问题>。
请先判断是否影响 spec.md 或 plan.md。
如果不影响，只修改 tasks.md。
请把任务拆得更可执行，补上 TDD 步骤、验证命令和预期结果。
11. 实现阶段
$speckit-implement 请按 tasks.md 顺序执行，遵守现有代码风格；不要做 PRD 外功能。完成后汇总已完成任务、未完成/阻塞项、验证命令和结果。
实现后收敛：
$speckit-converge 请对照 spec.md、plan.md、tasks.md 和当前代码检查是否还有未实现、部分实现或超范围实现。如有缺口，只追加 convergence tasks 到 tasks.md，不要直接改业务代码。
12. 测试提 Bug 处理
测试提 bug 后，先分类，不要直接改代码。
12.1 Bug 类型判断
| Bug 类型 | 判断标准 | Spec Kit 操作 |
|---|---|---|
| 实现缺陷 | spec.md 和 plan.md 已覆盖，但代码没做到 | 更新 tasks.md，增加 bug 修复和回归测试任务 |
| 需求遗漏 | 测试提出的是 spec.md 没写的新行为 | 先更新 spec.md，必要时重新 clarify / plan / tasks |
| 技术方案偏差 | 需求没变，但 plan.md 的方案有问题 | 更新 plan.md、research.md、data-model.md 或 contracts，再更新 tasks.md |
| 测试用例问题 | 实现符合 spec.md，测试期望不对 | 修测试并记录依据，不改业务需求 |
12.2 未合并 Feature 的处理流程
收到测试 bug
→ 复现 bug
→ 对照 spec.md 判断是否已有验收场景
→ 对照 plan.md 判断是否是方案问题
→ 更新 tasks.md，增加 bug 修复任务
→ 如需求或方案变化，同步更新 spec.md / plan.md
→ 执行 $speckit-analyze
→ 执行 $speckit-implement
→ 执行 $speckit-converge
12.3 已合并 Feature 的处理流程
新建 bugfix feature
→ $speckit-specify 记录 bugfix 需求
→ $speckit-plan 生成修复方案
→ $speckit-tasks 生成修复任务
→ $speckit-implement 执行修复
12.4 推荐提示词
测试提了 bug：<bug 描述>。
请先对照 spec.md 和 plan.md 判断它属于实现缺陷、需求遗漏、技术方案偏差还是测试用例问题。
如果是实现缺陷，只更新 tasks.md，增加失败测试和修复任务。
如果是需求遗漏，先更新 spec.md。
如果是方案偏差，先更新 plan.md 和相关设计产物。
更新后执行 $speckit-analyze，再按 TDD 修复。
13. 交付前检查
请基于 spec.md、plan.md、tasks.md、quickstart.md 和当前代码做交付前 review：
1. 功能是否完整；
2. 是否还有未完成任务或阻塞项；
3. 需要执行哪些测试命令；
4. 当前分支是否可以提测。
14. 参考链接
- Spec Kit GitHub：github.com/github/spec…
- Spec Kit 安装文档：github.github.com/spec-kit/in…
- Spec Kit Integrations：github.com/github/spec…
