Spec Kit 使用指南（增加 Bug Fixing & Assessment）



一、Spec Kit 是什么

Spec Kit 是 GitHub 开源的一套规范驱动开发（Spec-Driven Development，SDD）工具包：把结构化的 Markdown 文档作为主要产物，用它约束 AI 编码助手的输出，让"做什么 / 为什么做 / 怎么做"形成一条可追溯的文档链，而不是让助手凭一句提示词自由发挥。

它不再是"只有 SDD 一条流水线"，而是三条彼此独立的入口，按需选用、不必依次跑完：

你的需求流程产出形态
构建功能或应用规范驱动开发（SDD）规范 → 方案 → 任务 → 实现 → 收敛核心内置
排查并修复缺陷缺陷修复（Bug Fixing）评估原因、范围受控的修复、验证记录可选扩展 bug
判断一个想法是否值得做想法评估（Idea Assessment）基于证据的 go / needs-clarification / kill 决策可选扩展 assess

这三者是彼此独立的入口，不是必须依次完成的三个阶段。SDD 内置于核心；缺陷修复和想法评估由随工具提供的扩展实现，需要时再安装。

二、核心组件

组件说明
Specify CLI（specify）Python 命令行工具，负责初始化项目、管理扩展 / 预设 / 工作流 / 捆绑包
模板系统规范的 Markdown 模板，约束 AI 输出格式；支持项目本地覆盖
助手技能（Skills）/ 斜杠命令在 AI 助手里调用的 speckit.* 命令，按集成方式渲染成不同写法（见第四章）
扩展 / 预设 / 工作流 / 捆绑包插件化架构，支持自定义与面向角色的一键配置

三、安装与初始化

3.1 环境要求

  • 操作系统：Linux / macOS / Windows
  • Python 3.11 或更高
  • 包管理：uv（推荐）/ pipx / pip
  • AI 编码助手：Claude Code、GitHub Copilot、Gemini CLI、Codex、Cursor、Windsurf、Cline 等 30+ 种

3.2 安装 Specify CLI

# 三选一，推荐 uv
uv tool install specify-cli
pipx install specify-cli
pip  install specify-cli

# 一次性使用，不落地安装
uvx specify-cli init <项目名>

3.3 初始化项目

# 新建目录并初始化（不带 --integration 时默认集成为 copilot）
specify init my-project --integration claude

# 在当前目录初始化
specify init --here --integration claude

# 强制合入已有目录（跳过确认）
specify init --here --force --integration claude

常用选项：--integration <key> 指定助手，--script sh|ps|py 选脚本类型，--preset / --extension 初始化时装预设/扩展，--here 当前目录，--force 强制合入，--non-interactive 非交互。

3.4 验证

specify version        # 显示版本
specify check          # 检查已装助手与工具

四、命令怎么写：点号、连字符、还是 $

这是最容易踩坑的地方，必须先讲清楚。每个命令有一个规范的点号 ID（源码文件名就是 speckit.specify、speckit.bug.assess），安装时 CLI 会根据你选的助手，把它渲染成对应写法。所以同一条命令在不同助手里长得不一样：

集成 / 模式SDD 示例扩展命令示例
Claude Code、GitHub Copilot（默认 skills）/speckit-specify/speckit-bug-assess
Gemini / Cursor / opencode / Qwen 等/speckit.specify/speckit.bug.assess
Codex / ZCode（skills）$speckit-specify$speckit-bug-assess
Kimi（skills）/skill:speckit-specify/skill:speckit-bug-assess
参考文档正文里的规范写法/speckit.specify/speckit.bug.assess

关键提醒：官方文档正文统一用点号写法，但 Claude Code 与 Copilot 属于 skills 集成，实际要用连字符 /speckit-constitution（技能装在 .claude/skills/speckit-*/SKILL.md）。下文示例统一用连字符形式；若你用 Gemini/Cursor 等，把 - 换回 . 即可。

五、规范驱动开发（SDD）——核心流程

先明确做什么、为什么做，再决定怎么实现。SDD 把需求转化为规范、技术方案和可执行任务，再依据这些制品指导实现。

每个项目先确立一次章程；每个功能依次走：规范 → 方案 → 任务 → 实现 → 收敛。

完整命令链（含收敛循环）：

/speckit-constitution -> /speckit-specify -> /speckit-clarify -> /speckit-plan
   -> /speckit-checklist -> /speckit-tasks -> /speckit-analyze
   -> /speckit-implement -> /speckit-converge

命令链里只有 /speckit-specify 是 /speckit-plan 之前的硬性前置；clarify、checklist、analyze 是可选的质量门，给有明显歧义的需求加保险用。

5.1 各命令职责

命令（连字符形式）作用
/speckit-constitution确立或更新项目章程（后续每个阶段都要遵循的原则），并保持相关模板同步。项目开头跑一次，原则变了再更新。
/speckit-specify从自然语言描述创建/更新功能规范；聚焦"做什么、为什么"（用户可见的行为与目标），不定技术栈。自动编号、建语义化分支、生成 specs/<NNN-…>/spec.md。
/speckit-clarify（可选）就规范中欠明确处最多问 5 个针对性问题，把答案写回 spec.md 的 Clarifications 章节。规划前可反复跑，每次攻一个方面。原 /quizme。
/speckit-plan从规范生成设计制品：这里才放技术栈、架构、约束。产出 plan.md、data-model.md、research.md、quickstart.md、contracts/。
/speckit-checklist（可选）为功能生成"需求的单元测试"——检查规范本身是否完整、清晰、无歧义、一致（例如"每一列的拖拽规则都定义了吗？被删除的指派人行为定义了吗？"）。清单由 reviewer 拥有，[x] 表示需求质量已通过审阅，不代表代码写完了。
/speckit-tasks从设计制品生成按依赖排序的 tasks.md，分阶段：Setup → Foundational（阻塞性前置）→ 每个用户故事一个阶段（按优先级）→ 最后 Polish。可并行的任务标 [P]，并给出文件路径。
/speckit-analyze（可选）只读地跨 spec.md/plan.md/tasks.md 做一致性与质量分析，报告冲突、缺口、歧义（如某任务无对应需求、某方案选择与规范矛盾）。它绝不改文件，只出报告。发现问题就回到"拥有它的那一步"改源头，再重跑到干净。
/speckit-implement按 tasks.md 顺序执行，尊重依赖与并行标记。执行前把清单勾选状态当门槛读取：有未勾项会先问你再继续，但它不改清单标记。小功能一次跑完；大功能用参数分段跑、逐段验证。
/speckit-converge拿代码库跟规范/方案/任务比对，确认没漏。只追加：绝不改/删代码，唯一可能的写入是往 tasks.md 追加任务。须在当前 tasks.md 已 implement 后再跑。
/speckit-taskstoissues（可选）把 tasks.md 导出为 GitHub Issues。需要 GitHub origin 远端与 GitHub MCP 工具；只在该远端对应的仓库建 issue，并按已有任务 ID 去重。

5.2 收敛循环

反复执行 implement → converge，直到收敛报告给出 Converged。/speckit-converge 会先打印一份按严重程度分级的发现摘要，然后落到两种结果之一：

  • Converged——没发现缺口。tasks.md 一字不改，你会看到类似 ✅ Converged — the implementation satisfies the spec, plan, and tasks.，可以去 review 或开 PR 了。
  • Tasks appended——发现缺口。把它们作为新任务追加到 tasks.md 的 Convergence 小节，并告诉你追加了几条。再跑一次 /speckit-implement 补完，然后再 /speckit-converge。每轮发现的越来越少，重复到报告 converged 为止。

5.3 一个最小示例

specify init taskify --integration claude
cd taskify

在 Claude Code 聊天里逐条调用（每步看完结果再走下一步）：

/speckit-constitution 采用"安全优先"原则：所有用户输入必须校验；微服务架构；代码需完整文档。
/speckit-specify 开发团队协作平台 Taskify：可建项目、加成员、分派任务、看板拖拽、评论。初期五个预置用户（1 产品经理 + 4 工程师）、三个样例项目、看板列 To Do/In Progress/In Review/Done，暂不做登录。
/speckit-clarify 聚焦任务卡：可在看板列间改状态、可无限评论、可指派有效用户。
/speckit-plan 用 .NET Aspire + Postgres；前端 Blazor Server，支持拖拽与实时更新；REST API 拆成 projects/tasks/notifications 三套。
/speckit-checklist
/speckit-tasks
/speckit-analyze
/speckit-implement
/speckit-converge

六、缺陷修复（Bug Fixing 扩展）

把诊断、修复、验证三段分开：让助手先评估根因，再做范围受控的修复，最后回头检查最初出现的症状。不用先走一遍 SDD 功能开发流程。

6.1 安装（终端，一次性）

specify extension add bug

这是个随工具捆绑、需手动开启的扩展；它不注册任何生命周期钩子，三条命令永远由你显式调用。

6.2 三步流程

三条命令共享一个句柄——slug（.specify/bugs/ 下的每缺陷目录名）。用 slug=<名> 传；不给时 assess 会问你要（自动模式下自己生成唯一 slug）。slug 归一化为小写 kebab-case；若已存在同名评估，交互模式会先问再覆盖，自动模式则拒绝并另起唯一 slug。

/speckit-bug-assess "提交空密码会导致登录表单崩溃。" slug=login-crash
/speckit-bug-fix   slug=login-crash
/speckit-bug-test  slug=login-crash
命令做什么产物
/speckit-bug-assess把缺陷报告（粘贴的堆栈文本，或 GitHub issue 之类的 URL）对着代码库做分诊：判断是不是真 bug、定位可疑代码路径、提出修复方案。只读，只写 assessment.md，绝不改源码。.specify/bugs/<slug>/assessment.md
/speckit-bug-fix执行评估里提出的修复并记录具体改了什么。唯一会动源码的 bug 命令；只在评估列出的文件范围内改动，除非新证据要求扩大范围（记在 fix.md 的 Deviations from Assessment）。.specify/bugs/<slug>/fix.md
/speckit-bug-test重跑复现与新增测试来验证修复，记录结论。与 assess 一样对源码只读。结论绝不夸大：评估里列出的复现若没真正执行，整体降级为 partial 而非报 verified。.specify/bugs/<slug>/test.md

6.3 验证结论怎么读

  • verified——关键检查全过，原症状不再复现。
  • partial——症状消失但出现无关回归，或部分检查结论不明，或复现未真正执行。
  • failed——症状仍复现，或修复破坏了回归套件。

缺少验证不算修复成功。首个参数既可以是症状描述，也可以是 issue 链接（如 https://github.com/example/repo/issues/1234）。

七、想法评估（Idea Assessment 扩展）

在动手之前先收集证据，判断一个想法值不值得做——即使项目里还没有源代码、甚至不是软件类想法也能用。它是坐在 SDD"交付轨"（specify → clarify → plan → tasks → analyze → implement）前面的那条"发现轨"：发现轨回答"这值得做吗"，交付轨回答"怎么做"。只有通过评估的想法才交给 /speckit-specify。

7.1 安装

specify extension add assess

assess 在一个已初始化的 Spec Kit 项目里运行（评估写在 .specify/assessments/ 下），但那个项目可以完全没有源代码——刚 init 的空项目和成熟代码库一样能用。输入就是一个想法：粘贴文本、URL、工单，或指向某个代码库。

7.2 五步管道

五条命令同样共享 slug（.specify/assessments/<slug>/ 目录名）。这是一个漏斗：大多数想法应在 shape 之前就被 kill 或搁置——带着明确理由 kill 掉一个想法是成功的结果，不是失败。

/speckit-assess-intake "让用户离线工作、重新联网后自动同步。" slug=offline-mode
/speckit-assess-research slug=offline-mode
/speckit-assess-define   slug=offline-mode
/speckit-assess-shape    slug=offline-mode
/speckit-assess-decide   slug=offline-mode
命令阶段产物
/speckit-assess-intake捕获并归一化原始想法（文本 / URL / 工单 / 代码库指针）intake.md
/speckit-assess-research收集用户 / 市场 / 先例 / 数据证据——也包括反对这个想法的证据research.md
/speckit-assess-define定义问题：用户、目标、非目标、成功指标、不做的代价problem.md
/speckit-assess-shape形成 2–3 个概念级方案，带"投入意愿（appetite）"与取舍，推荐其一（或都不推荐）concept.md
/speckit-assess-decide对着标准打分并给出裁决；把 go 的想法交给 /speckit-specifydecision.md

7.3 阶段依赖与最终决策

阶段按顺序跑，但不是刚性门禁：define 是最小可用阶段，可直接对用户输入运行（intake/research 可选）；shape 需要 problem.md；decide 需要 problem.md，且 go 裁决期望有 concept.md，否则降级为 needs-clarification。

最终决策三选一：

  • go——问题成立、证据强度达到 adequate 以上（绝不能是 weak/unknown）、且有推荐方案。可把 decision.md 的交接摘要交给 /speckit-specify 进入开发。
  • needs-clarification——有前景但卡在具体未知项上。
  • kill——当下不值得做（记录理由后停止，同样是有价值的结论）。

遇到 [NEEDS CLARIFICATION: …] 标记时，直接完善已有的 Markdown 制品（或请助手把缺失信息并进那个文件），而不是重新生成整个阶段。补证据时保留 research 阶段的来源与置信标签（ASSUMPTION vs 有出处的论断），不要编造引用。

assess 是一条你主动进入的独立管道：不注册任何生命周期钩子，也不会自动插进 /speckit-specify。唯一的耦合是向前、且出于选择——一个 go 裁决把它的 decision.md 摘要交给规范阶段。发现与规范始终是两个独立过程。

八、CLI 命令参考

8.1 核心命令

命令说明
specify init [项目名]初始化项目
specify check检查已装助手与工具
specify version显示版本（--features / --json）
specify self check / self upgrade检查新版本（只读）/ 升级（--dry-run、--tag）
specify artifact list|info|lookup内省已安装的命令/模板/钩子等制品

8.2 扩展 / 预设 / 工作流 / 捆绑包

类别常用子命令
specify extensionlist / add / remove / search / info / update / enable / disable / set-priority + catalog
specify integrationinstall / uninstall / switch / use / upgrade / list / status / search / info / scaffold + catalog
specify presetlist / add / remove / search / resolve / info / set-priority / enable / disable + catalog
specify workflowrun / resume / status / list / add / remove / update / search / info / resolve + step / overlay / catalog
specify bundlesearch / info / list / install / update / remove / validate / build / init + catalog

8.3 模板覆盖优先级（从高到低）

  1. 项目本地覆盖 .specify/templates/overrides/
  2. 已安装预设 .specify/presets/templates/
  3. 已安装扩展 .specify/extensions/templates/
  4. Spec Kit 核心模板 .specify/templates/

内置扩展：git（Git 工作流，需手动 add）、agent-context、bug、assess。捆绑包示例：developer、product-manager、business-analyst、security-researcher——一键装好某个角色的扩展 + 预设 + 工作流。

九、适用场景

适用：从零起步、需要统一规范文档的新项目；需要 review 与版本管理规范的团队协作；要求 AI 产物可追溯的场景。此外还有两条轻量入口——单个缺陷的诊断修复（bug 扩展）、动手前的想法评估（assess 扩展）。

不适用：一行修复或极小改动走 SDD 全流程仍嫌重（但可只用 bug 扩展）；已有大型存量代码库且不打算补写历史规范时，可考虑增量式方案。

相关资源：GitHub 仓库 github/spec-kit、官方文档 github.github.io/spec-kit、缺陷修复指南 guides/bugfix.html、想法评估指南 guides/assessment.html、命令参考 reference/agentic-*.html。

posted @ 2026-09-17 10:27  起飞的乌龟  阅读(91)  评论(0)    收藏  举报