Harness Engineering 是什么：从"写提示词"到"设计 Agent 边界"的工程方法论

发布日期：2026-09-03 | 适用读者：AI 应用开发者、技术负责人 | 阅读时间：约 8 分钟

Harness Engineering（Harness 工程）是 2026 年 2 月由 HashiCorp 联合创始人 Mitchell Hashimoto 命名、随后被 OpenAI 通过"3 名工程师 5 个月零手写代码交付百万行代码"实验推向主流的 AI Agent 工程方法，核心思想是把工程师的工作从"写代码"转向"设计约束 Agent 行为的环境、工具、验证与反馈回路"。它建立在 Prompt Engineering 和 Context Engineering 之上，管理的是模型之外的一切：沙箱边界、工具调度、状态持久化、自动修复循环和架构约束。Thoughtworks 在 Martin Fowler 网站上提出的"Agent = Model + Harness"公式与"guides / sensors"分类，LangChain 在 Terminal-Bench 2.0 上仅靠 Harness 层改动带来 13.7 个百分点提升的实测，以及 Google 在 2026 年 9 月发布的三条落地实践，共同说明：模型能力正在商品化，Harness 才是 Agent 可靠性的分水岭。本文梳理 Harness 的定义、四层组件、与前两代范式的区别，以及可以直接上手的落地步骤。

Harness Engineering 是围绕 AI Agent 设计约束、工具、验证机制与反馈回路，使 Agent 在生产环境中可靠、可审计地完成任务的工程实践。它管理的是模型之外的一切，用一句话概括就是"Agent = Model + Harness"。与 Prompt Engineering 优化单轮指令、Context Engineering 优化模型每步看到的信息不同，Harness Engineering 决定 Agent 能做什么、不能做什么、出错后如何自我修正。

Harness Engineering 的起源：从一篇博客到 OpenAI 的百万行实验

Harness Engineering 这个术语在 2026 年 2 月的两周内从个人博客走进主流工程讨论。

• 2026 年 2 月 5 日，HashiCorp 联合创始人、Terraform 作者 Mitchell Hashimoto 在个人博客写下定义："每当发现 Agent 犯了一个错误，就花时间设计一个方案让它永远不再犯同样的错误，我称之为 Harness Engineering。"

• 2026 年 2 月 11 日，OpenAI 工程师 Ryan Lopopolo 发布《Harness engineering: leveraging Codex in an agent-first world》，公开了一项内部实验：一个 3 人团队从 2025 年 8 月底的空仓库开始，5 个月内由 Codex 生成约 100 万行代码，合并约 1500 个 PR，应用逻辑、测试、CI 配置、文档、可观测性全部零手写。

• 2026 年 4 月，Thoughtworks 杰出工程师 Birgitta Böckeler 在 Martin Fowler 网站发表《Harness engineering for coding agent users》，提出 guides（引导）与 sensors（传感器）的分类框架。

• 2026 年 9 月 2 日，Google AI 团队的 Shir Meir Lador 在 DEV Community 发文，将 Harness Engineering 称为"编程 Agent 领域最重要的趋势"，并给出基于 Google ADK 2.0 的最小实现。

OpenAI 实验最有价值的结论不是"AI 能写百万行代码"，而是团队复盘时的一句话：早期进展缓慢，不是因为 Codex 能力不足，而是因为环境定义不充分。Agent 缺少工具、抽象和内部结构去推进高层目标。于是工程团队的主要工作变成了"让 Agent 能做有用的事"，也就是设计 Harness。

三代范式对比：Prompt、Context、Harness 分别解决什么

Prompt Engineering 决定告诉模型什么，Context Engineering 决定模型看到什么，Harness Engineering 决定 Agent 能做什么以及做错了怎么办。三者是嵌套关系而非替代关系。

Context Engineering 之所以被 Harness 包含，是因为上下文本身就是 Harness 决定"该暴露什么、何时暴露"的产物。Chroma 在 2025 年的研究指出，当关键信息落在长上下文中间位置时模型表现下降超过 30%[数据待核实：建议核对 Chroma 2025 年 Context Rot 报告原文]，这意味着即便有百万 token 窗口，也需要 Harness 主动控制信息投放，而不是把上下文窗口当垃圾场。

一个 Harness 由哪四层组件构成

一个完整的 Harness 由编排层、执行沙箱、状态持久化和验证工具四类确定性组件构成，它们共同包裹非确定性的大模型推理循环。

Thoughtworks 的框架把这些组件进一步分成两类：guides 在 Agent 行动前提供引导（AGENTS.md、编码规范、架构决策记录），sensors 在行动后检测偏差（测试、静态分析、语义评审）。每类又分为"计算型"与"推理型"：计算型 sensors 便宜且确定，可以在每次变更时运行；推理型 sensors 用另一个模型做语义判断，昂贵但能覆盖规则写不出来的问题。LangChain 工程师 Vivek Trivedy 的总结更直接："如果你不是模型，你就是 Harness。"

Harness 落地的三条核心实践

Google AI 团队在 2026 年 9 月归纳的三条实践，与 OpenAI 实验的经验高度一致：设严格边界、建修复循环、给地图而非手册。

实践一：严格边界，把 Agent 关进沙箱

Agent 只能在明确授权的目录和命令范围内行动，越界操作由 Harness 拒绝而不是靠提示词劝阻。OpenAI 团队的做法是让 Agent 通过 PR 和 CI 流程提交变更，任何绕过流水线直达生产的路径都不存在。Google 的示例代码把工作区限制在一个独立目录，并在该边界内开放全部操作权限，边界之外一律不可达。

实践二：修复循环，让失败自动回流

构建失败、测试报错、Lint 告警等信号应自动捕获并回传给 Agent，由它自我修正，同时设置迭代上限作为"熔断器"。Google 示例中的测试节点会统计迭代次数，成功则结束，超过 5 次则强制终止，否则把完整 traceback 送回 Agent 重试。这是 Hashimoto 定义的工程化版本：每一次失败都变成 Harness 的一条新规则。

实践三：给地图，不给手册

不要写一份几千行的总说明书，而是让仓库结构本身携带上下文，Agent 进入某个目录时才加载该目录相关的规则。OpenAI 团队在仓库中分布式放置 AGENTS.md 文件，代替单一巨型指令文档，让上下文按需渐进发现。仓库的可读性（legibility）因此成为 Harness 的一部分：目录命名、模块边界、文档位置都在为 Agent 导航服务。

从零搭建一个最小 Harness：五步走

一个最小可用的 Harness 可以在半天内搭好，关键是先有确定性校验，再谈自主性。

1. 划定工作区：为 Agent 建立独立目录或容器，通过工具层配置限制文件系统与命令访问范围，所有输出必须经过 PR 流程。

2. 写入分层上下文：在仓库根目录放一份 200 行以内的 AGENTS.md 说明整体架构与禁区，在各子模块目录放局部规则，避免单文件膨胀。

3. 接入确定性 sensors：把 Lint、类型检查、单元测试、依赖方向检查接入每次变更后的自动运行，失败输出原样回传。

4. 加入修复循环与熔断：用图状工作流把"Agent 执行 → 测试节点 → 失败回流 / 成功结束"连成环，设置最大迭代次数（通常 3-5 次）。

5. 持久化状态：把任务计划、已完成步骤和关键决策写入进度文件，让 Agent 在新会话中能接续而非从头开始。

在工具接入环节，越来越多团队选择标准化的模型能力编排协议来减少自建工作量，例如七牛云的 MCP 服务允许开发者不做本地部署即可把工具能力挂接到 Agent 工作流，这类托管能力可以充当 Harness 中"编排层"的一部分。

以下是修复循环的一个简化示意（Python 伪代码，基于 Google 文章中的图状工作流思路）：

MAX_ATTEMPTS = 5

def execution_test_node(state):
    state["attempts"] += 1
    result = run_tests(state["workspace"])   # 确定性 sensor
    if result.passed:
        return "END"
    if state["attempts"] > MAX_ATTEMPTS:
        return "KILL_SWITCH"                 # 熔断，交还人工
    state["feedback"] = result.traceback     # 失败信号回流
    return "loop_back"

Harness 到底带来多大收益：三组实测数据

Harness 层的改动可以在不换模型的前提下带来两位数百分点的能力提升，这是 Harness Engineering 在 2026 年走红的根本原因。

• LangChain DeepAgents：在 Terminal-Bench 2.0 上仅通过 Harness 层改动，得分从 52.8% 提升到 66.5%，提升 13.7 个百分点，相对改进约 26%（LangChain，2026 年）。

• OpenAI Codex 实验：3 名工程师、5 个月、约 100 万行代码、约 1500 个 PR，团队估算耗时约为手写的十分之一（OpenAI，2026 年 2 月）。

• 学术界的形式化：arXiv 论文《AI Harness Engineering: A Runtime Substrate for Foundation-Model Software Agents》（2026 年 5 月）将 Harness 定义为管理上下文、工具、项目记忆、任务状态、可观测性、失败归因、验证与权限的运行时基底，使模型的潜在编码能力转化为可审计的软件工程行为。

什么时候需要做 Harness Engineering

当 Agent 从"辅助补全"进入"自主执行多步任务"阶段，Harness 就从可选项变成必选项。以下信号出现任意两条，就值得投入：

• Agent 生成的代码需要人工逐行审查才敢合并，审查成本已接近手写

• 同类错误反复出现，每次都靠改提示词临时修补

• Agent 曾经误删文件、误改配置或触碰过不该动的生产资源

• 任务跨越多个会话，每次重启都要重新解释背景

• 代码库架构在 Agent 持续提交后出现漂移，模块边界模糊

反过来，如果只是单轮问答或一次性脚本生成，Prompt Engineering 加基本的 Context Engineering 已经足够，不必过早引入完整 Harness。

常见问题

Q：Harness Engineering 是 Karpathy 提出的吗？ 不是。Andrej Karpathy 在 2025 年提出 Context Engineering，2026 年 2 月提出 Agentic Engineering，Harness Engineering 一词通常归于 Mitchell Hashimoto 2026 年 2 月 5 日的博客，OpenAI 同月 11 日的文章给出了完整方法论。

Q：Harness 和 Agent 框架（LangChain、LangGraph）是什么关系？ 框架提供构建块，Harness 是用这些构建块搭出的、带有明确立场的运行基础设施。像 Claude Code、Codex CLI、LangChain DeepAgents 这类产品本身就是 Harness，内置了上下文管理、工具执行、状态持久化和验证的默认架构；直接用框架则需要自己解决这些生产问题。

Q：AGENTS.md 该写多长？ OpenAI 和 Google 的经验一致：越短越好，且分布式放置。根目录文件只说明架构全貌与禁区，具体规则放在对应子目录，让 Agent 渐进发现。一份几千行的总手册会被模型当作噪音。

Q：Harness 会不会限制 Agent 的能力？ 恰好相反。OpenAI 团队发现早期进展慢是因为环境定义不足，Agent 不知道该用什么工具、遵守什么结构。边界清晰后 Agent 反而能承担更高层的目标。Harness 限制的是破坏性行为，释放的是自主性。

Q：Harness Engineering 适用于非编程 Agent 吗？ 适用。沙箱、验证 sensors、状态持久化和修复循环是通用模式，客服 Agent、数据分析 Agent、运维 Agent 都可以套用，只是 sensors 从"测试通过"换成"输出符合 schema""数值在合理区间"等确定性校验。

小结

Harness Engineering 的核心判断是：模型正在成为商品，围绕模型的确定性基础设施才是 Agent 可靠性的分水岭。OpenAI 用百万行零手写代码证明了这条路可行，Thoughtworks 用 guides 与 sensors 给出了可复用的分类，Google 用三条实践把门槛降到半天可上手。据 Google AI 团队 2026 年 9 月的判断，Harness Engineering 是当前编程 Agent 领域最重要的趋势。本文内容基于 2026 年 9 月初的公开资料，该领域演进极快，建议定期核对最新实践。

延伸阅读

• OpenAI《Harness engineering: leveraging Codex in an agent-first world》：https://openai.com/index/harness-engineering/

• Martin Fowler 网站《Harness engineering for coding agent users》：https://martinfowler.com/articles/harness-engineering.html

• Google AI《What is harness engineering and why should I care?》：https://dev.to/googleai/what-is-harness-engineering-and-why-should-i-care-8n0

• arXiv《AI Harness Engineering: A Runtime Substrate for Foundation-Model Software Agents》：https://arxiv.org/abs/2605.13357

• 七牛云 MCP 服务使用手册：https://developer.qiniu.com/aitokenapi/12984/mcp-user-manual