Harness Engineering 与 Spec-First：有什么区别？

这两套实践都是为了让问题在进入生产环境之前被发现。Harness engineering 构建运行和验证代码的基础设施；spec-first 则在你动笔写代码之前就定义什么叫“正确”。它们作用在交付生命周期的不同节点，防止的是不同类别的失败——所以把两者混为一谈的团队，总会在其中一侧留下漏洞。

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

概念定义

Harness Engineering 是将测试执行基础设施作为一等工程关切来建设的实践。测试 Harness 是围绕被测系统的脚手架：fixture 加载器、mock 服务器、环境初始化脚本、集成测试包装器、契约测试运行器。践行 Harness Engineering 的团队会在生产代码之前或同步进行这项基础设施投入，用对待系统本身同样的设计纪律来对待它。

Spec-First 开发是在实现开始之前先写行为规格文档的实践。规格定义系统必须做什么——以验收标准、边缘情况、错误路径和明确的非目标的形式——让每位工程师、QA 工程师和产品经理在第一行生产代码落地之前就共享同一个"正确"的定义。

两者都旨在弥合"预期"与"实际构建"之间的差距，但作用在不同的层面：规格处理意图问题，Harness 处理验证问题。只做好一个而忽视另一个，会留下一个可预测的具体漏洞。

各自在交付生命周期中介入的时机

时机差异是实践中最重要的区别。Spec-First 在上游介入——规格评审发生在冲刺开始之前、IDE 打开之前。它的产出是一份文档，回答：需要什么行为，什么不在范围内，QA 需要验证什么。如果一个决策在规格中缺失，它就会在实现期间被做出——悄无声息，没有任何评审记录。

Harness Engineering 是并行的。Harness 与生产代码同步构建，或在上一个冲刺中提前构建。它的产出是基础设施：运行测试的环境、填充数据的 fixture、替代不可用依赖的 mock、捕捉破坏性 API 变更的契约测试套件。如果 Harness 缺失或不可靠，本应捕捉回归的测试要么根本不运行，要么运行结果不稳定。

交付生命周期——各自介入的时机：

  PRD / 需求发现
       ↓
  [SPEC-FIRST] ← 规格在此撰写并评审
       ↓
  实现开始
       ↓
  [HARNESS ENGINEERING] ← Harness 在此与实现并行构建
       ↓
  QA / 验证
       ↓
  发布

跳过 Spec-First 的团队带着模糊的需求进入实现。跳过 Harness Engineering 的团队带着缓慢、不稳定或根本不存在的测试进入 QA。两种失败都代价高昂，但它们不是同一种失败。

Harness Engineering 产出什么

一个成熟的后端服务测试 Harness 通常包含以下组件，每个组件解决一个特定的验证问题，这些问题是临时拼凑的测试基础设施在规模化时无法可靠解决的。

• Fixture 系统：为测试建立已知起始状态的确定性种子数据。没有 fixture，测试会共享状态，根据运行顺序产生不一致的结果。
• Mock 服务器：外部依赖的本地替代（支付网关、邮件服务、第三方 API），行为可预测，可以被编程模拟失败场景——超时、500 错误、格式错误的响应。
• 契约测试运行器：自动验证服务的 API 契约是否符合消费者的预期。在部署前捕捉破坏性变更，而不是等消费者触发告警之后。
• 环境初始化脚本：本地和 CI 测试环境的脚本化建立与清理——数据库 schema 迁移、服务依赖、特性开关默认值。消除"在我本地好好的"类型的失败。
• 测试数据工厂：以编程方式构建具有合理默认值（可按测试覆盖）的有效测试对象。减少测试的样板代码，让每个测试用例的意图一目了然。

构建这套基础设施需要时间——对于从零开始的服务，通常需要一到两个冲刺。不做这项投入的团队最终会在每个测试文件里重复相同的初始化代码，积累让测试套件越来越难维护、越来越慢的技术债。

Spec-First 产出什么

Spec-First 工作流在实现开始之前产出一份文档。最小可行规格包含：一句话目标、明确的非目标、可测试形式的验收标准、已知边缘情况、依赖项和发布计划。每个部分都解决一类歧义，而这些歧义如果放到实现期间才去解决，代价更高，且不留记录。

Spec-First 产出——最小可行规格：

  目标：[一句话——对用户产生什么变化]
  非目标：[本次变更明确不做的事]

  验收标准：
  - Given [状态]
    When [动作]
    Then [可观察的结果]

  边缘情况：
  - [场景] → [预期行为]

  依赖项：[外部服务、特性开关、其他团队]
  发布计划：[谁先获得、成功信号、回滚定义]

规格不描述如何构建系统，它描述系统必须做什么、以及如何判断它做到了。这个区别很重要：Harness 可以验证代码做了它所做的事——但只有规格才能验证它所做的事是实际需要的。

各自防止的失败类型

它们防止的失败类型截然不同，互不重叠。

Spec-First 防止构建错误的东西。规格缺失时，实现决策由当时写代码的工程师做出。这些选择基于局部知识，对团队其他人不可见。边缘情况的处理方式是否一致，取决于哪位工程师碰巧遇到了它。非目标悄悄扩张。"支付网关超时时应该怎么处理？"这个问题往好了说出现在 PR 评论里，往坏了说根本没有出现。

Harness Engineering 防止无法验证正确的东西。Harness 缺失时，QA 依靠手动测试、运行缓慢且频繁失败的端到端测试，或者什么都没有。回归被用户发现，而不是被测试发现。契约变更在消费者被影响之后才被注意到。性能特征变化无人察觉，直到生产告警响起。

失败模式对比：

  没有 Spec-First：
  - 工程师构建了他们对工单的理解，不一定是需求方的理解
  - 边缘情况在代码库各处被不一致地处理
  - 非目标在实现期间悄然扩张
  - QA 在构建完成后才发现歧义
  - 回滚行为直到生产需要时才被定义

  没有 Harness Engineering：
  - 回归由用户发现，而不是测试
  - 破坏性 API 变更在到达消费者之前未被检测到
  - 随着代码库增长，测试可靠性下降
  - CI 运行变得冗长、不稳定，最终被人绕过
  - 性能和契约变化无人监控

只有其中一个时的具体漏洞

有完整规格但没有 Harness 的团队，需求清晰，但没有可靠的验证方式。验收标准是正确的，但测试套件无法系统性地执行它们。QA 从规格中编写测试用例——这是正确的输入——但在一个依赖共享状态和真实外部服务的脆弱环境中手动运行。规格是值得写的，验证基础设施却无法承载它。

有完整 Harness 但没有规格的团队，有出色的验证基础设施，却没有明确的目标。Harness 快速、可靠、全面，在每次提交时验证系统做了它所做的事——一致地、可重复地。但它所做的事不一定是需求所要求的。测试通过了，功能仍然以错误的行为发布，因为被测试的行为来自实现本身，而不是来自关于实现应该做什么的先验规格。

第一种情况的漏洞出现在 QA 阶段——手动测试跟不上交付节奏。第二种情况的漏洞出现在生产环境——"但所有测试都通过了"无法解释为什么账单逻辑对边缘情况 X 的处理方式是没人商定过的。

两者如何互相强化

当两种实践同时存在时，它们以一种特定的方式弥补彼此的不足。

规格为 Harness 提供目标。以 Given/When/Then 形式写成的验收标准直接映射到测试用例——Given 子句变成 fixture 的建立，When 子句变成测试动作，Then 子句变成断言。有了规格，QA 工程师可以在实现完成之前就开始写测试用例，而 Harness 基础设施已经就位可以运行它们。规格告诉 Harness 要验证什么，Harness 告诉 QA 规格是否被满足。

Harness 为规格提供反馈。当规格中的某个验收标准无法用现有 Harness 表达为测试——因为 Harness 无法模拟所需的前置条件，或者可观察的结果需要访问一个未被 mock 的系统——这是一个信号：要么规格需要重写，要么 Harness 需要扩展。这种摩擦是真实的信息：它意味着该标准是针对一个与系统实际可测试性不匹配的心智模型写成的。

互相强化的闭环：

  规格定义：Given [状态] When [动作] Then [结果]
       ↓
  Harness 提供：[状态] 的 fixture、[动作] 的 mock、[结果] 的断言
       ↓
  测试运行并通过 → 实现满足规格
  测试失败 → 实现偏离规格 → 合并前修复

先采纳哪个

如果团队两者都没有，Spec-First 是成本更低的第一步投入。一份一页规格只需一到三小时来写和评审，不需要工具、基础设施或新的依赖项。它在第一个冲刺就产生立竿见影的回报：更少的实现中途澄清需求的问题，QA 可以在构建完成前就写测试用例，以及一份在实现开始前记录了什么被决定的文档。

Harness Engineering 是更大的投入。为现有服务搭建 fixture 系统、mock 服务器层和契约测试运行器通常需要一个完整的冲刺。对于从零开始的服务，它与功能开发争抢工程时间。回报也更大——成熟的 Harness 会大幅降低持续测试的成本——但前期投入是真实的，应该作为一个明确的冲刺目标来规划，而不是让它以临时方式自然积累。

实践建议：现在采纳 Spec-First，无需任何工具变更。当团队的测试可靠性成为可见的瓶颈时，将 Harness Engineering 规划为专项冲刺投入。两种实践互不依赖就能各自产生价值——它们独立有效，组合在一起效果更好。

一个框架总结两者

Spec-First 回答：系统需要做什么，我们怎么知道它做到了？Harness Engineering 回答：我们如何可靠地、重复地验证系统做了我们说它会做的事？这是两个相邻但不同的问题，有不同的负责人和不同的成本。规格由理解需求的工程师或技术负责人撰写。Harness 由理解代码库测试基础设施需求的工程师构建。

同时拥有两者的团队能做到单独任何一个都做不到的事：交付一个在编码前被清晰规格化、按规格实现、并在每次提交时自动验证的功能。这才是功能"完成"的真正定义——不是"已合并"或"已部署"，而是对一份先前关于正确是什么意思的书面约定，得到了确认。