Harness Engineering：构建高可靠AI Agent的工程方法论

摘要：HarnessEngineering（驾驭工程）是一种提升AIAgent可靠性的工程方法论，其核心是通过优化围绕模型的系统而非频繁更换模型本身。该体系包含六大支柱：1）上下文架构管理信息输入；2）架构约束通过代码强制执行规则；3）自验证循环防止执行异常；4）上下文隔离避免多Agent协作污染；5）熵治理对抗系统复杂性积累；6）可拆卸性实现模块化设计。这些工程机制如同赛车的转向和刹车系统，能确

AI算法工程师笔记

485人浏览 · 2026-04-14 14:42:09

AI算法工程师笔记 · 2026-04-14 14:42:09 发布

李宏毅Harness Engineering驾驭工程教程

当我们观察一辆高性能赛车时，驾驶员的技术固然重要，但更关键的是整套车辆工程系统——转向系统、刹车系统、悬挂系统、仪表盘——这些围绕引擎构建的系统，才是赛车能够高速安全行驶的根本保障。

AI Agent开发面临同样的本质问题：模型本身的智能能力是"引擎"，但引擎再强劲，若缺乏指引方向的"指南针"和确保安全的"刹车系统"，最终的结果往往是在高速行驶中迷失方向或失控。

这正是 Harness Engineering（驾驭工程） 诞生的背景。

什么是Harness Engineering

Harness Engineering（驾驭工程）是AI Agent开发领域中一个关键的工程方法论，其核心理念是：

通过优化模型周围的系统，而非频繁更换模型本身，来提升Agent的可靠性。

这一理念可以用一个简洁的等式来表达： $Agent = Model + Harness$

其中：

Model（模型）：是Agent的智能引擎，提供理解、推理、生成等核心能力，如GPT、Claude、Gemini等大模型
Harness（驾驭系统）：是围绕模型构建的工程系统，包括上下文管理、约束执行、验证循环、状态隔离等一系列工程机制

汽车比喻在这里尤为贴切：模型是引擎，Harness是指南针和刹车系统。一辆没有方向盘和刹车的跑车，无论引擎功率多大，都是一场灾难。同样，一个缺乏Harness工程保障的AI Agent，无论模型能力多强，在真实复杂场景中都将面临不可预测的失败。

技术背景与问题由来

在AI Agent开发初期，大多数工程师将精力集中在两件事上：选择更好的模型，以及优化prompt（提示词）。这种"模型中心论"的开发范式带来了显著的局限性：

问题一：上下文窗口的性能墙与焦虑

研究发现，当大模型的上下文窗口利用率超过40%时，模型的推理质量会出现明显下滑。在长时间运行的Agent任务中，上下文会不断积累历史对话、工具调用记录、中间结果，最终导致模型"信息过载"，输出质量大幅下降。

更隐蔽的问题是上下文焦虑（Context Anxiety）：部分模型在感知到上下文窗口即将耗尽时，会主动提前收尾、跳过尚未完成的步骤，表现得好像自己已经完成了全部工作。与普通的性能下降不同，上下文焦虑不产生任何错误信号，而是静默地输出不完整的结果，在缺乏外部验证机制的情况下极难发现。

问题二：Prompt的脆弱性

通过prompt要求模型遵守规则，本质上是在依赖模型的"自律性"。而大模型在复杂场景中是天然不稳定的——同样的规则描述，在不同的上下文状态下可能产生截然不同的执行效果。

问题三：多Agent协作的污染效应

当多个Agent协作完成任务时，不同Agent的上下文互相污染，导致决策偏差、责任边界模糊、调试极其困难。

问题四：无终止的执行循环

Agent在执行复杂任务时容易陷入无意义的循环：反复重试失败操作、跳过关键验证步骤、在无进展状态下持续消耗token。

问题五：系统熵增导致的维护危机

随着Agent系统不断演进，上下文状态、配置规则、工具约束逐渐积累成难以维护的复杂混乱状态，最终导致系统不可预测性急剧上升。

Harness Engineering正是为了系统性解决上述问题而提出的工程方法论。

六大支柱

Harness Engineering的实践体系由六大核心支柱构成，每个支柱针对不同层面的可靠性挑战。

上下文架构（Context Architecture）

核心理念：精准设计进入模型上下文的信息，避免信息过载。

上下文架构是Harness Engineering最基础也最关键的支柱。研究表明，模型上下文窗口利用率超过40%后，推理质量开始显著下降。这意味着让模型"少想"有时比让模型"多看"更重要。

上下文生命周期管理

上下文架构的核心是为上下文建立完整的生命周期管理机制，而非被动等待模型性能劣化。完整的生命周期包含以下四个阶段：

Claude Code 实践参考

Claude Code在上下文架构上的设计是业内较为完善的参考实现：

结构化注入：CLAUDE.md作为项目级上下文的核心载体，在每次会话启动时自动加载到上下文窗口，充当"项目手册"。开发者可通过/init命令自动生成并持续更新它。
分层记忆系统：/memories/目录按三个作用域分层管理持久化知识——用户记忆（跨工作区全局生效）、会话记忆（当次会话）、仓库记忆（当前项目）。前200行核心文件在会话开始时自动加载，其余按需读取，天然实现了延迟加载。
按需读取：Claude Code默认不会一次性读入所有文件，而是通过工具（read_file、grep_search等）在推理过程中按需拉取内容，有效控制上下文膨胀速度。
上下文重置（Context Reset）与压缩（Compaction）的区别：压缩（/compact命令）是将对话早期内容就地摘要化，使同一个Agent在缩短后的历史上继续执行——可以释放空间，但因为未提供真正的"干净石板"，无法消除上下文焦虑。上下文重置则是彻底清空当前窗口，启动一个全新Agent会话，并通过精心设计的交接文件（Handoff Artifact）传递上一个Agent的任务状态与下一步骤。重置能从根本上消除上下文焦虑，代价是更高的编排复杂度与token开销。当模型在压缩后仍出现提前收尾行为时，上下文重置往往是唯一有效的解决方案。

架构约束（Architectural Constraints）

核心理念：用工具和代码强制执行规则，而非依赖prompt软约束。

这是Harness Engineering最反直觉的一个原则。当我们在prompt中写下"请不要删除用户数据"时，我们是在用语言劝说一个随机采样系统。而架构约束的做法是：代码层面根本不提供删除功能，或在工具定义时强制要求二次确认。

架构约束的工具落地

架构约束的核心在于用工程手段替代prompt劝说。落地时应遵循以下设计原则：

工具设计的约束原则

最小权限暴露：Agent在任何时刻只应获得当前任务最小所需的工具集合，而非全量工具列表。应按任务阶段动态注册工具，而非一次性暴露所有工具。
操作分级授权：将所有工具操作按风险等级分为三级——只读操作自动执行；写操作生成操作计划后等待确认；破坏性操作（删除、重置等）强制双重确认，甚至从工具定义中彻底移除。
强类型参数定义：使用JSON Schema或OpenAPI规范严格定义工具的输入参数类型、取值范围和必填项，拒绝一切不符合规范的调用请求，在架构层防止参数注入和路径穿越。
幂等性设计：所有写操作工具应在设计层保证幂等性。相同参数的重复调用不产生副作用，Agent可安全重试而不造成数据异常。

Claude Code 实践参考

Claude Code将架构约束设计为核心的权限模型，是该支柱最直接的工程实现：

分级权限模式：内置四种权限模式，通过Shift+Tab循环切换，将操作风险与授权级别强制绑定：

工具级黑白名单：通过.claude/settings.json中的allowedTools和deniedTools配置，可精确控制Claude Code可使用的工具范围，实现工具白名单的架构约束。
MCP工具扩展约束：通过MCP（Model Context Protocol）接入的外部工具，其参数校验由MCP服务器侧负责，天然将约束逻辑与Agent主体解耦。

自验证循环（Self-Validation Loops）

核心理念：在Agent执行流程中内置验证检查点，防止死循环与静默失败。

Agent在无人监督的情况下执行复杂任务时，最危险的两种状态是：

无意义的重试循环（消耗大量资源却无进展）
静默地跳过关键验证步骤（生成看似正常却实际错误的结果）

自验证循环通过在每个重要操作节点插入验证逻辑来解决这两个问题。

自验证循环设计要素

自验证循环的设计方法

有效的自验证循环需要明确回答三个设计问题：

① 如何判断"有进展"？

不能仅凭Agent是否产生输出来判断进展，而应通过状态指纹比对来检测。每次执行后对关键状态（任务完成度、已解锁资源、已修改文件等）计算摘要，连续多轮摘要无变化即为停滞循环，应触发升级或中止。

② 如何设置终止边界？

应以"预算"而非"无限循环"的心态设计Agent执行边界：

设置最大迭代次数（如20次），超出则强制中止并上报
设置时间预算，超过任务时限则中断并保存中间状态
设置停滞容忍阈值（如连续3轮无进展），触发自我校正或降级处理

③ 错误后如何处理？

自验证循环要求Agent不允许静默忽略错误。当步骤后验证失败时应依次尝试：自我校正（重新分析并修正当前步骤）→ 换策略重试 → 升级到人工确认 → 彻底中止并生成诊断报告。

④ 为何必须将生成者与评估者分离？

Anthropic的工程实践揭示了一个关键问题：大模型在评估自身产出时存在系统性乐观偏见。当要求Agent对自己生成的内容打分时，即便产出质量在人类观察者看来明显欠佳，模型也倾向于给出积极评价。更棘手的是，即使模型在评估过程中识别出了真实存在的问题，它也容易"自我说服"这些问题不算严重，最终仍然通过验证。

这一问题的工程解法受生成对抗网络（GAN）启发——将生成与评估分离为两个独立Agent：生成者Agent负责产出内容，评估者Agent负责批判性审查。分离本身并不能立即消除评估者的乐观倾向，但它使得单独针对评估者进行"偏向严格"的调优成为可能，而这比让生成者"批判自己的作品"在工程上要容易得多。

评估者的调优是一个迭代过程，需要反复审查评估日志、找出评估判断与预期存在偏差的具体案例，并迭代更新评估prompt。值得注意的是，有效的评估者还需具备主动探测能力——不能仅凭静态截图打分，而应像真实用户一样主动操作界面、调用API、验证边界条件，才能发现被动查看无法暴露的深层缺陷。

Claude Code 实践参考

Claude Code的智能体循环（Agentic Loop）本质上就是一个自然的自验证循环——执行工具、观察结果、调整策略，循环迭代直至任务完成：

plan模式作前置验证：切换到plan权限模式后，Claude Code只执行只读操作并生成完整执行计划，用户审批计划后方可推进，充当任务的"前置条件验证"关卡。
工具结果驱动验证：Claude Code在编写代码后会主动调用构建工具（go build、npm run build等）和测试工具（go test、pytest等）以验证变更正确性，将工具执行结果作为步骤后验证的依据。
错误自适应：当工具调用返回错误时，Claude Code不会静默跳过，而是根据错误信息调整策略重试，并在多次失败后主动向用户说明障碍并请求指引。
Hooks机制：通过Claude Code Hooks（如PostToolUse钩子），开发者可以在每次工具调用后自动触发验证脚本，将自定义验证逻辑硬编码进执行流程。

上下文隔离（Context Isolation）

核心理念：多Agent协作时，保持每个Agent上下文的纯净性，防止跨越边界的信息污染。

在多Agent架构（如协调者-执行者模式、流水线模式）中，上下文污染是可靠性的头号杀手。当一个Agent的内部状态、中间推理或错误信息渗漏到另一个Agent的上下文中时，会引发一系列难以调试的级联问题。

典型污染场景

Claude Code 实践参考

Claude Code通过SubAgents（子代理）和Agent Teams（代理团队）机制，在工具层面提供了上下文隔离能力：

SubAgents隔离：Claude Code可以通过runSubagent工具启动子代理执行特定任务。每个子代理拥有完全独立的上下文窗口，主代理只向子代理传入精简后的任务描述和必要参数，子代理的内部推理过程、中间状态和错误信息不会回流污染主代理上下文。
Agent Teams协作隔离：在代理团队模式下，多个专注特定领域的代理（如代码审查代理、测试代理、文档代理）各自维护独立上下文，通过结构化消息交接工作成果，而非共享原始会话历史。
记忆作用域隔离：session记忆（会话级）、user记忆（用户级）、repo记忆（仓库级）三个作用域天然隔离，不同会话之间的临时状态不会相互干扰。

熵治理（Entropy Governance）

核心理念：建立自维护机制，对抗Agent系统中上下文和状态的自然熵增趋势。

热力学第二定律告诉我们，孤立系统的熵（无序度）只会增加。Agent系统也不例外——随着任务执行，上下文不断积累，规则不断叠加，工具调用记录不断增长，系统状态越来越复杂，最终变得难以预测和维护。

熵治理的目标是建立自维护的闭环机制，让系统能够定期清理、压缩、重组自身状态，保持长期健康。

熵的来源分析

上下文熵增的来源：
  - 持续累积的对话历史
  - 工具调用轨迹与中间结果
  - 随时间叠加的矛盾指令
  - 死亡状态引用（已不存在的任务）
  - 大量重复信息挤占上下文空间

熵治理的设计方法

熵治理需要建立系统性的"清洁维护"机制，类似于数据库的定期VACUUM操作，保持系统状态的持续整洁。

上下文蒸馏设计

上下文蒸馏是熵治理最核心的手段，其设计原则是：保留决策结论，丢弃推理过程。蒸馏时应明确区分需要保留和可以丢弃的信息：

关键检查点设计

在Agent系统设计阶段应预先规划"熵控检查点"，即阶段性任务边界在完成时自动触发以下清理动作：

将当前阶段的核心结论压缩写入"阶段摘要"区域
清空该阶段产生的所有中间工具调用记录
将有价值的领域知识（非任务相关）写入外部持久知识库
重置内部状态至干净的初始形态，为下一阶段准备

Claude Code 实践参考

Claude Code的记忆体系是熵治理思想的直接落地——通过分层记忆机制和自维护闭环，对抗上下文熵增：

自动记忆写入（Auto Memory）：这是Claude Code最具代表性的熵治理手段。当Claude Code在协作过程中发现有价值的信息（如项目构建命令、调试技巧、用户偏好纠正等），会自动将其写入/memories/持久化，让宝贵经验跨会话沉淀，避免每次会话从零开始。
/compact命令：手动触发上下文蒸馏。执行后Claude Code会将当前对话中的关键决策和状态压缩为结构化摘要，替换冗长的历史交互，释放上下文空间的同时保留核心知识。
CLAUDE.md的/init更新：/init命令不仅可创建CLAUDE.md，也可定期重新分析项目结构并更新，相当于对项目知识进行"重新蒸馏"，清理过时的描述和失效的规则。
记忆分层归档：session记忆在会话结束后自动失效（天然熵清理），user记忆和repo记忆作为持久层长期积累高价值知识，形成自然的信息过滤机制。

可拆卸性（Detachability）

核心理念：以模块化设计构建Harness系统，使其能够随着模型的迭代进化而优雅适配。

AI模型迭代速度极快。今天针对GPT-4.5精调的Harness系统，明天可能需要适配Claude 4.5的能力特性，后天又需要对接开源模型。如果Harness与特定模型深度耦合，每次模型更换都意味着大规模重构。

可拆卸性原则要求将Harness系统中与模型强相关的部分设计为可插拔的适配层。

可拆卸性架构

可拆卸性的工程落地方法

实现可拆卸性的核心工程手段是在Harness核心层与模型适配层之间建立明确的接口契约，确保模型相关的适配逻辑不渗透进业务层。

具体落地时，建议将Harness系统明确分为三个层次，并为每个层次建立独立的配置、部署和演进机制：

关键实践：将prompt模板从代码中外置为独立的配置文件（YAML/TOML格式），每个模型对应一套模板配置，切换模型时只需切换配置文件，无需修改业务逻辑。

Claude Code 实践参考

Claude Code的整个配置体系设计本身就是可拆卸性原则的体现——指令、技能、规则均以独立文件形式存在，与底层模型版本解耦：

Skills系统（SKILL.md）：技能文件完全独立于模型实现，定义的是"处理某类任务应遵循的专家流程"，而非绑定特定模型的prompt技巧。当Claude模型升级时，Skills文件无需修改即可继续生效，是可拆卸性的最佳实践。
指令文件体系：CLAUDE.md、.instructions.md、Rules规则文件均以Markdown纯文本存储，完全独立于Claude Code的运行时。这意味着工程规范可以版本化管理（Git追踪），随时迁移、复用到不同项目或不同的AI工具中。
SubAgents模块化：子代理通过声明式配置定义其职责和工具集，与主代理松耦合。当某个子代理需要升级或替换策略时，只需修改其配置文件，不影响其他代理和整体系统。
MCP工具解耦：外部能力通过MCP（Model Context Protocol）标准协议接入，工具能力与Claude Code主体完全解耦。新增或替换工具时只需调整MCP配置，主体Agent无需变动。