规格评审反模式：何时跳过规格、哪些内容不该写进规格

今年我观察了三个采用 Spec-First 开发的团队。其中两个在六周内就精疲力竭了。不是因为这个实践本身有问题，而是因为他们给所有改动都写了规格。改两行配置？写规格。一个已经定位到的 Bug？写规格。凌晨两点的紧急修复？最好先写个规格。结果不出意料：工程师彻底放弃了写规格，因为这个流程和官僚主义没有区别。Spec-First 是有效的，但前提是你知道什么时候该跳过它。

发布于 2026-04-01 · ✓ 已更新 2026-05-06 · 阅读约 9 分钟 · 作者：Daniel Marsh · 审校：编辑政策

过度规格化陷阱

Spec-First 在组织内消亡的最常见方式不是被拒绝，而是被过度采纳。团队读了关于 Spec-First 开发的文章，兴奋不已，于是决定每项改动在写代码之前都必须有书面规格。不到一个月，规格积压比功能积压还长。工程师花在写规格和评审规格上的时间比写代码还多。本该减少无效工作的实践本身变成了无效工作。

原因在于 Spec-First 最初的宣传很有说服力：先思考再动手、尽早发现设计错误、在代码评审之前对齐团队。这些都没错。但宣传中很少提到边界。没有人说"只对复杂、高风险或新颖的改动写规格，其余的跳过"。相反，隐含的信息是"更多规格等于更多纪律"，而纪律总是被框定为好事。

不是的。不加判断地统一施加纪律，不过是为了流程而流程。为修改一行环境变量写规格，其撰写、评审和维护的成本高于改动本身。为修复一个已定位的空指针异常写规格，不会增加 Bug 报告和修复本身未包含的信息。这些规格不是在防止错误，而是在阻止推进。

能够长期坚持 Spec-First 的团队，都把它当作有特定适用场景的工具，而不是没有例外的规则。他们知道什么时候该用，更重要的是，知道什么时候不该用。

规格成为负担的时候

有些类型的工作，写规格确实是适得其反的。认清这一点不是偷懒，而是区分一个实践能否持续的关键。

50 行以下的 Bug 修复。如果 Bug 已经被充分理解，根因已经确认，修复量很小，那么规格不会带来任何增量信息。Bug 报告本身就是规格，修复就是实现。写一份正式文档说"我们将修复 UserService.java 第 47 行的空指针"，然后等两个评审者批准才能动手写那一行修复代码——这是表演，不是工程。直接修复，把解释写在 PR 描述里。

已充分理解的模式。如果你的团队本季度已经构建了十二个 REST 端点，第十三个遵循完全相同的模式，那么为"新增 GET /api/widgets 端点"写规格并不能发现设计问题。没有设计决策需要做，模式已经建立，约定已经文档化。写代码，遵循模式，继续前进。

紧急修复。生产环境挂了，用户受到影响，修复方案已知。在部署修复之前写规格不是负责任的工程实践，而是流程崇拜。先修复生产问题，之后再写复盘报告。如果事故暴露了需要规格来解决的设计缺口，那就在火扑灭之后再写规格，而不是在楼还在烧的时候。

无行为变更的重构。重命名模块、提取辅助函数、将文件移至不同的目录结构。如果外部行为不变、风险低、且动机在 PR diff 中一目了然，规格就是负担。代码评审本身就够了。

配置变更。Feature flag、环境变量、阈值调整、依赖版本升级。这些是运维变更，不是设计决策。除非配置变更有不明显的下游影响，否则在提交信息中记录即可，跳过规格。

五种常见的规格评审反模式

即使在确实需要规格的场景下，评审流程本身也可能成为瓶颈。以下是我在采用了技术设计评审的团队中反复看到的五种反模式。

1. 纠结排版而忽略范围。评审者花二十分钟建议规格用项目符号代替编号列表，或者第三节加个图会更好看。与此同时，范围部分有一个歧义，如果没人发现，会导致两周的返工。排版反馈容易给，范围反馈难给。评审者默认做容易的事。

2. 把实现细节写进规格。规格写着"使用 HashMap 作为查找缓存，TTL 设为 300 秒，基于 LRU 策略淘汰"。这不是规格，这是用英语写的代码。规格应该定义问题、约束和架构层面的方案。写代码的工程师应该选择数据结构。规定实现细节的规格削弱了执行者的自主权，而且往往锁定了过早的决策。

3. 对琐碎改动也要求规格。前面已经讲过，但它值得作为一个独立的反模式单独列出，因为它经常通过工具强制执行。团队创建 Jira 工作流，没有关联规格文档就阻止 PR。结果就是工程师写一段什么有用信息都没有的规格，只为通过门禁。规格要求变成了打勾，而打勾式流程训练人们只做通过所需的最低限度。

4. 评审委员会造成延迟。规格周一写好。评审会议排到周四，因为那是六位评审者都有空的时间。反馈在周五到达。修改在下周一完成。第二轮评审在再下一个周四。两周过去了，一行代码都没写。而那个功能本来只需要三天就能做完。评审委员会适用于重大架构决策。对于典型的功能规格，两个评审者加上 48 小时 SLA 就够了。

5. 先写代码后补规格。这是最隐蔽的反模式，因为它看起来像是合规。功能已经开发完了，工程师写一份规格来匹配已完成的实现，提交评审，团队打上已完成的勾。这份规格没有指导任何决策，没有发现任何错误。它是一份事后合理化文档，披着规划文档的外衣。如果规格不是在代码之前写的，那它就不是规格，而是文档——应该如实标注。

车棚效应：规格评审的头号杀手

车棚效应值得深入讨论，因为它是规格评审失败的最常见原因。这个术语源自帕金森的观察：委员会在自行车棚涂什么颜色上花的时间，比核反应堆的设计还多，因为每个人都觉得自己有资格对油漆颜色发表意见。

在规格评审中，车棚效应有具体的表现形式。评审者争论命名约定（"这个服务应该叫 UserProfileService 还是 ProfileService？"），同时忽略规格没有定义当该服务不可用时该怎么办的事实。他们争论 API 对空结果集应该返回 404 还是 204，而下游依赖的故障模式完全没有被定义。他们建议重新组织规格文档本身，而技术内容无人审查。

解决方法是结构性的，而不是文化性的。告诉大家"关注重要的事"不管用，因为每个人都认为自己已经在关注重要的事了。相反，给评审者一份清单，强制先关注高影响领域：范围清晰度、故障模式、非目标、回滚计划，然后再开放讨论。如果评审者没有处理前四项，排版建议可以等等。这不是理论。采用结构化评审格式的团队一致报告评审周期更短、实施后意外更少。我在设计评审指南中详细介绍了这一点。

轻量级规格替代方案

并非每个需要前期思考的改动都需要一份完整规格。在"不写规格"和"三页带图的设计文档"之间存在中间地带，但大多数团队永远找不到它，因为他们把规格当作非此即彼的选择。

一页纸。一页纸包含三个部分：问题、方案、风险。不需要正式模板，不需要审批流程。只需要足够的书面思考来确认工程师在写代码之前考虑了方案。一页纸适合中等复杂度的改动——太大了不能直接做，但太小了不值得写完整规格。

决策日志。对于涉及有意义的技术选择但不需要完整设计的改动，三段式决策日志记录做了什么、为什么、以及考虑了哪些替代方案。比 ADR 轻，比提交信息重。放在 PR 描述或团队 Wiki 页面中。

Slack 讨论摘要。许多技术决策发生在 Slack 中。问题是 Slack 对话是临时性的，实际上无法有效搜索。一个轻量替代规格的做法是将 Slack 讨论总结成文档，记录决策和推理过程。这只需要五分钟，却能保存否则会蒸发的上下文。

PR 描述即规格。对于代码本身就是方案最清晰表达的改动，详细的 PR 描述可以充当规格。这在评审者能通过阅读 diff 评估方案时有效。PR 描述解释"为什么"，diff 展示"做什么"。两者共同提供有意义评审所需的足够上下文。关键限制：这只适用于实现足够直观、代码本身就能说明问题的改动。

决策框架：写规格、做探针、还是直接开发

下面是我提供给那些纠结于何时该写规格的团队的流程图。它刻意做得很简单。如果你用来决定是否写规格的框架本身复杂到需要一份规格，那你已经输了。

  新改动到来
       |
       v
  是否复杂、高风险或新颖？
      / \
    是    否
     |      \
     v       v
  写规格   代码量 > 50 行？
     |       / \
     v      是   否
  一页纸    |     \
  能说清？  v      v
   / \   一页纸   直接
  是   否  或 PR   开发
  |     \  描述
  v      v
直接   先做
开发   探针
      

复杂指涉及多个组件、服务或团队。高风险指方向错误的纠错成本高昂。新颖指团队中没人做过类似的事。如果这三者都不适用，你大概率不需要规格。

"先做探针"分支适用于你知道改动很重要，但对问题本身理解不够深的情况。在不理解问题时写规格，产出的规格是错的。不如做一个有时间限制的探针，学到该学的，然后再决定剩余工作是否需要规格，还是已经理解到足以直接开发。

"> 50 行"的阈值是一个启发式标准，不是硬性规则。有些 30 行的改动比某些 200 行的改动风险更高。关键是有一个粗略的过滤器，捕获中等规模的工作，将其导向轻量替代方案，而不是完整规格或完全没有文档。

Spec-First 团队如何保持速度

我最常听到的反对意见是规格会拖慢团队。对于过度规格化的团队来说，确实如此。但那些有效采纳 Spec-First 的团队实际上比之前交付更快，因为他们花在规格上的时间少于过去花在返工、对齐不一致、以及做错东西上的时间。

模式是这样的。采用 Spec-First 之前，一个功能需要五天开发加两天返工（因为代码评审暴露了设计问题）。采用 Spec-First 之后，同一个功能需要一天写规格、一天评审、四天开发且没有返工。总的端到端时间差不多，但产出质量更高，工程师的挫败感更低。没有人喜欢因为评审者想要不同方案而扔掉两天的工作成果。

关键在于规格不是叠加在现有流程之上的额外步骤。它替代了隐式的设计步骤——那个步骤原本就存在，只是做得很糟。在没有规格之前，工程师在写代码时做设计决策，在代码评审时发现问题，在事后修复。规格把设计步骤前移到了修改成本更低的阶段。改一段文字比改一个 Pull Request 容易得多。

能够保持速度的 Spec-First 团队有几个共同习惯。他们为规格评审设定 48 小时 SLA。他们将评审者限制在两到三人，而不是整个团队。他们使用填写只需十五分钟而不是两小时的模板。他们跳过小改动的规格时不会有负罪感。他们衡量的指标是从想法到上线的周期时间，而不是写了多少份规格。如果规格对某个改动没有缩短周期时间，那它就是负担，他们会跳过。

这个实践应该让你更快。如果它让你变慢了，要么是过度规格化，要么是评审不到位，要么是用在了错误的改动上。上面的框架帮你判断是哪一种。

示例：什么时候可以合理跳过规格

跳过规格不是问题，前提是团队能说清楚风险为什么低。“这个很小”不是理由。“这是静态文案修正，不涉及状态、API、权限、发布、测试矩阵”才是理由。

可以跳过：
- 把按钮文案从“保存”改成“保存更改”
- 不改变 API 行为
- 不改变数据写入
- 由现有视觉评审覆盖

不要跳过：
- 改变按钮何时可点击
- 改变会映射到服务端错误的校验文案
- 改变谁能看到这个操作

重点不是强制所有改动都写规格，而是让“跳过”这个决定本身足够明确，能被别人评审。