从 SPEC 进入技术规划HERMES & AGENT ENGINEERING · 课时 01

1.1 SPEC 确定以后，技术问题才真正出现

胶囊系统的 SPEC 已经规定了系统要处理哪些资料、怎样形成纯文本证据、什么情况必须进入人工审核，也给出了可以验收的场景和结果。SPEC 的目的是写清楚“系统必须做到什么”。

但是，同一份 SPEC 可以对应很多种实现方案。证据和知识页可以保存在文件中，也可以放进数据库；资料处理可以是一个本地命令，也可以由 Web 服务接收；审核队列可以由页面展示，也可以由 Agent 在对话中列出。这些选择都会影响数据模型、模块边界和测试方式，却不应该在需求阶段由 SPEC 提前决定。

记住，SPEC 再复杂也只是“需求文档”。

所以，SPEC 确定以后还不能马上开始让 Agent 干活。如果没有中间的技术规划，不同任务就可能对同一个对象作出不同的假设，我们会对代码失控。

1.2 Plan 负责把需求变成可实现的设计

$speckit-plan 的任务是读取已经确认的 SPEC，再把其中的用户故事、功能需求、关键对象和验收条件，转换成一套能够指导实现的技术设计。在 Spec Kit 的标准流程里，这份设计会继续拆成 Tasks；如果使用能力较强的模型，也可以在人工审查 Plan 以后直接进入实现。

这四层保存的是不同阶段的决定。Plan 如果发现某项需求无法实现，或者两条需求相互冲突，应该把问题返回 SPEC 阶段处理，而不是在技术方案中悄悄换掉原来的需求。

1.3 $speckit-plan 先读取什么

执行 Plan 时，Spec Kit 先通过 .specify/feature.json 找到当前功能目录。对胶囊系统来说，当前功能是 specs/001-capsule-main-flow/，因此后面生成的规划文件也会放在这个目录中。

接下来需要同时读取三类上下文：

1.4 Plan 内部的两个阶段

$speckit-plan 会先生成 plan.md，填写项目的技术上下文，包括语言、主要依赖、存储方式、测试工具、目标平台、性能目标和项目规模。当这些信息还没有确定时，会先被标记为 NEEDS CLARIFICATION。

这里的 NEEDS CLARIFICATION 和 SPEC 阶段留下的需求歧义不一样。SPEC 中如果连用户要什么都没有确定，必须回到用户那里澄清。Plan 中的未知项通常是技术选择，比如当前规模应该使用文件还是数据库、音视频转写适合使用什么工具。它们会进入技术调研，需要真正影响产品范围或使用方式时，才重新请用户作出决定。

SPEC + 宪章 + 当前项目
              ↓
     填写 Technical Context
              ↓
        第一次宪章检查
              ↓
Phase 0：调研技术未知项
              ↓
Phase 1：设计数据模型、接口和验证指南
              ↓
        第二次宪章检查

Phase 0 会把每个未知项变成具体的调研问题，然后把结果写入 research.md。这份文档不只记录最后选了什么，还要保留选择理由和考虑过的替代方案。以后某项技术需要更换时，我们才能知道当初的选择是因为什么，而不是只看到一个结论。

1.5 Phase 1 把技术决定变成系统设计

Phase 0 完成以后，我们已经知道技术上准备怎么选，但还不足以直接拆分开发任务。比如，Phase 0 可能决定用飞书多维表格保存审核项，由 Agent 基座展示审核内容。本教材以 Hermes 为目标环境，但这个决定仍然留下了很多问题：一个审核项需要保存哪些信息，怎样从“待审核”变成“已处理”，Agent 又要通过什么方式读取它。

Phase 1 就是把这些还停留在“方案”层的决定，继续推进成可以指导开发的设计。它不再比较要不要使用飞书，而是在已经确定的技术方向下，明确系统中有哪些对象、它们怎样产生关系，以及不同模块之间怎样交换信息。

以“独立图片只能识别出局部信息”这个验收场景为例，SPEC 规定系统不得补写无法确认的内容，并且必须生成处理中断审核项。Phase 1 会继续把这条需求展开：

图片无法完整识别
        ↓
生成审核项并保存中断位置
        ↓
Agent 读取审核信息并向用户展示
        ↓
用户补充信息、重试或终止处理
        ↓
系统保存决定，然后恢复或结束原流程

data-model.md 负责定义这条流程里的对象。它需要记录审核项与哪份衍生证据相关，为什么中断，应该从哪一步恢复，以及用户作出决定后状态怎样变化。这里的“数据模型”不只是数据库表，它更重要的作用是把 SPEC 中的“审核项”“衍生证据”和“审核决定”变成系统可以长期保存和准确处理的对象。

contracts/ 负责定义这些对象如何在模块之间传递。胶囊系统没有 Web 页面，所以这里的契约不一定是 HTTP API。它更可能用来约定 Agent 调用 Python 工具时应该传入什么，Python 返回哪些信息，以及读取失败或用户决定不完整时如何表示。有了这份约定，不同 Agent 基座和 Python 工具才不会对同一个字段作出不同理解。

quickstart.md 则从可验证的角度把设计再走一遍。它要记录怎样准备一张无法完整识别的图片，怎样触发处理，应该看到什么审核信息，以及用户作出决定后如何确认原流程的去向。它不是完整的测试代码，而是把 SPEC 里的验收场景与当前技术设计连在一起，证明这个设计确实有办法实现需求。

Phase 1 不写正式功能代码，也不拆分开发任务。它要做的，是把 Phase 0 中已经选定的技术方向，变成对象、关系、契约和验证路径。这些内容固定下来以后，标准的 Spec Kit 流程可以继续使用 $speckit-tasks 生成开发任务，高级模型也可以把它们作为直接实现的依据。

1.6 Plan 会生成哪些文件

执行完成后，当前功能目录通常会增加下面这些内容：

tasks.md 不在这一步生成。Plan 负责把技术设计定下来。用户审查完这些产物以后，可以按照 Spec Kit 的标准流程使用 $speckit-tasks 拆分开发任务，也可以把全部规划产物直接交给高级模型。后面会专门讨论这两条路线的选择。

1.7 P1 和 P2 在 Plan 中怎样处理

当前 SPEC 中有三条 P1 用户故事：让资料进入长期维护的 Wiki、获得纯文本且可追溯的证据，以及在审核队列完成人工判断。这三条共同组成第一个可安全使用的版本。

Plan 可以覆盖完整的 P1、P2 甚至是 P3，但并不一定要一次实现全部功能。可以分阶段实现。后面的 Tasks 可以按用户故事和依赖关系排列，先完成 P1 并进行阶段验收，再继续实现 P2。

这种做法可以让一个还不确定的产品先交付最小可用版本，也更适合刚开始练习 SDD 的同学。

在本教材的胶囊系统中，我们选择另一种做法：P1 和 P2 统一规划，并在同一次实现中全部完成。主要原因是，现在的 Vibe-Coding 基本上是在探讨理论和需求，很少动手编码，他已经足够的枯燥了。如果再进一步的拆分 P1 和 P2，会引出更多的方法论。

这毕竟是我们第一门真正的工程意义上的 Vibe-Coding 教材，所以还是直接 P1 和 P2 一起实现吧。如果你有需要，再分阶段实现。

1.8 当前已经具备的规划输入

现在的胶囊系统已经具备执行 Plan 所需的需求输入：

• 项目宪章已经升级到 1.1.0，三条长期原则都已确认。
• specs/001-capsule-main-flow/spec.md 中没有遗留的需求澄清项。
• SPEC 质量检查表已经通过，用户故事 1、2、3 被确认为 P1。
• 当前功能目录已经记入 .specify/feature.json，Plan 可以找到正确的 SPEC。

这里说的“已经具备输入”，不表示所有技术选择都已经确定。相反，当前项目还没有选择语言、存储方式和项目结构。这些未知项正是 Phase 0 需要调研的内容。

需求输入已经准备好，不等于 Plan 可以在完全没有限制的情况下自由选择技术。真正启动规划以前，还要由用户确定技术决策不能偏离的范围，并指定哪些平台偏好需要进入 Phase 0 验证。