Harness Engineering：为什么模型很强，Agent 还是经常做不稳？

过去，大家遇到 AI 输出不理想，第一反应是把提示词再写长一点；Agent 出现后，工程师又开始研究怎样把检索结果、记忆和工具说明塞进上下文。可到了真正的长链路任务里，提示词和上下文都没有明显问题，Agent 依然会忘目标、重复劳动、提前宣布完成、误用工具，甚至把错误模式一遍遍复制进代码库。

Harness Engineering 解决的正是这一层问题：它不再只优化模型“看到什么”，而是设计模型周围的运行环境，让 Agent 能够规划、执行、观察、验证、恢复，并把每次失败沉淀为下一次可复用的系统能力。

图 1 Prompt、Context 与 Harness 的控制范围逐层扩大

一、这个概念从哪里来？

2026 年 2 月，Mitchell Hashimoto 在《My AI Adoption Journey》中把自己长期使用编码 Agent 的方法称为“harness engineering”。他的核心做法很直接：每当 Agent 犯一次错误，就花时间把解决方案工程化，让同类错误以后不再依赖人类临时提醒。可能是补一条仓库规则，也可能是新增 Lint、自动化测试、Git Hook 或验证工具。

几天后，OpenAI 发布 Codex 团队的官方复盘，把 Harness Engineering 推向更广泛的工程讨论。OpenAI 报告称，一个小团队从空仓库开始，让 Codex 生成应用代码、测试、CI、文档、可观测性和内部工具；五个月后仓库规模约 100 万行，期间约有 1,500 个 PR 被创建并合并。这里真正重要的不是“AI 写了多少行代码”，而是人类工程师把工作重心转向了环境设计、意图描述和反馈回路。

图 2 OpenAI Codex 团队公开的 Harness 实验数据

二、Harness 到底是什么？

LangChain 给出了一个很容易记住的表达：Agent = Model + Harness。模型负责推理和生成；模型之外的系统提示词、工具描述、文件系统、沙箱、浏览器、状态管理、子 Agent 编排、上下文压缩、Lint、测试和恢复逻辑，都属于 Harness。

图 3 模型只是 Agent 的“大脑”，Harness 才让它真正拥有工作能力

因此，Harness 不是某一个 SDK，也不是把 ReAct 循环写出来就结束。它更像是一套运行时：决定 Agent 在哪里执行、能访问什么、怎样找到知识、如何保存进度、什么时候重试、如何证明任务完成，以及什么情况下必须停下来找人。

图 4 生产级 Harness 的八层工程能力

三、Harness Engineering 的核心不是“约束 AI”，而是“让错误形成复利”

最容易犯的错误，是每次都只修当前结果。例如 Agent 漏跑测试，人类提醒一句“下次记得测试”；Agent 又违反架构边界，再补一句“请遵循分层设计”。这些提醒只能影响当前会话，一旦上下文结束，团队又回到原点。

Harness 的思路是把失败变成系统改造信号：漏跑测试，就把测试纳入完成门槛；误用 API，就提供可搜索的版本化文档；越权访问，就通过权限层直接拒绝；重复产生同类坏代码，就把规则写成结构测试或 Lint。这样每一次失败都会增强环境。

图 5 从“修一次结果”转向“永久修复环境”

四、第一块地基：把仓库知识变成可读取、可验证的事实库

OpenAI 最早也尝试过把所有规范都写进一个巨大的 AGENTS.md，但很快发现四个问题：它挤占任务上下文；规则太多后没有重点；内容容易过时；单个大文件很难做完整性和新鲜度检查。

他们后来把 AGENTS.md 控制在大约 100 行，让它承担“目录”的作用；真正的架构、产品规格、执行计划、质量标准、安全要求和生成式事实都放进结构化 docs/ 目录，并把仓库内版本化文档视为 System of Record。Agent 先读短入口，再根据任务按需深入。

图 6 AGENTS.md 做地图，docs/ 做事实库

图 7 渐进式披露：只把当前任务真正需要的信息送进上下文

AGENTS.md 应该写什么？

一个实用的 AGENTS.md 不需要复制 README、代码风格手册和所有框架文档。它更适合保留仓库入口、强制命令、核心边界、资料索引和高风险禁区。能够被格式化工具或 Lint 自动检查的内容，不要再用长篇自然语言重复。

# AGENTS.md
## 开始工作前
- 先阅读 docs/ARCHITECTURE.md 和相关 product-spec
- 使用 `make test-fast` 验证本地改动
- 涉及数据库变更时，先阅读 docs/DB-MIGRATION.md
## 强制边界
- controller 不得直接访问 repository
- 所有外部输入必须经过 schema 校验
- 禁止在日志中输出 token、手机号和身份证号
## 完成标准
- 相关测试通过
- 新行为补充验收用例
- 复杂任务更新 docs/exec-plans/active/ 下的进度记录

五、第二块地基：规则必须从“建议”升级为“机械约束”

文档可以解释为什么这样设计，却不能保证 Agent 每次都遵守。OpenAI 的实践是把关键边界写进自定义 Lint 和结构测试，例如限制依赖方向、统一结构化日志、约束 Schema 命名、限制文件大小，并对平台可靠性要求做静态检查。

更值得学习的是错误信息设计：一个面向 Agent 的 Lint 不只返回“校验失败”，还会告诉它违反了哪条不变量、应该阅读哪份文档、建议怎样修复。错误输出本身也成为下一轮上下文的一部分。

图 8 文档解释意图，机械约束守住边界

六、第三块地基：建立“写完—运行—观察—修复”的自验证闭环

Agent 最危险的状态不是不会写，而是无法看到真实结果。没有测试、日志、浏览器和截图，它只能根据代码外观猜测任务是否完成。生产级 Harness 应当让 Agent 使用与工程师相同的工具：执行测试、启动应用、操作页面、读取日志、查看截图、复现 Bug，并在结果不符合验收标准时继续修复。

图 9 自验证闭环让 Agent 从“生成答案”升级为“交付结果”

OpenAI 的 Codex 实验中，一个成熟运行可以复现 Bug、录制失败视频、实现修复、驱动应用验证、录制修复后视频、创建 PR、回应 Review、修复构建失败，并只在需要主观判断时升级给人类。官方同时强调，这种自治能力高度依赖仓库已有的结构和工具，不能简单复制到一个没有 Harness 投资的新项目。

七、长任务最大的敌人：上下文耗尽和“接班失忆”

复杂项目通常无法在一个上下文窗口里完成。Anthropic 把这个问题比作工程师轮班：每位新工程师上岗时都不记得上一班发生了什么。如果状态只存在聊天记录里，下一轮 Agent 就会重复探索、误判进度，甚至把未完成的项目提前宣布为完成。

Anthropic 提出的基础方案由两类会话组成：第一次由 Initializer Agent 创建运行脚本、功能清单、进度文件和 Git 初始状态；后续 Coding Agent 每轮只选一个尚未通过的功能，完成实现与测试后提交代码，并把进度写成结构化交接。

图 10 用文件、Git 和功能清单跨上下文接力

功能清单不要只写“完成 / 未完成”

好的功能清单应当描述用户能观察到的行为、验证步骤和当前状态。Anthropic 的示例会先把所有功能标为 failing，只有在 Agent 真正执行测试后才能改为 passing，从而避免“代码写了，所以功能完成了”的假验收。

{
    "category": "functional",
    "description": "用户可以新建一段对话",
    "steps": [
        "打开主页面",
        "点击新建对话",
        "确认出现空白会话",
        "确认侧边栏新增记录"
    ],
    "passes": false,
    "evidence": [

    ]
}

Context Compaction 和 Context Reset 不要混为一谈

Compaction 是在同一个会话里压缩早期历史，让模型继续工作；Reset 则彻底启动一个干净的新上下文，并通过交接文件、Git、任务状态和证据恢复进度。Anthropic 的测试认为，某些模型在长任务后期会出现急于收尾的倾向，仅做压缩不一定能消除这种状态，而 Reset 能让下一轮干净起跑，但会增加编排、Token 和延迟成本。

图 11 压缩保留连续性，重置提供干净上下文

八、复杂任务可以拆成 Planner、Generator、Evaluator

当任务既需要长时间实现，又有主观质量或复杂验收要求时，一个 Agent 既规划、又实现、又给自己打分，容易出现自我确认。Anthropic 在长时间应用开发实验中使用了 Planner、Generator、Evaluator 三种职责：Planner 生成任务与验收条件，Generator 负责执行，Evaluator 按明确标准检查结果并反馈差距。

图 12 规划、生成和验收分离，减少一个 Agent 自说自话

九、失败恢复要成为状态机，而不是无限重试

真实工具会超时，浏览器会崩溃，API 会限流，代码执行可能半途失败。Harness 需要区分可重试错误、需要回滚的错误、权限不足和必须由人判断的情况，并为任务保存检查点。重试要有限次、有退避、有幂等保护；超过阈值后应保留现场并升级，而不是让 Agent 在同一个坑里消耗 Token。

图 13 生产级失败恢复状态机

一个最小的编排循环

def run_task(task, harness):
state = harness.load_checkpoint(task.id)
while not state.finished:
context = harness.build_context(task, state)
action = harness.model.decide(context)
result = harness.tools.execute(action, sandbox=True)
verdict = harness.verify(task, result)
harness.trace.record(action, result, verdict)
if verdict.passed:
state = harness.advance(state, verdict)
harness.save_checkpoint(task.id, state)
elif verdict.retryable and state.retry_count < 3:
state = harness.retry_from_checkpoint(state, verdict)
else:
return harness.escalate(task, state, verdict)
return harness.publish(task, state)

十、Agent 产出越快，技术债治理越要自动化

Agent 会模仿仓库已经存在的模式。好的模式会被快速复制，坏的 helper、命名习惯和临时绕过也会指数扩散。OpenAI 早期每周拿出一天人工清理所谓“AI slop”，相当于 20% 的工作周，但这种方式跟不上 Agent 的产出速度。

后来，团队把“什么是好代码”沉淀为 Golden Principles，再由定时 Agent 扫描仓库、识别偏离、生成修复 PR；文档也由 doc-gardening Agent 检查是否过时。这里的关键不是完全消灭技术债，而是让技术债检测和修复速度跟上代码生成速度。

图 14 Harness 还要负责持续的熵管理和垃圾回收

十一、评测对象应该是“模型 + Harness”的完整系统

同一个模型放进不同 Harness，任务成功率、Token 消耗、工具调用次数、恢复能力和人工升级率都可能不同。GitHub 在 2026 年公开的多模型 Harness 对比也强调，评价编码 Agent 不能只看底层模型，而要同时看任务解决率、每任务成本和运行方差。

图 15 Harness 评测 Scorecard

每次修改系统提示词、工具描述、上下文策略、子 Agent 结构、重试次数或模型路由，都应在固定基准集上做回归。否则，团队很容易只看到某个案例变好，却没有发现另一类任务的成本翻倍或成功率下降。

十二、生产级架构：拆开状态、执行、凭证与评测

演示项目常把聊天记录、模型调用、工具执行、文件系统和密钥放进一个进程。长时间运行后，这种结构很难恢复、扩容和审计。更稳妥的方式是让 Harness 作为控制面：会话事件与检查点单独持久化；上下文由 Context Builder 动态组装；工具通过路由层调用；不可信代码在沙箱执行；凭证由代理或 Vault 管理；Trace 和 Eval 贯穿整个过程。

图 16 生产级 Agent Harness 参考架构

OpenAI 2026 年更新的 Agents SDK 同样强调受控沙箱和“Harness 与计算分离”，这使长任务在执行环境重启后仍能恢复，也便于按任务弹性创建环境。安全上需要坚持最小权限、网络白名单、凭证不落入沙箱，以及删除数据、发款、发布生产等高风险动作必须人工确认。

十三、从 0 到 1 怎么落地？

不要一开始就堆多智能体、长期记忆和复杂反思。最有效的路线，是先选一类可以明确验收的任务，建立最小执行与验证闭环，再根据真实失败逐步加固 Harness。

图 17 Harness Engineering 的四周起步路线与持续迭代

落地检查清单

十四、面试中怎么回答 Harness Engineering？

项目例子可以按“问题—Harness 改造—可量化结果”展开。例如：Agent 经常调用错接口，于是将最新 API 文档接入检索，增加参数 Schema 校验和失败后的纠错提示，再用固定用例评测工具调用成功率、平均重试次数和 Token 成本。这样比只说“优化了 Prompt”更能体现工程能力。

写在最后

模型能力会继续提升，但模型越强，Harness 并不会自动消失。新的模型可能让某些旧策略失去价值，例如过去必须存在的 Planner、上下文重置或多轮反思，在下一代模型上可能只是额外成本；与此同时，更高自治也会放大权限、恢复、技术债和评测问题。

因此，Harness Engineering 不是不断增加模块，而是持续做实验：保留真正提高成功率、降低成本和风险的能力，删除已经不再“赚回成本”的复杂度。最终竞争力不只来自使用哪个模型，而来自团队能否把知识、约束、反馈和失败快速编码进系统。