从 SPEC 到 Shell 项目：plan、实现与交付HERMES & AGENT ENGINEERING · 课时 05

5.1 技术方案：plan 是核心

二次澄清完成、SPEC 审批通过并冻结后，接下来做什么？

你可能会说"让 Agent 写代码"。且慢。SPEC 里没有技术选型——这是你刻意保持的。Agent 拿到一份包含功能要求和约束、但不包含技术选型的 SPEC，它不知道用什么技术来实现。

所以第一步是生成技术方案。这个环节叫 plan（技术规划），是 Shell Engineering 工作流里最核心的一步，没有之一。

Plan 的逻辑很简单：

• 输入：已经审批通过的 SPEC + 项目宪章。SPEC 里已经包含当前功能的非功能要求和约束
• 输出：技术方案文档（技术选型、架构设计、数据存储方案、外部依赖清单）

Agent 拿到 SPEC 和项目宪章之后，要先决定用什么技术来实现。纯前端方案还是带后端的？数据存在哪里？用哪个框架？这些选择直接影响系统的性能、可维护性和成本。

举个例子，如果 SPEC 写明“必须在浏览器中运行，不能依赖云服务”，Agent 在 plan 阶段就会在这个边界内做决定：用浏览器本地存储（比如 IndexedDB），选一个轻量前端框架，用某个库来解析 HTML 正文。如果 SPEC 和项目宪章都没有限定这些边界，Agent 可以自己选择，但必须在技术方案中写明自己做了哪些假设，供你审批。

技术方案长什么样

一份完整的技术方案，通常包含八个维度（这是我个人的经验，仅供参考）：

• 基座选型：Shell 项目用什么壳（比如 Hermes、PI Agent等）
• 开发工具：用什么Agent来写代码（比如 Codex、Qoder 等）
• 技术选型：前端用什么框架、后端用什么语言、数据库用什么
• 运行环境：项目跑在什么环境里（浏览器、Node.js、云函数等）
• 数据存储：数据存在哪里（飞书、MySQL、文件系统、云端数据库等）
• 对外服务：项目是否提供 API 或外部接口
• 外部交互：项目是否需要调用第三方服务（比如调用大模型 API、调用搜索引擎等）
• 交付物形态：最后交付什么（Skill、MCP 工具、完整应用，参考第 9 章 Shell Engineering的五种形态）

Agent 会按这八个维度，生成一份结构化的技术方案文档。你不需要自己写，但需要看懂、需要审批。

你需要审计技术方案

技术方案是 Agent 生成的，但最终决策权在你手上。你审计时看两件事：

第一，SPEC 和项目宪章里的约束有没有被遵守。 如果 SPEC 写了"必须使用飞书多维表格作为存储方案"，Agent 的技术方案里就不应使用 Excel 作为存储。如果项目宪章规定"只能用公司现有的技术栈（Java + MySQL）"，Agent 就不能擅自选 Python + MongoDB。

第二，技术选型是否合理。 你需要凭常识判断：一个个人知识管理工具，数据量不大、不需要多人协作，Agent 选 IndexedDB 做本地存储合不合理？

合理。

而如果Agent 选 PostgreSQL + 云服务器，那每月还要付几十美金。这不合理，打回重写。

不满意就打回，让 Agent 重新生成。满意了就通过。

5.2 任务分解：Tasks 是做什么的

技术方案通过了，接下来在标准 SDD 工作流里，还有一步叫 Tasks（任务分解）。

Tasks 做的事情很简单：把技术方案拆成一张可执行的任务清单，按依赖关系排序。比如技术方案说"先用 IndexedDB 存数据，再用 React 写界面"，Tasks 可能会拆成：

1. 搭建项目脚手架
2. 配置 IndexedDB 数据层
3. 实现数据增删改查
4. 写前端界面
5. 联调

每个任务都标注了依赖——第 3 步依赖第 2 步，第 5 步依赖第 3 和第 4 步。Agent 拿到这张清单，就可以按顺序逐一执行。

这个设计的初衷是什么？在早期，大模型的能力还不够强，你给它一个大的目标，它容易迷路、容易偏离方向。把目标拆成小任务，Agent 一次只做一件，出错概率就低很多。

但现在情况变了。像 GPT-5.6这种顶级模型，拿到技术方案之后，自己就能拆任务还能根据需要调度多个子Agent 协同工作。你不需要手动帮它拆成"第一步建数据库，第二步写 API，第三步写前端"——它自己会规划。

所以 Tasks 这一步你可以根据自己的模型能力决定是否直接跳过。但这一步是做什么事，你得知道：把大目标拆成小步骤，让执行更可控。 这个思想本身没有过时，只是现在 Agent 自己就能做这件事，不需要你插手。

5.3 实现：Implement 是怎么工作的

Tasks 定好了任务清单，下一步就是 Implement（实现）。

Implement 的工作方式值得了解一下。它的设计思路是"原子执行 + 原子提交"：

• 每个任务独立执行，一次只做一个
• 每个任务做完就提交一次代码变更
• 每个提交都有清晰的描述，说明做了什么、为什么这么做

为什么这么设计？两个原因。

第一，可追溯。 如果某个任务做错了，你可以定位到那一次提交，回滚或者修复，不会影响其他任务。

第二，可检查。 每个任务做完都可以验收——验收场景就是 SPEC 里写的那一套。如果第一个任务就通不过验收，说明方向错了，不用等到全部做完才发现。

Implement 在底层可能还会启用子 Agent 来并行执行。比如你有 5 个任务，其中第 2 和第 3 步没有依赖关系，Implement 可以同时派两个子 Agent 去执行，一个做数据层，一个做前端界面，互不干扰。

不过跟 Tasks 一样，Implement 这一步对于开发者现在也可以跳过。这一步实际上大多数 Agent 依靠 Harness 都能做的不错，不需要人工干预。除非你的模型很弱，才需要人工干预和规划。

5.4 验证：这一步不能省

好了，现在 Agent 把代码写出来了。你拿到一份交付物，看起来能运行。完事了吗？

没有。代码能跑不代表做对了。

这里有一个关键区别：运行不等于验证。 代码能运行，只说明没有语法错误、没有崩溃。但逻辑对不对、行为是否符合 SPEC，需要另外检查。

验证环节在 SDD 里叫 converge（收敛）。它的工作方式是这样的：

1. 对照 SPEC 里的验收场景，逐条检查交付物
2. 每一条验收场景都是一道考题——"输入这个，输出应该是那个"
3. 通过的就标记通过，不通过的就记录差距
4. 所有差距汇总成新的任务清单，追加到实现环节
5. 实现修复后，再次验证，再次检查
6. 重复这个循环，直到所有验收场景全部通过

这个过程叫"收敛"——每一次迭代，未通过的验收场景越来越少，最终收敛到零。收敛了，才算真正完成。

为什么不能省

你可能觉得"验证不就是跑一下测试嘛"，但 converge 做的不是单元测试，它做的是 SPEC 层面的验收。

单元测试验证的是"代码写得对不对"，converge 验证的是"系统做得对不对"。前者是技术问题，后者是业务问题。代码写得对，但业务逻辑错了，等于白做。

举个例子，胶囊系统的 SPEC 里有一条验收场景："用户输入一个已收藏的网页链接，系统提示'该链接已存在'，不创建重复条目"。Agent 实现的功能可能是：每次输入链接都重新抓取，没有检查重复就直接创建新条目。代码能运行，但行为不符合 SPEC。converge 就会发现这个缺口，标记为未通过，让 Agent 修复。

收敛到什么时候

收敛有一个明确的终点：所有验收场景全部通过。

"差不多都通过了"不算通过。收敛的定义就是零缺口。只要有一条验收场景没通过，就不能算完成。

这也反过来要求你：写 SPEC 的时候，验收场景不能太松。如果验收场景只是"系统能正常运行"，那收敛也没有意义。验收场景越精确，收敛的质量越高。

5.5 交付与部署

收敛通过了后，项目才算初步开发完毕。现在你有一份符合 SPEC 的交付物。

交付物是什么形态？参考第 9 章的五种形态：

• 纯 Skill（一个对话能力）
• Skill + 交付物（能力 + 配套文件）
• MCP + Skill（工具 + 能力）
• 代码骨架 + Skill（代码框架 + 能力）
• 完整应用 + Skill（完整项目 + 能力）

对于胶囊系统来说，交付物形态可能是形态四。代码+Skill+飞书环境。

做完这三步，你的胶囊系统就上线了。用户可以在超级 Agent 里直接说"帮我收藏这个网页"，系统会自动抓取、分类、存储。

5.6 从开发到管理

回到 11.2 的五阶段图：想法 → 需求 → SPEC → Agent 开发 → 部署。

现在你已经走通了前几步：

• 11.3：模糊想法 → grill-me 拷问 → 需求简报
• 11.4：需求简报 → 初版 SPEC → 二次澄清 → 审批后的 SPEC
• 11.5：SPEC 冻结 → plan（技术方案）→ converge（验证）→ 交付部署

整条链路的两个核心能力你已经掌握了：

SDD（规范先行开发）——先写 SPEC，再写代码。顺序不能乱。先写 SPEC，Agent 不会跑偏；先写代码，Agent 跑偏了你还不知道。

Shell Engineering（交付形态）——最终交付的不是代码，是一个可用的 Shell 项目。用户不需要关心你用了什么技术、数据存在哪里，他们只需要在对话里说一句话，系统就能完成一件事。

但还有一件事没解决：SPEC 不是一次性的。系统会演进、需求会变更、团队会换人——SPEC 本身需要一套管理机制。这就是 11.6 要讲的：OpenSpec——怎么用"主 SPEC + 增量变更"的模式，让 SPEC 像代码一样可追溯、可回滚、可验证。

5.7 ■ 学点英语