需求、规格与设计

变化在哪里

在传统 SDLC 里，一条需求变成代码之前要经过一个人。开发者发现工单与上季度的决定相矛盾，去问一句，最后做出来的东西与字面要求略有不同。读者换成智能体，这种非正式的纠错就消失了：它用看似合理的猜测填补空白，然后继续往下做。

工具已经把这一点说得很直白。GitHub 在 2025 年 9 月推出 Spec Kit，称之为"我们的实验"，目标是从"代码是事实来源"转向"意图是事实来源"。它的流程是 Specify、Plan、Tasks、Implement。Kiro 为每个功能维护三个文件：requirements.md、design.md 和 tasks.md，并用 EARS 句式写需求："WHEN [condition/event] THE SYSTEM SHALL [expected behavior]"（厂商文档，截至 2026 年 10 月）。前提是同一个：如果智能体会照着规格实现一切，那么产品就是在规格里决定的。

糟糕规格引出的失败有据可查。Answer.AI 把 20 个真实任务交给 Devin，结果智能体"会花上好几天追逐不可能的方案，而不是识别出根本性的障碍"（见案例）。GitHub 为其编码智能体写的使用指南读起来就像对症之方：把"缺乏清晰定义的任务"留给人，并给 issue 写上"完整的验收标准"（厂商指南，截至 2026 年 10 月）。一个分辨不出任务无法完成的智能体，需要规格替它说明，或者需要被告知去提问。

由此产生两个转变，分别对应本章的两半。

• 需求变成智能体消费的工件。它必须完整到可以实现、具体到可以核验。为此值得花多少时间，取决于改动的大小。
• 设计决策变成上下文，而不是委派。决策仍由架构师做出。变化在于决策记录在哪里：记录在智能体每次运行都会读到的地方。Anthropic 的 Claude Code 指南把"项目特有的架构决策"列入指令文件应当包含的内容，把"逐文件的代码库说明"列入应当省略的内容（厂商指南，截至 2026 年 10 月）。

开发者在这一阶段对 AI 心存戒备。在 Stack Overflow 2025 年调查中，69.2% 的受访者表示"不打算"在项目规划中使用 AI，而写代码一项只有 28.9%（调查）。但用量仍在上升。在 Anthropic 内部，2025 年 2 月到 8 月间，设计与规划在 Claude Code 使用中的占比从 1.0% 升到 9.9%（Anthropic，T3，由厂商对自家产品的 20 万份会话记录分类得出）。"决策"会不会成为核验之后的下一个瓶颈，是一个有理据的预期，而不是一项发现（瓶颈下一步去哪里）；本章不打算回答它。

本阶段的阶梯

成熟度模型为本章保留两行，需求和设计，因为二者爬升的方式不同。下面的标准与那里相同；这里每张表之后都会说明证据意味着什么。级别指的是在 AI 实际持有的权限下，人评审什么；并且按任务类型打分（规则）。

需求

这几行意味着什么。从 L1 到 L2，并不是"AI 起草得更好"，而是作者身份的变化加上一道新关卡：整份规格由智能体写出，规格放在负责实现的智能体会读到的地方，开始编码前由一位具名的人批准。如果拿不出该任务类型每一份规格的批准记录，团队就仍在 L1，只是多了些文书工作。

L3 有机制，但没有记录：Kiro 可以关掉关卡生成规格，却没有人公布这样做对缺陷率或返工率有什么影响。所以 L3 的标准刻意收窄，只限常规入站事项，不含功能需求，而且判据原则依然适用。对一份缺陷报告来说，最自然的检查是一个在修复前会失败的复现测试。这种搭配是本书的提议，不是有文档记载的实践。

L4 这一行刻意很小。伯克利 RDI 小组描述了一个"需求自主"（Demand Autonomy）级别，在这一级 AI"决定应该构建什么"，并指出相应的评估基础设施"几乎不存在"（Berkeley RDI，2026 年 7 月，立场文章，无数据）。本书不把它放进网格：决定做什么是产品决策，必须有可问责的负责人。唯一的 L4 候选是工单队列上的事务性工作，而它也没有公布过精度数据。

设计

这几行意味着什么。设计是本书所有阶段里证据最薄的，而这些空白都指向同一个方向。实验室研究说明 LLM 能起草一份像样的 ADR，却没有说明它能在仓库之外的约束下做出好的选择。生产环境中的机器人从另一面印证了这一点：Uber 的 uReview 文章写明该工具"目前只能访问代码"，所以设计评审仍归人负责。

L3 这一格是空的，因为没有人公布过一个为智能体改动把关、并报告其拦截结果的架构适应度函数。这个想法有业界实践者背书：2026 年 4 月的 Thoughtworks 技术雷达把"架构适应度函数"列为应对所谓"代码库认知债"的手段之一，认知债指的是"系统的实现与团队对其如何运作、为何如此运作的共同理解之间日益扩大的差距"。建议不等于结果。

因此，设计停在 L1–L2 是一种选择，而不是爬不上去。真正有价值的工作在 L2 标准的后半句：一旦人做出决策，就把它记录在智能体会遵循的地方。

案例：一位实践者眼中的三款规格驱动工具

没有任何组织公布过规格驱动开发的对照研究。最有用的单一来源是定性的。2025 年 10 月，Thoughtworks 的 Birgitta Böckeler 在大小不同的任务上试用了 Kiro、Spec Kit 和 Tessl，并记录了经过。

描述规格深度的词汇。Böckeler 区分了使用规格的三种方式：

• 规格先行（spec-first）："先写出一份深思熟虑的规格，再把它用于当前任务的 AI 辅助开发流程。"
• 规格锚定（spec-anchored）："任务完成后仍保留规格，继续用于后续演进和维护"。
• 规格即源码（spec-as-source）："长期来看规格是主要的源文件，人只编辑规格，从不碰代码。"

她把 Spec Kit 和 Kiro 归为基本上是规格先行，而 Tessl 是"这三款工具中唯一明确追求规格锚定的"。这套分类对迁移很重要。规格先行是一种 L2 实践。规格即源码则主张人可以不再评审代码，这是关于编码阶段的 L3 或 L4 主张，至今没有公开证据。

大小问题。Böckeler 让 Kiro 修一个小缺陷时，"很快就发现这个流程就像用大锤砸核桃。"Spec Kit"对这个问题的规模来说用力过猛"。她的总体结论是：每款工具只提供一种固执己见的流程，而"两者都不适合大多数真实的编码问题。"她认为，一个有效的工具"至少要为不同大小和类型的改动，提供几种不同核心流程的灵活性。"

评审问题。在 L2，人必须评审这些工具产出的 markdown。Böckeler 写道："说实话，我宁愿评审代码，也不想看这么多 markdown 文件。"如果规格就是产品，那么没人读的规格就是没人评审的产品。

控制问题。在"虚假的控制感？"这一小节下，她写道："即便有了所有这些文件、模板、提示词、流程和检查清单，我还是经常看到智能体最终没有遵循全部指令。"规格是给智能体的指令，不是对它的检查。只有当某样东西拿规格去核验产出时，规格才约束得了产出。

她的结论与本章的论点一致："我非常怀疑大量的前期规格设计是个好主意，尤其是写得过于冗长的时候。"Thoughtworks 技术雷达在 2025 年 11 月把规格驱动开发放在"评估"环，而不是"试用"环。它说这些流程繁复且固执己见，指出效果随任务大小和类型而变，并质疑为 AI 手工编写规则会不会重蹈"苦涩的教训"（bitter lesson）的覆辙（实践者小组观点）。

现有的结果数据

Böckeler 的文章之后，有三项研究测量了一些东西。三项都很弱，应当放在一起读。

一项关联研究。EPIC 框架依据 ISO/IEC/IEEE 29148，为 114 个践行规格驱动开发的开源仓库的规格打分；这些仓库是按 Spec Kit 和 OpenSpec 的目录结构以及常见的规格文件名找到的。规格质量位于前三分之一的仓库，"把 11.8% 的提交用于修复缺陷，后三分之一则为 20.4%"。前者每千行代码的圈复杂度也低 15.4%。每千行缺陷数相差 5.1%，不显著。

作者自己说明了局限："在没有多变量控制或分层分析的情况下，项目特征和开发实践仍是潜在的混杂因素"。其中一个混杂因素在他们的数据里就看得见：前三分之一仓库的贡献者中位数是 12.5 人，后者是 3 人。资源更充足的项目可能出于同一个原因，既写出更好的规格，又修更少的缺陷。

一次无对照试点。一项单一组织的 Spec Kit 试点追踪了 14 名工程师（8 名中级、6 名高级；不含初级）在三个 Web 项目上的工作：两个月基线，再加两个月使用 Spec Kit。每月回退次数从 2–4 次降到 0–1 次，每个迭代的后期热修复从 3–5 次降到 1–2 次。每个功能的交付周期中位数从 8–12 个工作日变为 6–9 个工作日。编写规格和计划的开销是每个中等规模功能 45–90 分钟。

论文自己列出了缺口："缺少平行对照组"，以及"无法排除时间上的混杂因素（例如研究期间 AI 模型能力的提升）"。回退数据令人鼓舞。开销数据是最可迁移的结果，因为团队可以拿它对照自己的日程。

一项由 LLM 评判的实验。一项 Spec Kit Agents 研究在五个开源仓库的 32 个功能任务上运行了 128 次。LLM 评委按 1–5 分给质量打分：无规格 3.46，原版 Spec Kit 3.51，作者的增强版 3.66，而增强版把运行时间从 24.0 分钟拉长到 37.2 分钟。在原版与增强版产出的 60 次人工偏好投票中，33 次平局，19 次偏好原版 Spec Kit，8 次偏好增强版。

合起来读：更好的规格与更少的缺陷修复相伴，但未必是因果；一家组织的规格习惯与更少的回退相伴，代价是每个中等功能约一小时；原版工具本身几乎没有提高评判质量。关于 Kiro 和 Tessl，除了厂商材料之外没有任何公开结果。规格习惯有希望，规格工具未经证明。

设计这一半：人否决了什么

关于智能体设计的最佳生产数据，来自微软对 GitHub Copilot 编码智能体在 dotnet/runtime 中十个月使用记录里的关闭原因（主案例见案例研究）。在 253 个未合并即关闭的智能体 PR 中，16% 以"方案错误"、8% 以"设计被否决"关闭。在已合并的 PR 上，人类评审意见中只有 1.8%（92 条）涉及架构。

在范围明确的任务上，智能体很少在架构上出错到需要评审者评论的程度。一旦出错，整个 PR 就被丢弃：被关闭的 PR 中约四分之一败在设计上。按照 L2 的要求，是人把它们拦了下来。更省力的办法是在开工前就把设计交给智能体，而不是事后更用力地评审。

记录的另一面展示了无人把握设计时会发生什么。2025 年，研究人员扫描了应用生成器 Lovable 展示的 1,645 个应用，发现其中 170 个应用共有 303 个端点无需认证即可读取数据（CVE-2025-48757）。研究人员称，该平台的安全扫描只检查行级安全策略是否存在，不检查它是否生效。CVE 记录注明 Lovable 对此有异议，理由是客户应自行负责其应用的数据保护。2026 年初，Wiz 发现，创始人自称"没写过一行代码"的 Moltbook 因客户端密钥外露且没有行级安全，暴露了 150 万个 API 令牌和 35,000 个电子邮件地址。在 Wiz 联系后约三小时修复。Wiz 的诊断是：如今的 AI 工具"还不会代替开发者去推理安全态势或访问控制"。

两者都没有设计阶段，这正是要点：谁能读哪些行，被留给了生成器决定，而且没有人评审。安全架构是不能委派的那个设计决策。安全、权限与爆炸半径一章讨论这些案例所在的代码风险面。

算例：一个改动负担得起多少规格

以下是示意性算术，不指向任何组织，只使用唯一公开的开销数据。

Spec + plan overhead (Spec Kit pilot):     45-90 min per medium feature
Medium feature lead time (pilot, after):   6-9 working days = 48-72 h
  Overhead as share of lead time:          0.75 h / 72 h = 1.0%
                                           1.5 h / 48 h  = 3.1%
One-sentence change, done directly:        ~20 min (illustrative)
  Same overhead applied to it:             45-90 min = 2.3x-4.5x the change

对一个中等功能来说，一小时的规格工作在交付周期里只是零头，换来的是智能体和评审者都能据以核对的工件。对一行修复来说，同样的仪式要花掉改动本身数倍的时间：这就是 Böckeler 说的大锤，换算成了分钟。Anthropic 的指南用一句话划了线：计划"会增加开销"，所以"如果你能用一句话描述这个 diff，就跳过计划。"规格写多深是按任务调的旋钮，不是按团队定的政策。

迁移步骤

一次只爬一级，只针对一个具名任务类型，并在每一级记下证据。需求现在就可以爬到 L2；设计应当爬到 L2 就停下。第 14 章《90 天试点》建议把维护作为风险最低的第一个试点，所以本阶段应放在后面再爬。

L0 → L1：让 AI 起草，作者仍是人。

1. 允许 AI 起草用户故事、PRD 和 ADR 文本，并把遗留代码总结成规格草稿。凡是离开草稿阶段的工件，都由人改写并负责。
2. 用工具遥测而不是自我报告记录使用情况，以便知道它被用于哪些任务类型。
3. 如果还没有 ADR 日志，就建一个；下一级依赖成文的决策。

需求的 L1 → L2：一次访谈、一份规格、一个新会话。

1. 挑选一个具名的、反复出现的任务类型，比如"服务 X 中的中等功能"，而不是"所有需求"。
2. 先采用做法，再选工具。Anthropic 的版本是：对较大的功能，"在开始实现之前，让 Claude 访谈你并写出规格"，然后"开一个新会话来执行它"。任何智能体都能这样做；Spec Kit 和 Kiro 只是把同样的步骤打包了。
3. 使用固定的规格格式。最有用的规格"列出涉及的文件和接口，说明哪些不在范围内，并以一个证明功能可用的端到端验证步骤结尾"。再加上可测试形式的验收标准；EARS 是一种选择。附录 A《模板》提供了规格模板。
4. 在第一份规格之前，用书面形式定下大小规则：如果 diff 能用一句话描述，就不写规格。
5. 把规格放在仓库里、紧挨着代码，并在开始实现前为每份规格记录一位具名批准人。这份批准日志就是 L2 的证据。
6. 为智能体写的规格标注归属（标签、提交尾注或文件头信息），并追踪该任务类型的返工：实现开始后被修改的规格，以及以"方案错误"关闭的 PR。

设计的 L1 → L2：智能体提方案，人做决定，决定变成上下文。

1. 对涉及多个组件的改动，让智能体在计划模式或设计文件中提出备选方案。由人选择并写下理由。
2. 把每个被采纳的决策写成一份简短的 ADR，并把约束日常代码的那些决策放进智能体的指令文件。条目只写规则本身，理由链接到 ADR。本站对比了各种指令文件格式。
3. 凡是能机械检查的决策（依赖规则、分层边界、某个库的禁用），就在 CI 中用确定性检查来强制，而不是写成文字。编码一章深入讨论指令文件和钩子。
4. 记录智能体 PR 的关闭原因，包括"方案错误"和"设计被否决"，以便看出记录下来的决策是否传达到了智能体。

需求的 L2 → L3：只限常规入站事项，只在有核验器时。没有可以照搬的公开案例，所以这一级是本书的提议。

1. 只限一类常规入站事项，比如针对单个服务的缺陷报告。功能需求留在 L2。
2. 为这一类事项配一个智能体无法修改的核验器。对缺陷报告而言，就是一个在当前代码上会失败、且负责实现的智能体不得改动的复现测试（判据原则）。
3. 写下路由规则，把有歧义、涉及安全或跨团队的事项送给人，并在工具中强制执行。
4. 在称之为 L3 之前，用 90 天时间把生成工单的逃逸缺陷和返工，与人写工单的基线作比较。

设计超过 L2：不要。没有 L3 证据，也没有经过检验的核验器。如果你构建了架构适应度函数，就在 L2 把它们当作检查来运行，并公布它们拦下了什么。

护栏

本阶段的护栏保护三样东西：验收标准、不得重开的决策，以及智能体究竟可以决定什么的边界。

• 验收标准一经批准就冻结。负责实现的智能体可以提议修改规格，但不得编辑用来评判它的验收标准或验证步骤。按照判据原则，一份成功条件可被智能体改写的规格，算不上 L3 的规格。用代码所有权或钩子保护这些文件，而不是用一句请智能体别碰它们的话。
• 把强制性规则放进确定性检查。Anthropic 的指南自己就做了区分："与只是建议性的 CLAUDE.md 指令不同，钩子是确定性的，保证动作一定发生。"Böckeler 观察到智能体没有"遵循全部指令"，这就是原因。凡是必须成立的，都放进测试、lint 规则或钩子。
• 安全架构由人负责，并加以测试。谁能读哪些数据、密钥放在哪里、哪些端点需要认证：由一位具名的人决定，并由一个智能体无法修改的测试来检查。Lovable 的扫描器只检查策略是否存在，不检查它是否生效。要测试行为。安全、权限与爆炸半径一章规定了每个级别对应的权限边界。
• 指令文件要短，并由人来写。2026 年 4 月的 Thoughtworks 技术雷达把"智能体指令膨胀"放进"谨慎"环："指令越多，重要规则被忽略的可能性就越大"，而且"手写的版本往往比 LLM 生成的更有效"（观点）。记录下来的决策只有留存在智能体真正遵循的文件里才起作用；编码一章讨论关于指令文件的证据。
• 一旦没有人工关卡，就把入站文本视为不可信。在 L3，外部人员写的一份缺陷报告会成为智能体不经评审就据以行动的输入。这是一个提示词注入的攻击面，安全一章中 L3 的权限边界适用于此。

本站关于计划评审与编辑和上下文工程的笔记，介绍了如何评审计划以及哪些内容会进入智能体的上下文。

指标

要衡量的是规格习惯是否值回成本，以及记录下来的决策是否传达到了智能体。每个流动指标都要配一个稳定性指标，第 17 章《衡量成效与何时回退》为每个阶段给出了配对方法。

• 规格开销：每份规格花费的分钟数，按任务大小区分，并与同一任务类型的交付周期对照。唯一公开的参照是每个中等功能 45–90 分钟（T3）。如果小改动也承担这样的成本，说明大小规则没有起作用。
• 智能体 PR 的关闭原因：以"方案错误"或"设计被否决"关闭的比例。dotnet/runtime 的 16% 和 8% 是参照，不是目标。决策移入指令文件之后这一比例下降，就说明设计工作传达到了智能体。
• 开工后的规格变动：已批准的规格在实现中途被修改的频率。变动多，说明访谈漏掉了东西，或者大小规则把不该走规格流程的任务送了进去。
• 缺陷修复占比与早期回退：同一类型中写了规格与没写规格的工作相比，提交中缺陷修复所占的比例（EPIC 的指标），以及两周内被回退的代码行（试点的指标）。两者都是团队在版本控制里现成就有的稳定性指标。
• 规格评审时间：批准人在每份规格上花的时间。长规格的评审时间接近零，说明没人在读，也就是 5.3 中的评审问题。

不要统计写了多少份规格，也不要统计 AI 起草的规格占比。两者都是数量指标，不管规格好坏都会上升。

反模式

• 大锤。每个改动，无论多小，都走完整的需求、设计、任务流程。人们会绕开它，而这个流程在真正需要它的功能上也失去了公信力。解法是一条书面的大小规则。
• 没人读的规格。智能体写出好几页 markdown，批准人扫一眼就点了批准。这个阶段看起来是 L2，实际表现却是没有核验器的 L3。写短一点的规格，并记录谁读了什么。
• 把规格当控制手段。把一份详细的规格当作智能体一定会照做的保证。规格说明要造什么；测试、钩子和评审才决定它是否造对了。
• 生成出来的指令文件。让智能体自己写指令文件，然后每出一次错就加一条规则，直到记录下来的决策再也传达不到它。
• 委派出去的安全架构。因为应用"能跑"，就让生成器决定访问控制。Lovable 和 Moltbook 展示了这条路的终点。
• "AI 决定做什么"。把产品战略或用户反馈直接变成路线图条目，而没有可问责的负责人。没有任何证据支持这样做。
• 不可能完成的规格。验收标准自相矛盾或无法达到，又没有让智能体停下来提问的指示。智能体会一直追下去，有时长达数天，或者用走捷径的方式"满足"它。告诉它去提出澄清问题，并给它一个报告任务无法完成的途径。

本站的规格驱动的智能体开发手册介绍工具。关于 AI 原生 SDLC 工件链的文章追溯了规格如何成为之后每个阶段的输入，包括代码评审和测试，在那里规格中的验证步骤变成一项检查。