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.gitspecify versionspecify self check

临时试用：

uvx --from git+https://github.com/github/spec-kit.git specify version

使用 pipx：

pipx install git+https://github.com/github/spec-kit.gitspecify 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-constitution3. 执行 $speckit-specify 生成 spec.md4. 执行 $speckit-clarify 澄清歧义5. 执行 $speckit-plan 生成技术方案6. 执行 $speckit-checklist 检查需求质量7. 根据 checklist 补齐 spec.md8. 执行 $speckit-tasks 生成任务拆分9. 执行 $speckit-analyze 做一致性检查10. 根据 analyze 补齐 spec / plan / tasks11. 执行 $speckit-implement12. 执行 $speckit-converge13. 如 converge 追加任务，再执行 $speckit-implement14. 交付前 review 和自测`

7. 常用提示词

场景

提示词

生成 spec

$speckit-specify PRD：<PRD 链接或内容>。请只生成需求规格，不进入实现。请明确 Out of Scope。

生成 plan

$speckit-plan 请基于当前仓库技术栈、目录结构、数据库变更方式和测试框架生成实现方案。不要更换技术栈。

生成 tasks

$speckit-tasks 请基于当前 spec.md 和 plan.md 生成可执行 tasks.md。任务必须包含具体文件路径、依赖顺序、测试任务和验证命令。

实现

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

提示词：

tasks 需要调整：<说明问题>。请先判断是否影响 spec.md 或 plan.md。如果不影响，只修改 tasks.md。请把任务拆得更可执行，补上 TDD 步骤、验证命令和预期结果。

11. 实现阶段

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-specify 记录 bugfix 需求→ $speckit-plan 生成修复方案→ $speckit-tasks 生成修复任务→ speckit-analyze，再按 TDD 修复。

13. 交付前检查

请基于 spec.md、plan.md、tasks.md、quickstart.md 和当前代码做交付前 review：1. 功能是否完整；2. 是否还有未完成任务或阻塞项；3. 需要执行哪些测试命令；4. 当前分支是否可以提测。

14. 参考链接

Spec Kit GitHub：https://github.com/github/spec-kit
Spec Kit 安装文档：https://github.github.com/spec-kit/installation.html
Spec Kit Integrations：https://github.com/github/spec-kit/blob/main/docs/reference/integrations.md