引言：为什么需要 Harness Engineering

为什么你需要 Harness Engineering：Vibe Coding 的蜜糖

如果你读到了这本书，相信你已经在Vibe Coding上有了一些经验。Vibe Coding是一片糖衣炮弹，它的初期体验非常好：跟 Claude Code说一个需求，几分钟的等待后大段的代码生成，应用启动。再加上几句短暂的讨论，更多的需求完成，一个下午就能搞定了过去几周的代码。 但是在短暂的蜜月期后，问题就逐渐出现了。随着代码库的扩大，让 Agent 在已有的代码上改一个功能，另一个功能又会出现问题。一通操作修好了，又冒出新的 bug。来回几十轮后bug仍然顽固，气不过的你打开了源代码，发现整个项目已经成为了无法维护的屎山——硬编码的路径，大段的无用代码，同一个函数有五六种不同实现，被不同的模块交叉依赖。花时间整理修改的代价还不如从头开始。

在过去的两年中，模型的能力有了巨大的飞跃， GPT-4、 Sonnet 3.5， Opus 4.6，每一代确实更强——更大的context window，更好的指令遵从，更高的智能。 而在这个过程中你自己也在进步，学习了prompt和context技巧，给的上下文更有针对性了。但是同样的崩溃模式不断在更大的规模上重现。项目再大一点，迭代再多几轮，Agent 仍然忘了之前约定的规范，修改不该修改的代码，导致产出开始偏离预期，最终不可维护。

大部分开发者的 Agent 使用体验也类似，体感上AI在以上百倍的速度产生代码，但是综合生产力提升，好像并没有那么多。然而在另一个方面，少数人做到了截然不同的成绩。PingCAP 的 CTO 黄东旭用 AI 将 TiDB 的 PostgreSQL 兼容层完全使用Rust重写。Pigsty 创始人冯若航一个人用 AI 维护着集成了 460 多个扩展的企业级 PostgreSQL 发行版，日常同时调度十个 Agent 并行推进。他们的生产力提升以数十倍计，产出的是生产级别稳定性的代码。

同样的模型，同样的工具，差距以数十倍计。差在工程制度上。这足以说明这并非是AI无法处理复杂的大型项目，而是模型能力或 prompt 技巧上的改进并没有从根本上解决问题。 Agent编程是与人类编程完全不同的生产力，Agent有自己的结构性特征。而能够大规模使用 Agent 的团队都建立了一套与 Agent 结构性特征匹配的闭环控制体系，用系统性的方法约束住Agent开发时的不确定性。这类系统性的方法，我们称为Harness Engineering（约束工程）。

要约束AI的不确定性，首先要理解AI不确定性的来源。在这本书中，我们将系统的分析Agent开发时不确定性的结构性来源。并介绍在Harness Engineering如何针对每一个特征，在软件开发的各个环节对其进行系统的限制和审查，从而让Agent能够稳定，高质量的交付生产可用的代码。书中介绍的所有方法论均来自Agent特区社区成员的真实经验，已经在大规模的实践和讨论中证明了有效性。在阅读这本书后，你将不仅对Harness Engineering的基本原则有深入的认知，精准的定位Agent软件工程失控的根因，判断层出不穷的Agent管理框架是否在解决真实的问题，同时也将收获具体可操作的实践方法论，实现真正的生产力跃升。

Agent 的结构性特征

要学习如何控制Agent带来的不确定性，需要先学习Agent的基本行为特征。Agent的基本能力来自大语言模型(Large Language Model/LLM)。LLM基于输入内容生成思考，决策，调用工具完成任务。而Agent编排框架在顶层为 LLM 提供与外部世界交互的能力：Agent 接收指令，推理下一步行动，调用工具（读文件、执行命令、调 API），观察工具返回的结果，再推理，再行动。这个循环持续进行直到任务完成。

在这一小节中，我们介绍AI作为执行者的五个结构性特征，这些特征都是基于架构的内在属性，不会随着模型能力的增长消失。从而为Harness Engineering的设计提供基石。

有限处理容量

Agent 的第一个特性是工作记忆有硬上限，有效容量远小于标称数字。所有信息给得越多效果越好的直觉是错的。

Agent 的全部工作记忆就是 context window。你的指令、代码文件、对话历史、工具返回的结果，所有信息被拼接成一个 token 序列送入模型。这个序列有长度上限，当前主流模型从 128K 到 1M tokens，看起来很大。但标称容量和有效容量是两回事。如果你不了解LLM的基本原理，这里需要补充一条较为重要的背景知识：目前所有的LLM都基于一套名为Transformer的架构，这套架构的核心是一套名为“注意力(attention)”的机制。在生成内容的时候，大语言模型并不会真正“阅读”给出提示词的全部内容，而是根据模型内部算法，在你输入的每个Token上计算一个“注意力”，获得”注意力”较高的内容会在模型生成内容时被重点考虑。而“注意力”在 context 上的分配不是均匀的，有研究显示，早期LLM的注意力信息在开头和结尾关注度较高，中间部分召回率显著下降。另一个方面，在context中包含信息越多，每条信息分到的 attention 权重越少，一些很重要的信息可能反而因为内容过多而得不到足够多的”注意力”，导致被淹没在噪声里。标称 1M tokens 的上下文窗口，有效利用的部分可能只有一半甚至更少。

这个限制在两个场景下表现得特别明显。

第一个场景是大任务。小任务涉及几个文件、一个功能点，所有相关信息都在有效注意力范围内，Agent 表现很好。大任务需要同时考虑数据库 schema、API 契约、前端状态管理和权限模型，相关信息的总量超过了有效容量，Agent 开始顾此失彼。人类程序员对整个系统有一个持久的心智模型，能在处理局部代码时维持全局一致性。Agent 每次都在有限的窗口内从头构建理解，装不下的部分直接被忽略。

第二个场景是长链推理。Agentic Loop 的每一步都往 context 里追加内容，窗口内的信息持续增长。第 5 步做出的接口设计决策，到第 50 步时已经被淹没在海量的对话记录和工具调用结果中，获得的 attention 权重很低。Agent 前半段声明的关键约束和信息在后半段被无声地忽略。

Harness Engineering需要提供系统的上下文控制机制，确保只有合适，与任务相关的上下文被注入执行AI中。

忠实执行

Agent的第二个特性是忠实地执行你给它的输入。通过训练AI，获得了非常强的指令遵循能力，根据指令来输出合理的结果。这是一把双刃剑，如果给出的输入清晰完整，AI可以产出高质量的结果。而任何模糊之处，AI会根据常识补全一个它认为合理的信息。

人类程序员遇到同样的模糊需求，会询问同事，会看现有代码里类似功能是怎么做的，会根据开会时收到的信息推理。但Agent不同，它倾向于跳过了所有这些补全步骤，直接从模糊的输入生成确定的输出。人类程序员通过 code review、站会、日常协作逐步吸收这些知识。但对于Agent来说只有被写进 context 的知识才存在于 Agent 的世界中，产出的代码会在功能上正确地忽略所有未被显式提供的知识。

你对 Agent 说，加一个搜索功能。搜索的范围是文章标题还是全文？结果按什么排序？关键词为空时显示什么？每个没有说清楚的点，Agent 按训练数据中概率最高的方案填充，然后忠实执行。

另一个更可怕的缺陷则是上下文冲突。当你提供的信息中包含了互相矛盾的信息时，AI是无从判断正确性的。根据我们讨论过的注意力机制，任何一个信息都可能因为收获更多的注意力在生成内容时胜出，生成无法控制的内容。

Harness Engineering框架需要系统的定义项目所需的context，并提供完整的方法以检验所有输入的完整和准确性，才能确保AI的产出符合开发者的期望。

无记忆积累

Agent 的第三个特点是无记忆积累。会话从你发起指令开始，到会话关闭结束。会话期间，所有信息都在 context window 里积累。会话结束后，context 被清空，下一次会话从空白开始。你花二十分钟教它的架构约定、踩过的坑、约定的接口规范，今天全部归零。第一百次会话和第一次会话的起点完全相同。

人类团队的知识积累方式完全不同。一个程序员在项目上工作越久，对项目的理解越深。架构决策的历史原因、各模块的脆弱点、特定业务场景的处理惯例，这些知识大多从未被写成文档，但活在团队成员的脑子里，通过 code review、站会、日常协作自然传递和更新。Agent 驱动的开发缺乏这个自然的积累过程。

随着模型基础能力的不断进展，它已经可以提供越来越大的context window让模型可以天然的“记住”任何东西，但是注意力丢失和context window的硬上限始终是绕不开的槛。Agent框架提供了如compaction等功能自动“压缩”已有的对话，来腾出context的位置。但是这样就把记忆的取舍全部交给了Agent框架，它仍然没有准确的办法评估任何内容的重要程度。

一个简单的解决方式当然是把知识外化为文档来弥补，但文档本身也需要持续维护。人脑中的知识随项目演化自动更新，你重构了一个模块，你脑子里对这个模块的理解同步更新了。文档不会自动更新。糟糕的过时文档将前后矛盾的信息注入到Agent当中，导致Agent的性能崩塌。

Harness Engineering框架需要提供系统的记忆管理和提取机制，让记忆可以有效的随着软件的演进同步发展，并且在需要的时候有效提取最相关的信息。

无后果感知

Agent 的第四个特点是无后果感知。和忠实执行类似，Agent尽善尽美的完成你交给它的任务目标，但是代码的长期可维护性、技术债的积累水平、架构的一致性，这些维度都不在它的优化目标里。人类程序员会想到三个月后自己还要维护这段代码，会为了可读性牺牲一些短期效率。Agent 的每一次执行都是独立的，当前任务完成就是全部目标。

这个特征带来一个自强化循环。Agent 在生成新代码时会参考代码库中已有的模式。你之前赶工留下的一段 workaround，在 Agent 看来就是项目中已建立的实现模式，会被忠实地复制到新代码中。合并后的代码成为后续生成的参考集，坏模式不断被复制和放大。人类团队积累同等规模的技术债通常需要几个月到一年，Agent 驱动的团队可能在几周内达到这个水平。系统中没有任何内在力量推动重构或质量改进。

Agent 对所有任务分配同等的注意力和速度。修改一段展示页面的文案和修改支付扣款的核心逻辑，在执行层面完全一样。人类面对高风险操作会本能地放慢节奏，增加确认步骤，找同事一起看。Agent 对所有任务一视同仁。高风险操作混在大量低风险操作中间，以同样的速度被处理。

Harness Engineering框架需要提供完备的验收机制帮助AI克服后果问题，在合适的时机触发重构，在高风险改动中添加确认和验收机制。

高吞吐零边际成本

Agent前四个特征虽然独属于AI，但是在人类的深度参与下并非不可跨越的问题。人类来得及 review 每个 PR，在新会话开始时重新教一遍关键约定，在发现AI产生偏离预期的实现后及时修正它。但是AI的第五个特征：高吞吐零边际成本，让Human in the Loop的模式不可持续。Agent 的产出速度是人类的上百倍。同时，它可以被轻松地并行实例化。启动第二个、第十个、第一百个 Agent 实例的成本趋近于零，不需要招聘、培训或沟通协调。

这个特征自身不产生新的问题类型，但把前四个特征的影响放大一到两个数量级。如果你想真正实现生产力的跃升，大规模的AI自动化是不可避免的。一个模糊的文档，单个Agent执行后产出两三个需要修正的偏差，程序来得及逐个纠正。而在大规模并行的场景下，可能在一个小时内产出上百个偏差各异的实现。

百倍速打破了产出和审查之间的节奏匹配。最后一道防线，人工 review，在百倍产出面前失守了。人类不可能以百倍速度审查百倍产出。

从Harness Engineering框架的角度来讲，则是框架需要明确的定义必须由人类验收的部分和可以进行自动验收的部分，通过明确的分类让人类尽可能的脱离生产代码的关键路径，不成为阻碍AI交付的绊脚石。

Harness 的本质

这五个特征共同指向一个需求。开发者需要外部的、自动化的、独立于 Agent 的Harness Engineering框架，来真正驾驭Agent，实现生产力的跃升。除了刚刚提到的特征，Harness Engineering设计时还需要考虑两个原则：

闭环控制保证每一次执行可靠，并可以自动化前进。闭环做两件事。第一件是用规约定义清楚什么是对的，把你脑子里的意图变成 Agent 可以对照执行的精确描述。一份规约包含意图（做什么，为什么做），验收条件（怎么算做对了），和约束（改动的边界在哪，什么不该动）。有了规约，Agent 的输出从不可预测的随机变成了可以检查的有限集合。第二件是用验证检查做对了没有。验证是独立于 Agent 的自动化检查机制，在偏差产生的时刻就捕获和纠正它，而不是在最终交付时由人类肉眼发现。规约和验证构成反馈回路，偏差被即时发现并纠正。

持续演进则是软件工程的基本原则，是让Agent能够产出长期可维护生产级代码的必要手段。软件在被开发出来的那一刻就成为负债，后续的功能迭代，需求变更才是维护成本的大头。Harness Engineering不仅需要保证一次生成满足开发者期望的代码。还需要在软件的后续演进过程中闭环本身不会退化。

这两个原则，加上我们刚刚讨论的Agent根本特征，是本书对 harness engineering 的完整定义。Harness Engineering不是prompt engineering的trick，或是某些可以在系统级透明提供的监控功能，而是一个围绕 Agent 结构性特征设计的完整工程体系。

通过应用本书中的方法论，我们将手把手的分享我们第一线的实践经验和理论构建。让Vibe Coding时无法驾驭的AI Agent成为真正稳定、可靠的生产力交付工具。

全书路线图

全书沿生产力阶梯展开，每一卷对应一个跃迁阶段。

卷一解决可靠性。你坐在 Agent 前面一问一答，但产出从碰运气变成工程化交付。规约章节讲怎么把模糊的意图变成 Agent 能精确执行的输入。验证章节讲怎么用自动化手段证明产出符合意图。掌握这两章，你在单次交互层面建立起闭环。

卷二解决规模。闭环建立之后你才有可能放手让 Agent 自主执行。缺少闭环的自主执行就是 YOLO mode，灾难是确定的。第四章处理长期执行中的上下文管理和跨会话记忆，让一个 Agent 能持续推进复杂任务而不丢失关键信息。第五章扩展到多 Agent 并行，解决隔离与集成的问题。你从实时操作者变成任务的设计者和验收者。

卷三解决组织。个人效率不再是瓶颈后，瓶颈转移到团队层面。分工、流程、角色定义都是为人类的执行速度设计的，需要重新匹配 Agent 时代的节奏。卷一卷二建立的工程实践是组织级协作的基础设施，没有这些基础设施，团队级的 Agent 协作无从谈起。

三类读者可以从不同入口开始。如果你是工程师，正在从自己写代码转向指挥 Agent 写代码，从卷一开始，沿着生产力阶梯一路走下去。如果你是产品人或编程新手，已经用 vibe coding 做出了能跑的产品，卷一的规约和验证会直接帮到你。如果你是技术负责人，正在推动团队 AI 转型，可以先看卷三了解组织层面的挑战，再回到卷一卷二了解支撑组织变革的工程基础。

Harness Engineering Playbook · AgentsZone Community