learnNote

主题

Harness Engineering 来了，SDD 还有意义吗？ ​

作者：何艺萍 | 来源：腾讯云开发者 | 日期：2026年3月31日

TL;DR（核心结论） ​

  • Harness Engineering 和 SDD 不是竞争关系，而是同一件事的两个层面。
  • 工程纪律没有消失，只是从「写好代码」转移到了「构建好让 Agent 工作的 scaffolding」。
  • Spec（写进仓库的意图、契约和规范）正是 scaffolding 的核心内容之一。
  • Harness 是放大器，Spec 是被放大的内容。 Harness 越强，Spec 的质量对最终结果的影响就越大。
  • SDD 是必须且重要的，不是因为 Harness 不够好，而是因为 Harness 把 Spec 的重要性放大了。

一、Harness 到底是什么 ​

1.1 Mitchell Hashimoto 的视角（个人实践） ​

Mitchell Hashimoto（HashiCorp 联合创始人、Terraform 缔造者）将 AI 采纳之旅分为六个阶段，第五阶段叫做「Engineer the Harness」，核心定义：

"每当你发现 Agent 犯了一个错误，你就花时间去工程化一个解决方案，让它再也不会犯同样的错。"

两类具体做法：

  1. 记录坏行为模式：在 AGENTS.md 里记录 Agent 的错误模式，防止重现
  2. 编写专用工具脚本：截图工具、过滤测试等，让 Agent 能自我验证

1.2 OpenAI 工程团队的视角（团队系统） ​

OpenAI 进行了一次大规模实验：5 个月，从空仓库开始，约 100 万行代码，1500 个 PR，全部由 Agent 生成。

Harness 的组成：

  • 结构化的 docs/ 目录
  • product-specs/（产品规格）
  • exec-plans/（执行计划）
  • design-docs/（设计文档）
  • 架构约束（自定义 linter + 结构测试）
  • 反馈回路（可观测性工具接入 Agent 运行时）
  • 定期运行的「垃圾回收」Agent 扫描架构漂移

核心结论：Harness 是让 Agent 可靠工作的系统，而不只是模型本身。

二、OpenAI 的核心观点 ​

OpenAI 的关键论述：

「构建软件仍然需要纪律，但纪律更多地体现在支撑结构（scaffolding）上，而不是代码上。」

「我们当前最棘手的挑战集中在设计环境、反馈回路和控制系统方面。」

工程纪律的转移：

以前现在
好好写代码构建好让 Agent 工作的环境
认真做 Code Review设计文档、约束、反馈回路
遵守编码规范把意图和规范写进仓库

核心发现：Agent 看不到的，就不存在。存储在 Google Docs、聊天记录或人们头脑中的知识都无法被系统访问；代码仓库本地的、已版本化的工件，才是 Agent 所能看到的全部。

三、Spec 在 Harness 里的三个角色 ​

3.1 角色一：Agent 推理的地图 ​

  • Spec 是一张地图，而不是一本百科全书
  • 系统级 Spec → 告诉 Agent 系统有哪些服务、各自负责什么、边界在哪里
  • 服务级 Spec → 告诉 Agent 服务内部的能力、接口语义、行为规则
  • 渐进式披露：Agent 从高层概览出发，按需深入到具体节点

3.2 角色二：约束生效的语义基础 ​

  • Linter 能检查格式层面的约束（层间依赖、文件大小、命名规范）
  • 但 Linter 检查不了语义：错误码的跨服务含义、接口字段的业务含义、状态流转规则
  • Spec 的契约层和行为规格层承载了 "linter 管不到、但 Agent 必须知道" 的语义约定

实践案例：服务 A 定义了错误码含义，服务 B 的 Agent 不知道此跨服务语义，沉默地猜测了处理方式。补充了完整的错误码契约后，同一个 Agent 生成的实现通过了验证——不是换了更强的模型，而是补上了缺失的语义定义。

3.3 角色三：反馈回路的正确性判据 ​

  • Harness 飞轮：Agent 犯错 → 诊断原因 → 工程化修复 → Agent 不再重犯
  • 飞轮的前提：你能知道 Agent 犯错了，这需要「正确性判据」
  • Spec 的验收标准层（WHEN/THEN Scenario）提供了这个判据
  • 有了判据，反馈回路才能闭合；没有判据，「发现错误」只能靠运气

四、规范驱动（SDD）AI Coding：把 Harness 里的 Spec 做对 ​

4.1 Spec 决定 Agent 能做对什么 ​

Spec 的价值在三个层次上递进：

单 capability 内做对（WHEN/THEN Scenario 约束行为边界）
    → 多服务联动做对（系统级契约让各服务 Agent 看到同一份语义）
        → 改了还对（验证规范提供持续的回归基线）

4.2 Spec 消灭的是返工，不只是提速 ​

  • 规范驱动方法优化的不是「写出第一版代码的速度」，而是「正确交付的总成本」
  • 没有 Spec 时的隐性成本：跨服务歧义等联调暴露、边界条件上线后才发现、每次新 AI 会话都要从零重建上下文
  • 前移写进 Spec 的成本，消灭的是后移返工和猜测的成本

4.3 知识资产化：Spec 是可继承的工程记忆 ​

  • AI Coding 加速了知识随人和会话流失的问题
  • Spec 把知识从「人脑 + 对话历史」转化为「仓库里版本化的结构化资产」
    • 系统级 Spec → 记录跨服务约定
    • 服务级 Spec → 记录各服务语义
    • 决策记录层 → 记录「为什么选了这个方案、排除了什么」

4.4 人才能力迁移：从写代码到设计环境 ​

  • 写 Spec 的本质：把模糊意图转化为精确、结构化、可被 Agent 消费的定义
  • 这一能力正变得越来越重要
  • SDD 的 Spec 编写和审查流程，本身就是对这个能力的训练

4.5 一套典型的规范驱动方案 ​

OpenAI 的实践参照：

文档类型职责
product-specs/产品规格，定义系统要做什么
design-docs/设计文档，描述技术方案
exec-plans/执行计划，拆解具体任务

人类只做两件事：

  1. 提供原始意图（口述需求、架构决策）
  2. 审查 AI 生成的 Spec 和代码

Spec 的生成由 AI 主导，基于引导式对话从人类的非结构化输入中提取、精化、结构化。

五、Harness Engineering 的四大启示 ​

5.1 启示一：审查的重心应在 Spec，而不是代码 ​

  • Spec Review 是上游控制：一个 Scenario 被遗漏，Agent 会在整个实现过程中持续放大偏差
  • Code Review 是反馈入口：发现 Spec 没有定义清楚的地方，并把它补回 Spec
  • 先把 Spec Review 做好，Code Review 的压力会自然减轻

5.2 启示二：「大型 AGENTS.md」是一个陷阱 ​

OpenAI 踩过的坑：大型 AGENTS.md 有四个系统性问题——挤掉有效上下文、过多导致失效、立即腐烂、难以核实。

解法：

  • AGENTS.md 应该是目录，而不是百科全书（约 100 行，主要用来导航）
  • 执行约束（"不要使用这个 API"、"文件大小不超过 X 行"）和语义约束（字段含义、服务边界、错误码处理）要分开管理

5.3 启示三：Spec 漂移是必然的，需要主动检测机制 ​

  • 代码漂移能在运行时感知（测试失败、类型报错），但 Spec 漂移是沉默的
  • Active 状态的 Spec 描述着一个已经演进的系统，不会报错，只会沉默地误导下一个 Agent
  • 建议：
    • 设计 Spec-Code 一致性检测机制
    • 工程规范兜底：Spec 修改和代码修改必须在同一个 PR 里提交，Spec 先于代码合入
    • 定期检测 Spec 描述与代码现状是否一致，对漂移条目自动发起更新提案

5.4 启示四：追问「AI 还缺什么」，而不是「人类再努力一点」 ​

「当事情进行不顺利时，解决方案基本上再也不会是'再努力一点'。取得进展的唯一方式是让 Codex 来完成工作，而人类工程师则追问：'究竟还需要什么样的能力？'」

  • 遇到 Bug 或阻塞时，首要追问不是「怎么让人做对」，而是「AI 还缺什么」
  • 缺的可能是 Spec 里的一个 Scenario、一个自我验证的工具、或一层可观测性数据
  • 下一个值得投入的方向：让 AI 也能读到运行时的反馈信号（日志、错误、验证结果）

六、结语：Harness 越强，Spec 越重要 ​

Harness 是放大器。 Spec 写得好，Harness 把它放大为可靠的、一致的、可验证的输出。Spec 写得差或根本没有，Harness 把 Agent 的猜测放大为高效率地产出错误。

引擎越强，导航越重要。 高速公路的护栏比自行车道更必要，不是因为车更危险，而是因为速度更快、后果更严重。

构建 SDD 体系，不是在做一件和 Harness Engineering 平行的事，而是在回答 Harness Engineering 最核心的追问：

究竟需要什么样的 scaffolding，才能让 Agent 把我们想要的东西，既清晰可读又可强制执行地做出来？

  • Spec 是其中举足轻重的一环。
  • SDD 是把这个答案做工程化的方法。

参考来源 ​

  1. Mitchell Hashimoto 《My AI Adoption Journey》，2026年2月
    https://mitchellh.com/writing/my-ai-adoption-journey#step-5-engineer-the-harness
  2. OpenAI 工程团队 《Harness Engineering》官方博客文章，2026年2月
    https://openai.com/index/harness-engineering/