从模糊想法到 Shell 项目的完整脉络HERMES & AGENT ENGINEERING · 课时 02

2.1 一张图看完全程

从模糊想法到 Shell 项目，功能开发的主线一共五个阶段。第二阶段和第三阶段里面，还各自包含几个具体动作。

模糊想法
   ↓
需求：需求澄清 → 需求简报
   ↓
SPEC：规范生成 → 初版 SPEC → 二次澄清
   ↓
Agent 开发：plan → tasks → implement → converge
   ↓
  部署上线

这五个阶段构成了 Shell Engineering 从 0 到 1 的功能开发主链条。

后面几节我们会一步步展开，但先记住这张图——它是这一章的骨架，之后每个细节都能在这张图上找到位置。

2.2 五个阶段之上，还有一层项目宪章

上面这张图，画的是一个功能从想法到交付的主线。但一个项目并不是每做一个功能，就重新从空白开始。有些原则一旦定下来，后面所有功能都要遵守，不能让 Agent 每次重新决定。

比如胶囊系统里的资料必须能对照原始资料（证据），Hermes 负责理解和判断，飞书负责保存和展示。这些不是某一个功能的临时需求，而是整个项目的长期边界。今天做内容入库要遵守，以后做主题演化、搜索和问答，也不能违反。

在这套方法里，我们可以把这类项目级的长期规则称为项目宪章。它回答的不是“这次要做什么功能”，而是整个项目以后必须一直遵守什么。它可以规定系统的职责边界、数据原则、测试要求、安全约束和开发流程。

所以项目宪章不是另一份功能 SPEC。可以先这样理解：

因为宪章管的是整个项目，所以它不是五个阶段后面的“第六个阶段”，而是压在后续开发上方的一层约束：

项目宪章（长期原则）
        ↓ 约束
SPEC → plan → tasks → implement → converge

一个新项目开始开发时，通常先把宪章定下来，再开始写第一个功能 SPEC。后面每增加一个功能，Agent 都应该先检查新的规范和方案是否违反宪章。只有项目的长期原则真的发生变化时，才需要修订宪章本身。

2.3 五个阶段里，哪两个最值得讨论

现在把这五个阶段展开看看。

第一阶段，模糊想法。你脑子里有一个念头——想做点什么东西。这一阶段不需要学，你已经有想法了。

第二阶段，需求。模糊的想法往往不能用来做开发，还需要进一步把模糊的想法变成需求。这一阶段你完全可以自己凭借经验来编写，但更推荐先用问答式的需求访谈来帮助自己整理需求，再把问答整理成一份简短的需求简报。而常用的问答式工具是grill-me ，我们在后面会讨论这个工具。

第三阶段，SPEC 文档。把需求简报整理成初版 SPEC，再对初版 SPEC 做二次澄清，最后得到一份精确、可验证的规范：数据模型、业务规则、验收场景。11.4 会讲清楚这一步的通用方法。

第四阶段，交给 Agent 开发。SPEC 写好了，交给 Agent。它自己出技术方案、拆任务、写代码。你不需要操心怎么实现，只需要审批。

第五阶段，部署上线。项目做完了，部署到 Hermes 上运行。

这五个阶段里真正需要你学的东西其实很少。真正值得研究的，就是第二阶段和第三阶段——把模糊想法变成需求，再把需求变成 SPEC。

尤其是第三阶段，从需求到 SPEC。这是 SDD（规范驱动开发）的核心，也是大多数人做错的地方。

2.4 难点在哪里

很多人做 Shell 项目，第一步就急着让 Agent 开始写代码。想法刚有一个轮廓，就告诉 Agent：帮我写一个什么东西。

我举个例子。你想做一个"每天自动汇总 AI 新闻发给我的工具"。这个想法本身很明确，你告诉 Hermes：帮我写一个每天抓取 AI 新闻并发送邮件的工具。

Agent 收到指令，开始自己猜。

它猜你早上 9 点想看，于是设了定时任务。它猜你想看英文新闻，于是抓了 TechCrunch 的 RSS。它猜你关心大模型，于是加了关键词过滤。它猜你习惯用 Gmail，于是接上了 SMTP 服务。

一段时间后，Agent 把做好的东西交给你。

你打开一看，问题来了。你下午 2 点才有空看新闻，它在 9 点就发了。你只关心中文来源，它抓的全是英文。你不需要过滤，你想看的是技术论文更新，不是产业新闻。你用的是 QQ 邮箱，不是 Gmail。

Agent 不是故意的。它只是按自己的理解替你做决定。你给它的指令太模糊，它只能从指令里提取它认为合理的默认值。你也没有告诉它不要这样做，它当然不知道自己在猜。

反过来，如果你在写 SPEC 这一步多花一点时间，把需求说清楚，后面就完全不一样了。

SPEC 写清楚了，Agent 不用脑补乱猜，直接照着做；验收场景也为后续检查提供了明确依据。你不需要再凭感觉判断代码像不像，但仍然要确认交付物是否符合这些场景。

这就是 SDD 的价值：把精力花在写规范上，而不是花在返工上。

2.5 ■ 学点英语