全面认识 Spec KitHERMES & AGENT ENGINEERING · 课时 03

3.1 Spec Kit 是什么

SDD 是一种开发方法。它强调先把需求写成可以检查的规范，再决定技术方案，最后才进入实现和验收。Spec Kit 是 GitHub 提供的一套开源工具，它把这套方法落实成了命令、模板、Agent Skill 和项目目录。

所以，Spec Kit 只是 SDD 的一种具体实现。你当然可以选择其他工具，也可以在熟悉这套流程以后，按照自己的项目需要进行调整。本章选择 Spec Kit，是因为它已经把 SDD 的主要步骤组织好了，适合用来完成第一次实践。

3.2 先分清两种输入方式

本章使用 Codex 开发胶囊系统。后面的操作会在两个地方发生：一部分在终端中执行，另一部分在 Codex 对话中完成。

终端命令

specify --version 和 specify init 都是终端命令：

specify --version
specify init

specify 是安装在电脑上的程序。第一条命令检查版本，第二条命令创建项目，并把模板、脚本和 Codex 集成资源写入项目目录。你可以直接在终端输入，也可以把明确的命令交给 Codex 执行。

$Skill名称 用来引用已经安装的 Skill

再看另一种写法：

$speckit-specify

这不是终端命令，而是在 Codex 对话中引用 Skill。$ 后面加上 Skill 的名称，表示当前任务要明确使用这个 Skill。

$ 只能引用已经安装并被 Codex 识别的 Skill，不会下载或安装新的 Skill。因此，$speckit-specify 的意思就是：这次任务使用 speckit-specify Skill，并按照它的说明执行。

实际使用时，通常还要在后面写清楚当前任务。例如：

$speckit-specify

请根据已经整理好的胶囊系统需求简报，生成这个功能的 SPEC。

Codex 收到这段输入后，会在项目的 .agents/skills/speckit-specify/ 目录中找到 SKILL.md。这份文件规定了需要读取哪些材料、生成哪些文档，以及结果应该保存到哪里。

Codex 有时能够根据上下文自动选择 Skill，但本章仍然会明确写出 $speckit-specify、$speckit-plan。这样每一步都更容易复现。

3.3 全局 CLI、项目文件和 Agent Skill

Spec Kit 整套工具可以分成三层：

安装 specify-cli，电脑只会获得 specify 命令。只有在执行 specify init 初始化项目后，项目才会出现 .specify/ 和 .agents/skills/目录。Codex 从这个项目启动以后，才能通过 $speckit-* 引用这些内置的 Skill。

所以，specify 和 $speckit-specify 虽然名字接近，作用却不同。前者是终端程序，负责初始化项目；后者是项目内的 Skill，负责把需求整理成 SPEC。

3.4 Spec Kit 的主流程

在初步了解 Spec Kit 的架构后，我们再来梳理下使用 Spec Kit 的步骤。注意，请结合前面11 章的 SDD 概念，始终记得，这一章是用 Spec Kit 来实践 SDD。虽然在局部细节上略有不同，但是基本复现了整个 SDD。

Spec Kit 的工作分成项目级和功能级两部分。

在初始化项目后，可以先用 $speckit-constitution 制定项目宪章。宪章保存的是整个项目都要遵守的原则，例如数据边界、技术限制和质量要求。只要这些长期原则没有变化，就不需要为每个功能重新制定一遍。

$speckit-constitution
        ↓
.specify/memory/constitution.md

项目原则确定以后，每个具体功能再按照下面的顺序推进：

经过 grill-me 整理的需求简报
        ↓
$speckit-specify
        ↓
spec.md
        ↓
$speckit-clarify
        ↓
确认后的 spec.md
        ↓
$speckit-plan
        ↓
plan.md 等技术方案文件
        ↓
$speckit-tasks
        ↓
tasks.md
        ↓
$speckit-implement
        ↓
代码和实现结果
        ↓
$speckit-converge
        ↓
实现缺口和追加任务

这条流程和前面讨论的通用 SDD 是一致的。需求先经过 $speckit-specify 和 $speckit-clarify，确认清楚后才进入技术规划；实现完成以后，再由 $speckit-converge 对照 SPEC 检查缺口。

3.5 本章主要使用的 Skill

$speckit-clarify 和 $speckit-converge 都带有检查动作，但检查的对象不同。前者发生在开发前，检查需求是否还有歧义；后者发生在实现后，检查代码是否满足 SPEC。

Spec Kit 还提供了几个附加 Skill：

这些 Skill 不在本章的主流程里。先理解前面的核心步骤，等项目真的需要一致性分析、自定义检查或 GitHub Issues 时再使用即可。

3.6 Spec Kit 特有的产物

通用 SDD 只要求有一份清楚、可验证的 SPEC，不规定一定要生成哪些附属文件。Spec Kit 在此基础上增加了一些自己的约定。

例如，$speckit-specify 生成 spec.md 后，还会创建一份需求质量检查清单，通常位于：

specs/<feature>/checklists/requirements.md

这份清单检查的是 SPEC 是否已经写清楚，能不能交给 $speckit-plan 继续处理。例如，需求里是否混入技术选型、验收条件是否可测试、成功标准是否能够度量。它不属于系统需求，也不是开发完成后的代码验收表。它只是 Spec Kit 设置的一道文档质量检查。

同样，$speckit-checklist 可以按照用户指定的主题生成其他检查清单。这些都是 Spec Kit 的增强能力，不是通用 SDD 的必备步骤。

3.7 Spec Kit 不会替你做抉择

Spec Kit 可以固定流程，但产品判断仍然需要由人完成。

• 它不会凭空决定系统要解决什么问题；
• 它不会替代前面的需求访谈和 grill-me；
• 它不能保证技术方案一定合理；
• 它不会替你完成最终部署；
• 它生成了任务，也不代表代码一定正确。

项目负责人仍然需要确认需求简报，审查 SPEC 和技术方案，并在实现后检查真实结果。Spec Kit 负责固定流程，真正的取舍和审批仍然由人完成。

下一节会执行 specify init，把 Spec Kit 的项目文件和 Skill 写入胶囊系统目录。初始化只准备开发工作区，不会生成业务代码、功能 SPEC 或技术方案。

3.8 ■ 学点英语