1. 什么是Harness:AI模型的控制系统
1.1 从马具到AI控制
Harness这个词最初指的是马具——包括缰绳、鞍具、嚼子等整套装备。这个比喻非常形象:就像马具用来驾驭一匹强大但不可预测的马匹,Harness在AI领域就是用来控制和引导强大但不可预测的AI模型的一套系统。
这个类比中:
- 马 = AI模型:拥有强大的能力,速度快,但自己不知道应该往哪个方向走
- 马具 = Harness:提供引导、约束,使AI的力量变得可控且有明确方向
1.2 技术定义解析
在技术层面,我们可以这样定义:
Agent = Model + Harness
换句话说,一个裸模型本身并不是一个完整的Agent。只有当它被Harness包裹,获得了状态管理、工具执行能力、反馈机制和可执行的约束条件后,才能真正成为一个可用的Agent。
以编程Agent为例:
coding agent = AI模型 + harness
其中Harness包含以下关键组件:
- 系统提示(System Prompt/AGENTS.md):定义Agent的行为准则
- 工具、Skills和MCP(模型上下文协议)及其描述
- 基础设施绑定(文件系统、沙箱环境、浏览器等)
- 编排逻辑(子Agent生成、任务交接、模型路由等)
- Hooks/中间件(上下文压缩、续行、lint检查等确定性执行逻辑)
1.3 操作系统类比
我们可以用计算机架构来类比理解Harness的作用:
AI模型本质上接受文本、图像等输入并输出文本,仅此而已。开箱即用的模型无法做到:
- 跨交互维护持久状态
- 执行代码
- 访问实时知识
- 搭建环境和安装依赖来完成工作
这些都是Harness层面的功能。大型语言模型(LLM)的结构决定了需要某种将其包裹起来的机制才能完成有用的工作。
2. Harness Engineering的核心概念
2.1 定义与起源
Harness Engineering这个概念由Vivek Trivedy(Viv)首创,描述了利用Harness的各个配置点来定制和提升编程Agent输出质量与可靠性的实践。Mitchell Hashimoto(Terraform、Ghostty等工具的创建者)在2026年正式命名了这一术语。
他的定义是:"每当你发现Agent犯了一个错误,你就花时间工程化一个解决方案,使Agent永远不再犯同样的错误。"
核心问题不是"如何让模型更聪明",而是"如何从今天的模型中获得最大收益"。
2.2 与Context Engineering的关系
Harness Engineering是Context Engineering的子集:
- Context Engineering(由Dex在12-factor agents中首次提出)是"prompt engineering"及多种系统性提升AI agent可靠性技术的超集
- Harness Engineering主要涉及利用harness配置点来精心管理编程agent的上下文窗口
它回答的关键问题包括:
- 如何赋予编程Agent新能力?
- 如何向它传授训练数据中没有的代码库知识?
- 如何在关键操作之外增加确定性?
- 如何防止上下文窗口膨胀或充斥无效上下文?
3. Harness Engineering的演进历程
3.1 技术范式的转变
我们可以观察到从LLM API到Harness API的演进:
LLM API(对话式端点) → Harness API(可定制的运行时)
这一转变反映了三个重要趋势的汇聚:
趋势一:模型商品化。Claude、GPT、Gemini等主流模型在标准基准测试上的表现已经非常接近。竞争优势不再是模型本身,而是模型周围的系统。
趋势二:Agent从Demo走向生产。2025年大多数Agent部署还是概念验证;2026年组织已在部署处理客户交互、编写生产代码、管理基础设施的Agent。可靠性标准从"令人印象深刻的Demo"变成了"不能宕机"。
趋势三:基准测试不再衡量真正重要的东西。标准基准衡量单轮任务完成率,但生产Agent运行数小时甚至数天。
3.2 工程思维的转变
许多团队面对Agent失败时的第一反应是:
- "等GPT-6就好了"
- "等指令遵循能力更好就好了"
- "等我用的小众库进了训练数据就好了"
但实践经验表明:这通常不是模型问题,而是配置问题。
模型确实会变得更聪明,某些失败模式会消失。但也正因为更聪明了,我们会赋予它们更大、更难的新问题,而它们将继续以意想不到的方式失败。意外失败模式是非确定性系统的根本性问题。
3.3 HaaS(Harness as a Service)的兴起
Viv提出了HaaS(Harness as a Service)的概念——通过丰富的Agent Harness生态系统,快速构建、定制和共享Agent。Claude Code SDK是这一范式的典型代表:其现有Harness可通过用户自己的提示、工具、上下文和权限轻松扩展,用户获得了一个开箱即用、可定制的Agent运行时。
4. Harness Engineering的六大杠杆
Viv最初提出了四个核心定制杠杆,后来HumanLayer团队在实战中补充了两个。
4.1 杠杆一:系统提示(System Prompt)
系统提示是最直接的配置点。以AGENTS.md或CLAUDE.md文件为载体,定义Agent的行为准则、编码规范、项目结构等。
关键洞见:上下文是稀缺资源。一个巨大的指令文件会挤占任务、代码和相关文档的空间。不要把AGENTS.md当作百科全书,把它当作目录,真正的知识库放在结构化的docs/目录中。
4.2 杠杆二:工具/MCP
Agent通过工具与外部世界交互。MCP(Model Context Protocol)提供了标准化的工具接口。
工具设计的三个关键问题:
- Agent需要做什么才能实现目标?是否有对应的工具?
- Agent是否清楚何时使用这些工具?
- 能否通过合并多个工具为更原子化的结果来减少出错面?
工具不仅扩展能力,更是反馈机制。自定义linter错误消息同时充当修复指令——工具在Agent工作时教育Agent。
4.3 杠杆三:上下文(Context)
给Agent的上下文越好,表现越好。关键上下文类型包括:
- 代码文档和片段:保存为文件系统中的Markdown文件
- 记忆/用户个性化:将相关信息注入记忆文件或使用记忆服务
- 最新知识:通过Web搜索和Context7等MCP工具访问超出知识截止日期的信息
经验法则:将所有关键上下文放在系统提示中,将其他有用上下文放在Markdown文件中并告知Agent何时及如何使用。
4.4 杠杆四:Sub-agents
Sub-agents通过YAML在.claude/agents/{name}.md中定义,解决两个核心问题:
- 专业化——让不同的Sub-agent专注于特定任务
- 并行化——在隔离的上下文窗口中并行执行多个任务
核心价值:上下文防火墙。Sub-agents确保离散任务在隔离的上下文窗口中运行,中间噪声不会积累到负责编排的父线程中。
4.5 补充杠杆一:Hooks
Hooks提供确定性控制流,用于自动化集成。典型用途包括:
- Pre-commit hook:运行linter、类型检查
- Stop hook:覆盖率下降时提示Agent提升覆盖率
- 成功时完全静默(不占用上下文),失败时只暴露错误信息
4.6 补充杠杆二:Skills
Skills解决了一个关键问题:Agent启动时过多工具或MCP server被加载进上下文,导致上下文腐烂(context rot)。
Skills通过渐进式披露(progressive disclosure)解决这个问题——不在启动时加载所有指令,而是在Agent需要时才按需加载相关知识模块。
5. 企业级Harness Engineering实践案例
5.1 Stripe Minions:大规模编程Agent系统
背景:Stripe的代码库包含数亿行代码,主要用Ruby(配合Sorbet类型系统),每年处理超过1万亿美元支付。Minions属于"无人值守Agent",每周负责超过1,300个PR的合并。
5.1.1 反馈左移(Shift Feedback Left)架构
Stripe构建了分层的反馈架构:
- Pre-push Hooks(预推送钩子):基于启发式规则自动运行相关linter,自动修复常见问题,耗时<1秒
- 本地Linting(后台守护进程):预计算并缓存适用规则,耗时<5秒
- CI选择性测试:从3,000,000+个测试中智能选择子集运行,已知失败模式→自动修复器自动处理
关键设计:最多两轮CI(at most two CI rounds)。这个上限是刻意为之的,因为LLM在反复重试同一问题时收益递减。
5.1.2 Blueprints(蓝图)——混合编排机制
蓝图将确定性代码节点与自由流动的Agent子任务混合在一起:
- 方形节点为确定性节点(如运行linter、推送分支)
- 圆形节点为Agent循环节点(如理解任务、编写代码)
这种分离至关重要:某些任务永远不应该留给Agent的判断,确定性节点可以节省token、减少错误、保证关键步骤每次都发生。
5.2 OpenAI:百万行代码零人工实验
实验概况:
- 3名工程师(后扩展到7人)驱动Codex
- 5个月内产出约100万行代码
- 约1,500个PR被开开并合并
- 人均每天3.5个PR
- 全程零人工编写代码
5.2.1 架构即护栏(Architecture as Guardrails)
OpenAI团队强制执行了一个严格的分层架构:
- 每个业务领域被划分为固定的层次集合
- 依赖方向经过严格验证,允许的边数量有限
- 通过自定义Linter和结构性测试以机械方式强制执行
这种"迂腐的规则"对Agent反而是倍增器:规则一次编写,永久生效,在所有Agent会话中同时作用。
5.2.2 工具即反馈(Tools as Feedback)
OpenAI最精妙的设计:自定义linter错误消息同时充当修复指令。这创造了一个零人工干预的紧密反馈回路:
- Agent写代码
- 自定义Linter运行
- 发现架构违规
- 错误消息=修复指令(注入Agent上下文)
- Agent按指令修复
- Linter再次运行
- 通过
6. Harness Engineering实践手册
Charlie Guo在《正在形成的Harness Engineering实践手册》中总结了跨组织的共同规律:
6.1 两部分工作
Harness Engineering有两个互相交织的部分:
- 构建环境:当Agent卡住时,将其视为环境设计问题
- 管理工作:在执行之前与Agent进行大量规划,担任架构的"仁慈独裁者"
6.2 四大反复出现的实践
- 架构即护栏(Architecture as Guardrails):Agent在拥有严格边界和可预测结构的环境中最为高效
- 工具既是地基也是反馈(Tools as Foundation and Feedback):维护团队依赖的工具列表,确保对Agent可访问
- 文档即记录系统(Documentation as System of Record):AGENTS.md作为目录,docs/目录作为知识库
- 每个团队需要一个Agent负责人(Agents Captain):指定负责思考Agent如何融入团队工作流的人
6.3 实践中的Do's和Don'ts
有效的做法:
- 偏向交付,只在Agent实际失败时才添加配置
- 设计、测试、迭代——并丢弃无用的东西
- 通过仓库级配置将经过实战检验的配置分发给整个团队
- 优化迭代速度,而非"第一次尝试就一击中的概率"
无效的做法:
- 在还没遇到真实失败之前就试图设计理想的Harness配置
- 以"以防万一"的心态安装几十个Skills和MCP Servers
- 在每个Agent会话结束时运行完整的测试套件(超过5分钟)
- 试图微观优化哪些Sub-agents可以访问哪些工具
7. Agent Harness的组件解剖
Viv从模型原生无法做到的事情反推Harness每个组件存在的原因:
7.1 反推逻辑
核心方法论:我们期望的Agent行为 → 帮助模型实现这一目标的Harness设计
| 期望行为 | 模型的原生局限 | Harness解决方案 |
|---|---|---|
| 持久存储与上下文管理 | 模型只能操作上下文窗口内的知识 | 文件系统抽象 + 文件操作工具 |
| 自主解决问题 | Harness只能执行预配置的工具 | Bash + 代码执行(通用工具) |
| 安全执行与核验 | 本地运行Agent代码有风险 | 沙箱 + 验证工具 |
| 记忆与搜索 | 模型除权重和当前上下文外无额外知识 | AGENTS.md + Web搜索 + MCP |
| 对抗上下文腐烂 | 上下文填满后推理能力退化 | 压缩(Compaction)、输出卸载、Skills渐进式披露 |
| 长周期自主执行 | 过早停止、跨窗口不连贯 | Ralph Loop + 规划 + 自我验证 |
7.2 文件系统:最基础的Harness原语
文件系统是最基础的Harness原语,因为它解锁了:
- Agent获得了读取数据、代码和文档的工作空间
- 工作可以增量添加和卸载,不必把一切保存在上下文中
- 文件系统是天然的协作界面,多个Agent和人类可以通过共享文件协调
7.3 上下文腐烂的三重防线
- 上下文压缩(Compaction):智能卸载并总结现有的上下文窗口
- 工具调用输出卸载:保留超出token阈值的工具输出的头尾,将完整输出卸载到文件系统
- Skills渐进式披露:避免启动时将过多工具描述加载进上下文
8. 面向编程Agent的Harness Engineering
HumanLayer团队提供了面向编程Agent构建者的战术工具箱。
8.1 Harness组件全景
编程Agent的Harness包含以下可配置层次:
- Agentfile(AGENTS.md/CLAUDE.md):行为准则和编码规范
- MCP Servers:外部工具集成
- Skills:渐进式知识披露模块
- Sub-agents:专业化和并行化的上下文防火墙
- Hooks:确定性控制流(pre-commit、stop等)
- 反压机制(Backpressure):验证Agent工作的反馈回路
8.2 反压机制(Backpressure)提升成功率
反压机制指的是让Agent在完成工作后能自动检验其产出质量、并在不合格时被迫回头修正的反馈回路。
好的反压机制遵循三条原则:
- 成功时静默——通过的测试、成功的构建不应向上下文注入任何信息
- 失败时精准——只暴露错误信息,且尽可能包含修复指引
- 运行要快——反压太慢(如完整测试套件跑5分钟以上)就失去了在Agent循环中嵌入的价值
8.3 构建者的核心原则
"下次你的编程Agent表现不如预期时,在责怪模型之前,先检查一下Harness。模型可能没问题,只是技能问题(It's just a skill issue)。"
9. 面向编程Agent用户的Harness Engineering
Birgitta Böckeler将控制论(Cybernetics)框架引入Harness Engineering,建立了完整的理论体系。
9.1 三层同心圆
"Harness"一词在不同限界上下文中含义各异:
- 最内层:模型——被套上Harness的终极对象
- 中间层:构建者Harness——编程Agent产品内置的系统提示、编排、检索机制等
- 最外层:用户Harness——我们(使用者)针对自身用例和系统构建的外部Harness
9.2 前馈(指引)与反馈(传感器)
为编程Agent套上Harness的核心机制:
- 指引(前馈控制,Feedforward)——预测Agent的行为,力求在其行动之前加以引导
- 传感器(反馈控制,Feedback)——在Agent行动之后进行观察,帮助其自我纠正
单独使用其中一种会产生问题:仅有反馈则Agent会不断重蹈覆辙;仅有前馈则Agent编码了规则却永远无从验证它们是否生效。
9.3 计算型 vs. 推断型
指引和传感器各有两种执行类型:
| 类型 | 计算型(Computational) | 推断型(Inferential) |
|---|---|---|
| 执行主体 | CPU | GPU/NPU(LLM) |
| 特点 | 确定性、快速 | 语义分析、更慢更贵 |
| 示例 | Linter、类型检查、测试 | AI代码评审、LLM-as-judge |
| 可靠性 | 结果可靠 | 具有非确定性 |
9.4 三种监管类别
- 可维护性Harness——调节内部代码质量
- 架构适应性Harness——定义和检查应用架构特性
- 行为Harness——确保应用按需运作(目前最具挑战性)
9.5 人类的角色
"一个好的Harness不一定要完全消除人类的介入,而是要将介入引导到我们的输入最重要的地方。"
人类开发者将自身的技能与经验作为隐式Harness带入每个代码库。编程Agent不具备社会责任感,对代码质量没有审美厌恶感,也没有组织记忆。Harness是将人类经验外化和显式化的一种尝试。