《Harness Engineering 实战让 Coding Agent 持续、可靠地完成工程任务》一、Harness Engineering 到底是什么Harness Engineering 工程关注的就是这些让模型持续、可控地完成任务的工作条件。先说清 Harness 在系统中的位置。在 AI Agent 的语境里可以把 Harness 理解为承载模型工作的运行机制它准备上下文协调模型与工具的调用收集执行反馈管理任务状态并决定何时继续、停止或交接。不同系统的具体边界会有差异本文讨论的是 Coding Agent 场景。模型负责根据输入生成内容、判断和工具请求运行机制负责把请求交给工具并把结果带回下一轮实际的文件读写、命令执行和网络访问还受到执行环境与权限系统的控制。我们使用的 Coding Agent通常已经把其中多项能力组合起来。因此在已有 Coding Agent 上实践 Harness 工程可以从项目周围的机制入手整理上下文入口、提供稳定的验证命令、记录任务状态、设置工具边界、保存交接证据。只有现有能力不足时才需要自己编写更多运行时逻辑。二、概念理解几个经常一起出现的概念可以这样区分概念主要回答的问题退款任务中的例子Spec什么行为符合要求重复请求不能产生第二笔退款Prompt当前这一轮要做什么根据失败报告定位原因并提出修复Skill某类任务通常怎样操作按项目约定排查、修复并执行回归Harness工作如何持续推进并受到检查调用工具、回传结果、控制状态、检查完成条件、保存交接它们可以配合使用。一个更详细的 Prompt 能改善当前指令一套可执行的机制则能让后续每轮行动都有明确依据。闭环的关键在于执行结果能改变下一步。下面用一个顺序执行、内存存储的模拟退款接口说明。这是教学设计不涉及真实支付、并发请求或数据库事务。先把验收条件写成能够观察的结果本人可以退款他人请求被拒绝且没有退款副作用同一订单再次请求时退款记录总数仍然为一已有订单功能通过回归。重复请求具体返回什么状态码由接口契约确定幂等性本身并不要求所有系统采用同一种响应。随后把这些要求接入工作流程验收未通过有新依据且允许继续无法继续或达到停止条件检查未能执行恢复后重新检查无法恢复检查通过仍有缺项条件满足确认目标、规格和当前版本执行下一步操作运行检查并收集证据结果属于哪一类分析失败并选择下一步保存未完成状态并交接排查环境或依赖核对全部完成条件与证据版本记录完成并交付三、实际业务案例举例来理解你给 Coding Agent 一项需求为订单增加退款功能要求只有订单本人能操作同一笔订单不能重复退款。Agent 修改了代码也运行了测试。第二次退款仍然产生了新的退款记录它继续修改再次运行最后告诉你“退款功能已经完成。”在这个设想的场景里需求写了代码改了工具也调用了。缺少的是一套机制让失败真正影响下一步行动让未满足验收条件的任务保持未完成让接手的人能够核对到底发生了什么。“重复退款仍然失败”提供的信息太少。一份有用的反馈应让 Agent 知道失败发生在哪里、预期是什么、实际是什么。例如# 示意报告字段与数值用于解释机制check:repeated_refund_has_no_extra_effectexecution:completedresult:failedexpected_refund_records:1actual_refund_records:2evidence:reports/refund-check-014.logtask_status:incomplete这份反馈证明重复请求产生了额外退款记录。但它还不能证明原因一定是“订单状态没有更新”。也可能是检查顺序有误或者重复请求走了另一条分支。Agent 下一步应检查这些可能性形成可以验证的修复假设再修改并重跑。失败信息越具体下一轮越容易围绕证据推进。如果检查因为依赖缺失根本没有启动应该记录“尚未验证”先处理环境问题。“业务断言失败”和“检查无法运行”需要不同的处理路径把它们都压缩成一个“失败”会引导 Agent 修改错误的地方。完成是一项需要证据支持的状态。“代码已经修改”“测试命令退出”“当前检查通过”和“任务完成”分别说明不同的事情。在这个例子中允许进入完成状态的规则可以写成必需检查全部实际执行且通过结果对应当前待交付代码没有未处理的阻塞项并且规格要求的人工验收已经完成。是否需要人工验收应在任务开始时约定。这个规则应进入任务状态管理或交付检查。模型输出一句“完成了”可以视为完成申请最终是否标记完成由约定的条件判定。即使全部检查通过结论也只覆盖已验证的要求测试本身仍可能遗漏场景。同样停止工作有多种原因。连续几轮出现相同失败、没有获得新证据或已经用完预算都可能触发停止。此时任务应保留未完成状态附带已尝试的方案、失败证据和下一步建议。“三次失败”可以是某个项目的策略参数不是 Harness 的通用法则。Anthropic 对长任务 Agent 的实验记录了提前宣布完成、一次尝试过多功能和验证不足等问题。他们采用初始化与后续增量开发的安排通过功能清单、进度记录和 Git 历史帮助后续会话接续工作。这些实践说明跨轮次状态需要被明确保存和核对。把约定变成机制需要知道约束由谁执行。在 AGENTS.md 中写“不要修改验收测试”表达了协作要求。工具层的写入范围、沙箱权限或受保护的检查流程才能在执行时阻止或检出越界操作。如果验收测试和“通过报告”都能被同一个 Agent 任意改写检查结果就需要额外审视。团队可以将验收基线交给独立的 CI 流程执行对测试变更设置复核或限制 Agent 对相关文件的写入权限。需求变化时测试也可以更新但应有明确的契约依据。这里还有一个容易误解的地方给报告附上哈希能够帮助发现内容变化。假如 Agent 同时能改写报告和预期哈希它就不构成独立的防篡改证明。机制提供多大保证取决于执行它的环境和信任边界。上下文也需要同样的工程处理。规格、代码和说明散落各处即使都写得很详细Agent 也可能读取过时版本。可以保留一个简短的入口指向当前规格、架构说明、修改范围、运行命令和任务状态再按需要加载细节。OpenAI 的工程实践采用了这种资料导航方式并通过自定义 linter 和结构测试检查架构约束。可读的说明帮助 Agent 找到依据可执行的检查则让违反约定的行为产生明确反馈。交接时要交付能够重新核验的状态。假设今天的 Agent 停在退款缺陷上明天换了一个会话。如果只把昨天的分析原样复制过去新会话可能继续修复一个已经被别人改掉的问题。一份简洁的交接记录至少需要包含目标与依据当前需求、验收条件、相关规格位置。当前产物仓库路径、分支、提交以及尚未提交的修改。已确认事实运行过的检查、实际结果、对应日志和代码状态。尚未证实的判断可能原因、排查思路、仍缺少的信息。待办与下一步未完成事项、复查命令、允许继续的范围。例如“第二次请求后出现两笔退款记录”是观察事实“可能漏掉状态更新”是假设。把两者分开能避免猜测在传递中变成既定结论。接手后先比较当前代码、规格和测试是否发生变化再决定哪些证据仍然适用。代码已变化时旧报告仍可用于理解历史但不能直接证明当前版本正确。只保存 Git 提交号有时也不够因为工作区可能存在未提交修改。更稳妥的做法是让验证对应明确的输入快照并记录相关依赖、环境和测试配置。证据究竟需要覆盖哪些输入取决于哪些变化会影响结果。从一个最小任务开始比一次配置所有机制更容易验证效果。在现有项目中可以先选一个范围小、验收明确的缺陷完成四件事写清行为契约、修改范围和完成条件让 Agent 有可查的依据。提供一条稳定的检查命令保留实际输出区分断言失败与执行失败。把检查结果接入任务状态明确修复、停止和交接的条件。保存一次可核验的交接记录让下一会话能够从当前状态继续。完成这一轮后再观察真正的瓶颈是经常读错资料还是反馈过于笼统是上下文丢失还是验收没有约束力针对问题增加机制才能知道它解决了什么。机制的效果也需要评估。可以选择同一批任务尽量固定模型、初始代码、工具权限和预算每次主要调整一种机制并重复运行。除了完成率还要观察误报完成次数、人工接管时间、总耗时和成本。成功多了一次不能单独证明 Harness 得到了普遍改善。Anthropic 在另一项应用开发实验中加入独立评价角色同时记录了评价过于宽松、需要校准的问题随着模型能力变化他们还移除了先前使用的部分上下文重置机制。这提醒我们评价者也需要验证已有流程也需要随模型和任务重新评估。