需求 → SPEC：让 AI 生成规范HERMES & AGENT ENGINEERING · 课时 04

4.1 SPEC 是什么

grill-me 拷问完了，你手里有一份需求简报。你可能会想，那我把这份需求简报直接丢给 AI 让它写代码。

别急，你试试就知道了——需求简报直接扔给 AI，出来的东西大概率跟你想要的不一样。需求简报是写给人类确认方向的，Agent 还需要一份结构化的 SPEC。

SPEC 的全称是 specification，规格说明书。它回答的不是"为什么要做"，而是"做成什么样算对"。

前面已经讲过项目宪章。现在把它和需求简报、SPEC、技术方案放在一起看：

• 项目宪章：描述整个项目长期必须遵守的原则，写给后面所有功能和 Agent 看。比如“所有资料都必须保留可追溯的来源”。
• 需求简报：描述要解决的问题、第一版范围和约束，写给人类确认方向。比如"做一个知识管理系统，帮我收藏资料"。
• SPEC：描述正确的标准，写给 AI 看。比如"系统收到一个网页链接，自动抓取正文，转成纯文本，按标签分类存储"。
• 技术方案：描述用什么技术实现，写给开发者和 Agent 看。比如"用 Python 写爬虫，数据存 PostgreSQL，前端用 React"。

项目宪章管长期边界，SPEC 管当前功能。如果一份新 SPEC 与项目宪章冲突，默认应该修改的是 SPEC，而不是为了让这个功能通过，临时改掉项目的长期原则。

还有一个关键点：SPEC 里不应该出现任何技术选型。你不会在 SPEC 里看到"用 Python 实现"或"数据存 MySQL"。这些是技术方案的事。SPEC 只关心"做成什么样算对"，不关心"用什么做"。保持这个原则，SPEC 才能在不同技术栈之间复用。

但这里有一个常见的误区，SPEC 里绝对不能出现任何的技术指南吗？比如：必须在浏览器中运行、不能依赖云服务、数据不能离开本地环境。这些是属于技术吗？应该写在 SPEC 里吗？

这些技术上的约束，我认为应该写在 SPEC 中，因为它们说的是“系统必须遵守什么”，并不是“用什么技术来实现”。

这两类内容要分开。“不能依赖云服务”是约束，可以写进 SPEC；“使用 IndexedDB，前端采用 React”是技术选型，应该等到下一步 Plan 再决定。这一点是很多开发者没有搞清楚的，他们认为 SPEC 里绝对不能提任何技术，这是对于 SPEC 的误解。

那么有了需求简报，是不是可以直接把它丢给 Agent 去开发了？

我看过很多人（包括程序员），都在这一步偷懒了。他们的问题出在：他们认为需求简报就可以替代 SPEC，把需求简报丢给 Agent 去开发。然后会抱怨：

这个模型不够强。

模型的能力是一方面，但你过于依赖模型的能力，把模型当做是许愿的机器也是个很大的问题。而SPEC 就是解决这个问题的。

比如"收藏资料"这四个字，可以展开成一套精确的描述：收藏什么、怎么收藏、怎么存储、怎么展示、查重怎么处理、失败怎么兜底。每一条都写得清清楚楚，AI 拿到手上不会有歧义。

4.2 SPEC 应该写清楚什么

一份 SPEC 应该写什么其实是一件很难说清楚的事情，因为不同团队不同的个人可能有自己的规范，但内容上应该把下面这些问题说清楚：

注意，上述表格并不是一种强制性的约束，更多的时候它只是一种提醒，提醒你的 SPEC 文档应该写清楚哪些事情。也不是每一项都必须出现，比如，只有在领域复杂、容易产生歧义时，才需要单独维护术语表。

其中有两组内容尤其容易混在一起。

验收场景描述一次具体行为：给定什么状态，用户做什么，系统应该返回什么。

成功标准描述功能上线后希望达到的结果，比如完成一次主要操作需要多长时间，或者有多少用户能够顺利完成任务。前者用来验收行为，后者用来判断结果。

4.3 为什么让 AI 生成，不自己手写

SPEC 文档应该让 AI 来写，你来审核。

你让我手写一份SPEC？太累了。而且写出来的大概率漏这漏那。 SPEC 本身就属于那种"写起来很烦、但检查起来很快"的东西。你花三个小时憋一份 SPEC，不如让 AI 三分钟生成一份，你花十分钟审计一遍。后者质量更高，因为人类擅长的是判断，不是从 0 开始编写。相反，AI最不擅长的就是判断。

所以正确的做法是：让 AI 按模板生成，你来审批。AI 擅长写结构化的文档，你擅长判断写得对不对。

亚当斯密在《国富论》里讲了一个"别针"的故事，指出合理的分工可以让生产力得到极大幅度的提高。我们和 AI 也要建立起这种分工机制。

让 AI 编写 SPEC 文档的时候，输入输出也很明确：

• 输入：需求简报（11.3 的产出）以及项目宪章（如果项目已经建立）
• 输出：初版 SPEC

初版 SPEC 不是最终版。生成之后，还要做一次针对 SPEC 的二次澄清，检查哪些地方会影响开发或验收，却仍然存在多种合理解释。

4.4 初版 SPEC 之后：二次澄清

二次澄清处理的对象已经不是模糊想法，而是刚刚生成的 SPEC。它会检查用户角色、数据规则、异常情况、非功能要求和验收标准等内容，找出那些会影响开发或验收、但目前仍有多种合理解释的地方，然后逐个向你提问。

你回答之后，把答案写回 SPEC。二次澄清的工作不是重新定义需求，也不是替你选择 React、数据库或 API，而是把初版 SPEC 中的重要歧义补齐。如果没有需要澄清的问题，也可以直接确认，进入下一个流程。

因此，实际顺序是：

需求简报
   ↓
生成初版 SPEC
   ↓
二次澄清
   ↓
确认后的 SPEC

4.5 你审批 SPEC 时看什么

生成的 SPEC 只是初稿。完成二次澄清后，你还需要逐条检查。记住，人永远是最后一道闸口——不管你前面有多少道 AI 自检，人都应该最后再检查一下。

重点看四个地方。

第一，关键歧义有没有处理。 如果 SPEC 里还留着未回答的问题，或者某个关键要求仍然有多种合理解释，说明这里还不能进入 Plan。

第二，验收场景是否覆盖核心流程。 验收场景必须覆盖这条路径上的每一个关键节点。如果某个节点没有验收场景，说明这个环节你可能漏想了。

第三，边界条件是否处理。 空值、超时、重复、异常输入——这些是 Agent 最容易出问题的地方。SPEC 里必须写明这些情况下的行为。比如"输入无效 URL 时返回错误提示，不创建空文章"，就是一条边界条件的验收场景。

第四，有没有混入技术细节。 如果 SPEC 里出现了"用 Python 写爬虫""数据存 PostgreSQL"这类描述，删掉。技术选型不属于 SPEC，属于技术方案。混在一起会导致两个问题：一是 SPEC 被技术栈绑定，换一个技术栈就要重写 SPEC。

注意，SPEC 文档不包括技术选项。技术选型需要推迟到下一步。不要混在一起，不然大家都做不好。

四个检查点过一遍，没问题就通过。有问题的标记出来让 AI 改，改完再看一遍。

4.6 审批通过之后

SPEC 审批通过了，需求明确了。接下来做什么？

放到以前，你可能会说"让 Agent 开始写代码"。但这里有一个问题：SPEC 里没有技术选型——这是你刻意保持的。Agent 拿到一份包含功能要求和约束、但不包含技术选型的 SPEC，怎么动手？

它需要先做一件事：生成技术方案。这个环节叫 plan（技术规划）。

然后还有 Tasks（任务分解）、Implement（实现）、验证（converge）——每一步做什么、哪些可以跳过、哪一步不能省，我们在 11.5 全部展开讲。

4.7 从 SPEC 到下一站

SPEC 有了，接下来做什么？

你可以直接跳到 11.5 看看技术方案是怎么生成的。但还有一件事：SPEC 不是写一次就完事的。系统会演进、需求会变更、团队会换人。今天的 SPEC 是权威基准，三个月后可能就没人记得当初为什么这么设计了。

所以你需要一套机制来管理 SPEC——版本控制、变更跟踪、验收机制、回滚能力。这就是 11.6 的内容：OpenSpec——SPEC 的工程化管理。

4.8 ■ 学点英语