推荐语

Harness Engineering 与 SDD 并非对立，而是互补关系，Spec 体系在 AI 工程中扮演着关键角色。

核心内容：
1. Harness Engineering 的概念解析与行业动态
2. SDD（规范驱动开发）的核心价值与实践方法
3. 两种方法论如何协同提升 AI 工程效率

杨芳贤

53AI创始人/腾讯云(TVP)最具价值专家

最近，「Harness Engineering」这个概念在 AI 工程圈里热了起来——Mitchell Hashimoto（HashiCorp 联合创始人、Terraform 缔造者）和 OpenAI 工程团队相继发文，描述了一套「让 Agent 可靠工作」的工程方法论。与此同时，笔者也在实践一套规范驱动（SDD）的 AI Coding 工作流，核心投入在于构建一套完整的 Spec 体系——把系统的意图、契约、行为规范结构化地写进仓库，让 Agent 有据可查。

注：本文中的“规范驱动 AI Coding”方法，笔者简称为 SDD（Spec-Driven Development），这是特指通过结构化规范驱动 Agent 编程的方法论。SDD 作为一个特定的概念和实践框架，与传统软件工程中的其他方法论有所区别。

这自然引出一个真实的疑问：在 AI 技术日新月异、Harness Engineering 概念刚刚成形的今天，花费精力去构建这套 Spec 体系，是否有意义？Harness 的工具和环境体系不断完善，Spec 是否会在不久的将来变得多余、甚至过时？

在仔细阅读了 OpenAI 和 Mitchell Hashimoto 的一手文章之后，结合自己的 SDD 实践，我对基于 SDD 的 AI Coding 工作流进行了一些思考，整理成这篇文章。

TL;DR

- Harness Engineering 和 SDD 不是竞争关系，而是同一件事的两个层面。

- OpenAI 的文章说得很清楚：工程纪律没有消失，只是从「写好代码」转移到了「构建好让 Agent 工作的 scaffolding」。而 Spec——写进仓库的意图、契约和规范——正是这个 scaffolding 的核心内容之一。Harness 越强，执行能力越强，Spec 的质量对最终结果的影响就越大。Harness 是放大器，Spec 是被放大的内容。**

- SDD是必须而且重要的，不是因为 Harness 不够好，而是因为 Harness 把 Spec 的重要性放大了。

在回答「SDD 还有没有意义」之前，先把 Harness 说清楚——因为很多讨论里这个词被用得很模糊。

Mitchell Hashimoto 在他 2026 年 2 月的博客里，把自己的 AI 采纳之旅分为六个阶段，第五阶段叫做「Engineer the Harness」。他的定义只有一句话：

"It is the idea that anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again."

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

他提到了两类具体做法：一是在 AGENTS.md 里记录 Agent 的坏行为模式，防止重现（他以 Ghostty 项目的 AGENTS.md 为例，说「那个文件里的每一行，都来自一次真实的坏行为，写进去之后几乎全部得到了解决」）；二是编写专用工具脚本（截图工具、过滤测试等），让 Agent 有办法验证自己的工作是否做对了。

Mitchell 说的 Harness，是从工程师个人实践的角度——当 Agent 出错，不要反复纠正，而是工程化地消除这个错误的可能性。

OpenAI 工程团队在官方博客的《Harness Engineering》文章中（2026 年 2 月），从团队系统的层面描述了一次更大规模的实验：5 个月，从空仓库开始，约 100 万行代码，1500 个 PR，全部由 Agent 生成。这里的"全部由 Agent 生成"指的是代码层面——人类工程师的工作转移到了定义产品规格、设计约束、搭建反馈系统等"支撑结构"的工作上。

他们的 Harness 是什么样的？是一套完整的环境体系：结构化的 docs/ 目录、product-specs/（产品规格）、exec-plans/（执行计划）、design-docs/（设计文档）、架构约束（自定义 linter + 结构测试）、反馈回路（可观测性工具直接接入 Agent 运行时），以及定期运行的「垃圾回收」Agent 扫描架构漂移。

两个视角，指向同一个核心：Harness 是让 Agent 可靠工作的系统，而不只是模型本身。

OpenAI 在官方《Harness Engineering》博客文章中提到了这样一段话（以下为意译）：

「显而易见的是：构建软件仍然需要纪律，但纪律更多地体现在支撑结构（scaffolding）上，而不是代码上。保持代码库一致性的工具、抽象和反馈回路变得越发重要。」

「我们当前最棘手的挑战集中在设计环境、反馈回路和控制系统方面，帮助智能体实现我们的目标：大规模构建和维护复杂、可靠的软件。」

这句话非常重要，因为它重新定义了「工程纪律」的所在。

以前，纪律体现在：好好写代码、认真做 code review、遵守编码规范。 现在，纪律体现在：构建好让 Agent 工作的环境——文档、约束、反馈回路。

纪律没有消失，只是转移了。从「如何写好代码」，转移到了「如何构建支撑 Agent 工作的系统体系」——包括结构化的文档、明确的约束规则、完善的反馈回路等。我们把这个转移总称为从代码驱动转移到了环境设计。

而 scaffolding 的质量，由什么决定？由写进去的内容决定。

OpenAI 自己的 Harness 里，维护着 product-specs/、design-docs/、exec-plans/——这些都是结构化写进仓库的「意图和规范」。他们总结出的核心发现是（以下为原文大意）：从智能体的角度来看，它在运行时无法在情境中访问的任何内容都是不存在的——存储在 Google Docs、聊天记录或人们头脑中的知识都无法被系统访问；代码仓库本地的、已版本化的工件，才是 Agent 所能看到的全部。

Agent 看不到的，就不存在。 这不是隐喻，是事实。

所以 Harness 里的 scaffolding 究竟是什么？是所有被写进仓库、Agent 可以读到、可以推理的内容——包括规范、意图、约束、决策记录。

「把意图和规范写进仓库」，本身就是 Harness Engineering 的核心工作之一。

明白了「scaffolding 由写进去的内容决定」，Spec 在 Harness 里的角色就清晰了。它不是 Harness 的附件，而是 Harness 能运转起来的前提之一。具体是三个角色：

   3.1 角色一：Agent 推理的地图

OpenAI 有一条实践原则：

「要给 Codex 的是一张地图，而不是一本 1,000 页的说明书。」

「这实现了渐进式披露：智能体从一个小而稳定的切入点开始，并被指导下一步该去哪里查看，而不是一开始就被淹没。」

这正是 Spec 应该是什么：一张地图，而不是一本百科全书。

地图的特点是：有目录，有指针，Agent 从高层概览出发，按需深入到具体节点。系统级 Spec 告诉 Agent「这个系统有哪些服务、各自负责什么、边界在哪里」；服务级 Spec 告诉 Agent「这个服务内部有哪些能力、接口语义是什么、行为规则是什么」。Agent 不需要一次性读完所有内容，它被指引着去找它需要的那部分。

没有这张地图，Agent 的起点是代码——而代码只告诉它「系统现在是什么样」，不告诉它「为什么是这样」「哪些是不应该改的」「这个字段在跨服务之间有什么约定」。

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

OpenAI 用 linter 和结构测试来机械地强制执行架构规则——比如层间依赖方向、文件大小限制、命名规范。这些是「格式」层面的约束，可以完全自动化。

但 linter 检查不了语义。它不知道「某个错误码在跨服务场景下应该怎么处理」，不知道「某个接口字段在特定来源场景下的业务含义」，不知道「这个状态的流转规则是什么」。

这些语义，必须被显式写下来，Agent 才能正确推理。Spec 的契约层和行为规格层承载的，正是这类「linter 管不到、但 Agent 必须知道」的语义约定。

在笔者的 SDD AI Coding 实践中就遇到过类似的问题：服务 A 定义了某个错误码的含义，但服务 B 的 Agent 在实现时完全不知道这个跨服务语义，于是沉默地猜测了一个处理方式。AI 的猜测不会告诉你「这里我猜了」——它只是生成了一段看起来合理的代码，然后上线后才发现行为不符合预期。

这个 bug 不是 Agent 能力不够，是跨服务的错误码契约没有被写进 Spec——在 Harness 的 scaffolding 里，这一块是空白的。后来在系统级 Spec 里补充了完整的错误码契约，同一个 Agent 生成的实现通过了验证——不是换了更强的模型，而是补上了缺失的语义定义。

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

Harness Engineering 的核心飞轮是：Agent 犯错 → 诊断原因 → 工程化修复 → Agent 不再重犯。

但这个飞轮的第一步「Agent 犯错」，需要一个前提：你能知道 Agent 犯错了。能知道，需要有一个「正确性的判据」——对照什么来判断 Agent 的输出是对是错。

如果只有代码，这个判据很难建立——代码只描述了「系统实际是什么样」，不描述「系统应该是什么样」。你只能靠人肉 review，靠跑起来看结果，靠上线后被用户发现。

Spec 的验收标准层（WHEN/THEN Scenario，即描述「在什么条件下，系统应该有什么行为」的结构化场景）提供的，正是这个判据。Agent 的实现可以被自动对照 Spec 里定义的场景来验证——覆盖了哪些 Scenario、哪些没有覆盖、哪些行为和 Spec 描述不一致。有了判据，反馈回路才能闭合；没有判据，「发现错误」这一步只能靠运气。

理解了 Spec 在 Harness 里的三个角色，回到最初的问题：规范驱动 AI Coding 还有意义吗？

规范驱动 AI Coding（本文简称 SDD）不是独立于 Harness 的另一套东西，而是在回答：Harness 里的 Spec，应该长什么样、包含什么、如何组织，才能真正让 Agent 可以推理、可以执行、可以验证。

   4.1 Spec 决定 Agent 能做对什么

Agent 的输出质量有一个简单的上限：它的输入质量。Spec 写得越完整、越精确，Agent 猜测的空间就越小，产出正确的概率就越高。上述案例已经说明了这一点——不是换了更强的模型，而是补了 Spec，同一个 Agent 就能一次做对。

这不只是单点的正确性。Spec 的价值在三个层次上递进：一个 capability 内做对（WHEN/THEN Scenario 约束行为边界）→ 多服务联动做对（系统级契约让各服务 Agent 看到同一份语义）→ 改了还对（验证规范提供持续的回归基线）。

OpenAI 也走了这条路：他们的 Agent 在处理「这四个关键用户旅程中的任何跨度都不得超过两秒」这样的约束时，需要靠写进仓库的可观测性配置和规范文档，Agent 才能推理和验证。

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

有一个常见的误解：规范驱动（SDD） AI Coding 是「先写文档再写代码」，前期投入多，变慢了。

实际上，规范驱动方法优化的不是「写出第一版代码的速度」，而是「正确交付的总成本」。

没有 Spec 时，跨服务的歧义要等到联调才暴露，边界条件要等到上线后才被发现，每次新的 AI 会话都要从零重建上下文。这些隐性成本，加起来远超写 Spec 的投入。笔者的实践经历也印证了这一点：后续修复变更的时间几乎全部来自初版 Spec 精度不足——错误码语义、非功能约束、边界条件没有在 Spec 中定义，Agent 猜测了，上线后才发现。

OpenAI 的工程师们也有同样的发现。他们花了大量时间把越来越多的「原本在人脑里的东西」显式写进仓库：

「那次让团队在架构模式上达成一致的 Slack 讨论？如果智能体无法发现它，那么它就会像迟了三个月入职的新员工一样，对其一无所知。」

前移写进 Spec 的成本，消灭的是后移返工和猜测的成本。

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

AI Coding 加速了一个已有的问题：知识随人和会话流失。在 Vibe Coding 模式下（即不做规划、随意向 AI 提需求的开发方式），大量设计决策、跨服务约定、「为什么不选另一个方案」的讨论，全部停留在一次性的 AI 对话里——下一个人，或者下一次 AI 会话，完全无从获取。

Spec 把这些知识从「人脑 + 对话历史」转化为「仓库里版本化的结构化资产」。系统级 Spec 记录跨服务约定，服务级 Spec 记录各服务语义，决策记录层（+1层）记录「为什么选了这个方案、排除了什么」。人可以换，AI session 可以换，但 Spec 留下来——这是 Harness 里 scaffolding 能长期有效的前提。

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

OpenAI 的文章里有一段话，说的是他们实验中的角色转变：

「当事情进行不顺利时，解决方案基本上再也不会是'再努力一点'。因为取得进展的唯一方式是让 Codex 来完成工作，而人类工程师则总是介入这项任务并追问：'究竟还需要什么样的能力，我们又该如何让这个能力对智能体来说既清晰可读又可强制执行？'」

这个「追问」，就是 SDD 在做的事情。

写 Spec 的过程，本质上就是在回答这个追问：系统需要什么能力？这个能力的边界在哪里？行为规则是什么？失败的场景怎么处理？这些信息怎么组织才能让 Agent 既能读懂又能执行？

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

   4.5 一套典型的规范驱动方案是什么样的

OpenAI 自己的实践已经给出了一个具体的参照：仓库里维护着 product-specs/（产品规格）、design-docs/（设计文档）、exec-plans/（执行计划）三类结构化文档，各自承担不同粒度的角色——产品规格定义系统要做什么，设计文档描述技术方案，执行计划拆解具体任务。Agent 从高层的产品规格出发，按需深入到设计文档和执行计划，不需要一次性读完所有内容。

这正是 OpenAI 说的「渐进式披露」的工程化落地：Agent 从稳定的高层视图切入，被指引着找到它需要的那部分，而不是一开始就被海量文档淹没。规范驱动开发（SDD）的核心，就是如何把意图、契约、行为规范按这个逻辑组织起来——让 Agent 既能找到地图，又能在需要时深入到细节。

整套体系里，人类只做两件事：提供原始意图（口述需求、架构决策），以及审查 AI 生成的 Spec 和代码。Spec 的生成由 AI 主导，基于引导式对话从人类的非结构化输入中提取、精化、结构化。人类不直接编写 Spec 文件，但人类审查 Spec——因为审查 Spec 比审查代码简单得多：你在审查的是自己意图的结构化表达，而不是 AI 对你意图的解读。

前面四节在回答「SDD 为什么有意义」。这一节想说另一件事：读完这两篇文章，有些东西不只是「印证了 SDD 的方向」，而是「让一些原本模糊的事想得更清楚了」，也看到了一些典型 SDD 方案里还需要补充的地方。

   5.1 启示一：人类注意力是最稀缺的资源——审查的重心应在 Spec，而不是代码

OpenAI 整篇文章有一条隐线：人类的时间和注意力是固定的限制因素，所有的工程投入都在想办法让这有限的注意力产生最大的杠杆效应。他们说：「我们优先处理工作，将用户反馈转化为验收标准，并对结果进行验证」——人类做的是「定义正确性」，而不是「检查每一行代码」。

在一套 SDD 方案里，人类只做两件事：提供原始意图，以及审查 AI 生成的 Spec 和代码。Harness 的视角让这两件事的优先级顺序更清晰：

Spec Review 是上游控制。一个 Scenario 被遗漏、一个字段语义被写模糊，Agent 会在整个实现过程中持续放大这个偏差——实现、测试、文档都会基于这个有缺陷的定义生成出来。在 Spec 层发现问题，修改成本极低；等到代码生成之后再发现，涉及的改动范围就大得多了。

Code Review 是反馈入口。审查代码的主要价值，更多在于「发现 Spec 没有定义清楚的地方，并把它补回 Spec」，而不仅仅是「检查 Agent 写得好不好」。每一个在代码 Review 里发现的语义问题，本质上都是一个 Spec 缺口——修代码是治标，补 Spec 才是治本，也是让飞轮继续转下去的方式。

在落地时，这意味着需要有意识地建立一个认知：先把 Spec Review 做好，Code Review 的压力会自然减轻。

   5.2 启示二：「大型 AGENTS.md」是一个陷阱——执行约束和语义约束要分开管

OpenAI 明确踩过这个坑：他们尝试过一个大型的 AGENTS.md，记录所有 Agent 应该遵守的规则，结果发现它有四个系统性问题——挤掉有效上下文、过多导致失效、立即腐烂、难以核实。最终结论是：AGENTS.md 应该是目录，而不是百科全书——大约 100 行，主要用来导航，指向其他地方更深层的真实来源。

背后的原因是：执行约束（「不要使用这个 API」「文件大小不超过 X 行」「不要运行这个命令」）和语义约束（「这个字段的含义是什么」「这个服务的边界在哪里」「这个错误码在跨服务场景下如何处理」）是两类性质完全不同的东西。混在同一份文件里，两者都会随着文件膨胀而失效。

这套 Spec 体系天然处理了语义约束——按层、按粒度组织，Agent 可以按需导航。但执行约束这一类，在典型的 SDD 方案里还需要明确划定位置。这是在落地时需要补充的一块：AGENTS.md（或等价物）应当作为 specs/ 体系的入口文件，保持轻量和精简，职责是「Agent 进入代码库后应该怎么行动、去哪里找什么」，而不是把 Spec 里的语义规则再复制一遍。两类约束分开管，各自才能保持清晰和可维护。

   5.3 启示三：Spec 漂移是必然的——仅靠人工维护不够，需要主动检测机制

OpenAI 发现：随着代码吞吐量增加，Agent 会不断复现代码仓库里已有的模式，包括那些不均衡或不理想的模式。人工每周花 20% 的时间清理「AI 残渣」，不具备可扩展性。他们的解法是把「品味」编码进规则，然后用一个定期运行的「doc-gardening」Agent 自动扫描漂移、发起修复 PR——「技术债务就像一笔高息贷款，不断地以小额贷款的方式偿还，总比让债务不断累积要好」。

这个问题对 Spec 更严峻。代码漂移通常能在运行时感知——测试挂了、类型报错了、行为不符合预期。但 Spec 漂移是沉默的：Active 状态的 Spec 在描述一个已经演进了的系统，它不会报错，不会提醒你，只会沉默地让下一个 Agent 基于一份过时的定义去生成代码。

典型的 SDD 方案通常已有 Spec 生命周期管理（Draft → Active → Deprecated）和变更治理流程，但触发 Spec 更新的动作目前依赖人工——需要开发者在做需求时记得同步更新。设计一个主动的 Spec-Code 一致性检测机制，是后续值得重点建设的方向：对照接口定义、数据库 Schema、配置文件，定期检测 Spec 描述是否与代码现状一致，对漂移条目自动发起更新提案。在这个机制建立之前，先用工程规范来弥补：Spec 修改和代码修改必须在同一个 PR 里提交，Spec 先于代码合入。

   5.4 启示四：遇到问题时，追问的方向是「AI 还缺什么」，而不是「人类再努力一点」

OpenAI 说了一句值得反复回想的话：「当事情进行不顺利时，解决方案基本上再也不会是'再努力一点'。因为取得进展的唯一方式是让 Codex 来完成工作，而人类工程师则总是介入这项任务并追问：'究竟还需要什么样的能力，我们又该如何让这个能力对智能体来说既清晰可读又可强制执行？'」

这句话的启示是：在落地过程中遇到 Bug 或阻塞时，首要的追问不是「怎么让人把这件事做对」，而是「AI 在完成这件事时还缺什么」。缺的可能是 Spec 里的一个 Scenario，可能是一个让 AI 能自我验证的工具，也可能是系统里缺少一层 AI 可以直接读取的可观测性数据。

OpenAI 花了大量精力让应用程序对 Agent「直接可读」：把日志、指标、追踪接入 Agent 运行时，让 Agent 能启动应用实例来复现 Bug、验证修复，而不是每次都靠人工 QA。这些投入是让执行层能够自主运转的基础设施。SDD 体系解决了「Spec 这一层的可读性」——Agent 有地图、有契约、有行为规范可以推理。但随着落地推进，让 AI 也能读到运行时的反馈信号——日志、错误、验证结果——是下一个值得投入的方向，让 Harness 飞轮的「发现错误」这一步更多由 AI 自己完成，而不是等人来发现。这部分和 SDD 的直接关联相对松散，但它是 Harness 整体能力成熟之后自然要走到的地方。

让我们回到最初的问题：Harness 来了，SDD 还有意义吗？

有。而且是更有意义，不是更没有意义。

原因很简单：Harness 是放大器。它放大 Agent 的执行能力，也放大输入给 Agent 的内容的影响。Spec 写得好，Harness 把它放大为可靠的、一致的、可验证的输出。Spec 写得差或者根本没有，Harness 把 Agent 的猜测放大为高效率地产出错误。

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

OpenAI 自己说得很清楚：最难的挑战不是「模型够不够强」，而是「如何设计环境、反馈回路和控制系统」。这正是 Harness Engineering 的实质——也正是 SDD 在解决的问题。

构建 SDD 体系，不是在做一件和 Harness Engineering 平行的事，而是在回答 Harness Engineering 最核心的那个追问：究竟需要什么样的 scaffolding，才能让 Agent 把我们想要的东西，既清晰可读又可强制执行地做出来？

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

参考来源

• Mitchell Hashimoto 《My AI Adoption Journey》，2026 年 2 月 https://mitchellh.com/writing/my-ai-adoption-journey#step-5-engineer-the-harness

• OpenAI 工程团队 《Harness Engineering》官方博客文章，2026 年 2 月 https://openai.com/index/harness-engineering/

关于本文的说明

本文综合了 Mitchell Hashimoto 和 OpenAI 官方文章中关于 Harness Engineering 的论述。其中：

1. SDD（Spec-Driven Development） SDD 特指通过结构化规范指导 AI Agent 进行软件开发的工程方法。

2. 引用翻译 中文表述为笔者根据英文原文的理解和意译，部分表达可能与官方中文版本（如有）存在表述差异。

3. 观点声明 本文中对 Harness Engineering 和规范驱动方法的分析和观点，是基于作者对公开信息的理解和实践经验的总结。