一文读懂 Harness Engineering：起源、原理与落地实践

前言：你的瓶颈不在模型，在环境

2026 年 2 月，OpenAI 发了一篇博客。

3 名工程师，5 个月，产出 100 万行生产级代码，合并了 1500 个 Pull Request，全程没有写过一行代码。团队估算效率约为人工的 10 倍。

但他们想说的重点并不是这个成绩，而是成绩背后的方法论，一个不到一个月就席卷全球工程圈的新词：Harness Engineering。

LangChain、Anthropic、ThoughtWorks 先后跟进。国内开发者社区开始密集讨论。它的核心主张只有很反直觉的一句话——你的瓶颈不在模型，在环境。

一、起源：从 Prompt 到 Harness 的三次跃迁

想要理解 Harness Engineering 为什么出现，得先看我们是怎么一步步走到这里的。

2023 到 2024 年：Prompt Engineering

这个阶段，所有人都在研究怎么跟模型说话：包括并不限于精心雕琢指令措辞、设计 Few-shot 示例、引导 Chain-of-Thought等等。其实核心问题只有一个：该怎么问，才能让大模型最好地回答我们的问题？

2025 年中：Context Engineering

Andrej Karpathy 说了一句影响深远的话：Context Engineering 比 Prompt Engineering 重要得多。至此，核心问题变成了：模型应该看到什么？RAG 检索、MCP 工具接入、记忆管理，这一系列动作都是要系统性地为模型构建信息环境。

2026 年 2 月：Harness Engineering

当 AI Agent 真正进入生产环境、执行跨步骤的长周期自主任务时，一类新的失败模式浮现了：Agent会忽视团队规范、生成违反架构约束的代码、在并行执行时与自身冲突、随时间推移逐渐降低代码质量。

这些问题不是"模型该看到什么"能解决的，而是"系统该阻止什么、度量什么、修复什么"的问题。于是就有了Harness Engineering这个名字。

2025 年 11 月，Anthropic 发布博客《Effective Harnesses for Long-Running Agents》，首次系统讨论了长期运行 Agent 的约束设计。

2026 年 2 月 5 日，HashiCorp 联合创始人 Mitchell Hashimoto 在博客里正式命名了这个概念：“每当发现 Agent 犯了一个错误，就花时间工程化一个解决方案，让它永远不再犯同样的错误。”

6 天后，OpenAI 发布官方博客《Harness Engineering: Leveraging Codex in an agent-first world》，披露了 100 万行代码实验。随后 Martin Fowler 在 ThoughtWorks 技术博客中深度分析，一个月内这个词成为开发者社区的高频词。

三代范式的演进，对应了工程师角色的三次角色变迁：

如果把大模型比作一辆赛车，那么Prompt Engineering是在起点呼喊指令，告诉赛车何时起跑、如何转弯；Context Engineering是一张高清赛道地图，标明了坡度、弯道和障碍物位置；Harness Engineering是为这辆赛车铺设一条智能化的赛道，自带护栏、限速提示和能量补给站，让赛车能安全、高效地跑到终点。

二、原理：为什么瓶颈在环境

2.1 核心公式

Harness Engineering 的底层公式很简单：

Agent = Model + Harness

其中，模型负责推理，Harness 负责模型之外的一切，包括工具调用、上下文管理、权限控制、状态持久化、错误恢复、可观测性。

如果 LLM 是 CPU，那么Harness 就是操作系统。CPU 再强，没有操作系统管理内存、调度进程、处理中断，它什么都干不了。

这跟 Prompt Engineering 不在一个层面。Prompt 优化的是"对模型说什么"，而Harness 优化的是"模型跑在什么样的系统里"，一个在对话层，一个在基础设施层。

2.2 Agent 为什么总在长任务里翻车

针对这一问题，Anthropic 工程师在长期跟踪中总结了三种典型的失败模式：

（1）试图一步到位。Agent 更倾向于在一个会话里把所有功能做完。上下文窗口被越塞越满，最终导致完全耗尽，留下一堆没有文档的半成品。在下次会话启动时，只能花费大量的时间来猜测"上次发生了什么"。

（2）过早宣布胜利。到了项目后期，部分功能完成后，Agent 环顾四周看到已经有进展，就会直接宣布任务完成，哪怕还有大量功能完全没实现。

（3）过早标记功能完成。写完代码，单元测试跑通就立即标为完成。但显然这并不是完整流程，至于端到端测试呢？跟其他模块的联调呢？它并不会去检查。

除此之外，更隐蔽的问题是模式复制。Agent 把代码库中存在的模式当作"合法实践"，忠实地复制并放大，这其中也包括坏的模式。

Reddit 一位独立开发者的实测数据：当某个坏模式在代码库中的占比超过 5%时，Agent 生成新代码时采用该模式的概率超过 70%。

以上四个问题没有一个是因为"模型不够聪明"，都是因为运行环境缺乏结构化的约束导致的。由此可见Agent 缺的并不是智力，缺的是护栏。

2.3 三个实验，证明环境比模型更关键

2.3.1 实验一：不改模型，排名从第 30 跳到第 5

LangChain 在 Terminal Bench 2.0 中做了控制变量，底层模型固定为 gpt-5.2-codex，权重一个没动。只修改了系统提示词结构、工具描述方式、中间件逻辑，也就是只改了 Harness。这一改动使得分从 52.8% 升到 66.5%，全球排名从第 30 名跃升至第 5 名。

核心 Harness 优化措施：团队利用 LangSmith 的 Trace 功能大规模分析了智能体的失败模式，并针对性地进行了以下三项核心改进：

1. 系统提示词与中间件：强制“构建-验证”循环

发现的问题：智能体最常见的失败模式是写完代码后，仅凭“自我感觉良好”就停止，缺乏对代码的实际测试和验证。

解决方案：

• 在系统提示词中明确加入了 “规划-构建-验证-修复” 的结构化工作流指导。
• 引入了 PreCompletionChecklistMiddleware 中间件。这个中间件会在智能体试图结束任务前强制拦截，并提醒它必须对照任务原始需求进行验证，只有通过验证才能退出

2. 工具与环境上下文：直接注入，而非探索

发现的问题：智能体在不熟悉的环境中浪费大量时间去探索目录结构、寻找可用工具，这个过程容易出错。

解决方案：

• 发现的问题：智能体在不熟悉的环境中浪费大量时间去探索目录结构、寻找可用工具，这个过程容易出错。
• 解决方案：
  • 使用 LocalContextMiddleware，在智能体启动时自动运行，将当前工作目录、父/子目录、Python 环境等关键信息直接注入其上下文，相当于给智能体做了一次“环境入职培训”。
  • 在提示词中明确告知智能体，其编写的工作将通过程序化测试进行评分，引导它写出更规范、可测试的代码。

3. 推理预算分配：“三明治”策略

发现的问题：在不限制推理预算的情况下，智能体可能在无意义的“末日循环”中过度消耗时间，甚至因超时而失败。

解决方案：

• 针对 gpt-5.2-codex，他们发现全程使用最高强度推理模式 (xhigh) 会导致超时增加，得分反而 更低 (53.9%)，低于使用 high 模式的得分 (63.6%)。
• 最终方案是采用了 “推理三明治” (xhigh-high-xhigh) 策略：在规划和最终验证阶段使用高强度的 xhigh 模式，在中间的代码实现阶段使用稍低的 high 模式，以此平衡深度与速度

4. 模式检测中间件：打破“末日循环”

发现的问题：智能体有时会在一个错误的方向上反复尝试，进行细微的、无效的代码修改（在 Trace 中，这种情况有时会重复10次以上）。

解决方案：开发了LoopDetectionMiddleware。它通过 Hook 追踪智能体对每个文件的编辑次数，一旦超过阈值，就会自动注入提示，建议模型“考虑重新审视你的方法”，帮助它跳出思维定式。

2.3.2 实验二：不改模型，成功率从 6.7% 到 68.3%

独立安全研究员 Can Boluk 发现，Agent 修改代码时大量失败不是因为逻辑错误，而是机械性失误。例如“第 47 行少了一个空格”、“匹配文本不完全一致”。

他设计了一套 Hashline 协议：给每行代码赋予基于内容的哈希标签，模型只需引用标签而非精确匹配原始文本。Hashline 通过修改read_file工具的返回格式，彻底改变了游戏规则：1.读取时加标签：当模型读取文件时，返回的每一行代码都会附带一个2-3 个字符的内容哈希标签（例如11:a3|function hello() {）。

2.编辑时引用标签：模型需要修改某一行时，直接引用这个短标签，而不是写一遍整行代码。

3.写入时校验：写入前，系统会检查该标签对应的原文内容是否发生了变化。如果有变化（哈希不匹配），直接拒绝编辑，防止覆盖别人的修改。

这个改动带来了一组非常夸张的数据：

• 最大黑马：Grok Code Fast 1的成功率直接从6.7% 飙升至 68.3%，翻了十倍不止。
• 普遍提升：在16个模型、3种编辑格式、每种540个任务的大规模测试中，Hashline 在几乎所有模型上都匹配或超越了str_replace。
• 成本直降：Grok 4 Fast 的输出 token下降了 61%，因为模型不再需要反复重试和输出大段修正代码了。

正如他所说：“Gemini 成功率提升了 8%，比大多数模型升级带来的提升都大，而且训练成本是零。你在怪飞行员技术差，其实是起落架坏了。

2.3.3 实验三：同一任务，达成率从 43% 提到 78%

在实验初期，HumanLayer团队遵循了传统的CI/CD实践：每次代码修改后，都会运行完整的测试套件，并将所有输出（包括成功的测试）返回给AI智能体。

问题出现了：在一个中等规模的项目中，一次完整的测试运行可能产生超过4000行的输出。这海量的“噪音”瞬间涌入AI大模型本就宝贵的上下文窗口（通常建议控制在75000 token左右的最佳“智能区”）。

这导致了两个严重的后果：

1. “成功幻觉”：AI智能体在阅读了大量测试文件的内容后，产生了认知混淆。它开始误以为那些通过测试所验证的功能，已经是自己实现的业务逻辑了。这导致它后续的代码修改完全偏离了实际需求——因为它“以为”代码已经写好了。
2. 资源浪费：每一行“PASS src/utils/helper.test.ts”这样的成功输出，都在无情地消耗着宝贵的上下文token，挤占了真正用于推理和解决问题的空间，并快速将模型推向需要“压缩记忆”的“迟钝区”。

解决方案：为了解决这个问题，他们设计了一个极其简单但在逻辑上却非常颠覆的协议：“沉默即成功” (Silence is Success)。他们修改了执行测试的工具逻辑，不再将原始输出一股脑地扔给模型，而是实现了这样一个流程：

# 伪代码示例：HumanLayer采用的“静默执行”逻辑
run_silent() {
    local description="$1"
    local command="$2"
    local tmp_file=$(mktemp)

    if eval "$command" > "$tmp_file" 2>&1; then
        # 成功时：只输出一个绿色对勾，然后删除原始日志
        printf "  ✓ %s\n" "$description"
        rm -f "$tmp_file"
        return 0
    else
        # 失败时：输出红叉，并将之前暂存的完整错误日志全部打印出来
        local exit_code=$?
        printf "  ✗ %s\n" "$description"
        cat "$tmp_file"
        rm -f "$tmp_file"
        return $exit_code
    fi
}

（注：此代码逻辑源于HumanLayer团队的公开技术分享）

这个协议的核心是确定性控制：成功，就只返回一个极简的✓符号（占用远少于10个token）；失败，才返回全部的错误细节，让模型精准地知道问题出在哪里。这样，模型不再需要自己去判断是否需要截断输出，也彻底杜绝了被无用信息干扰的可能。

实验结果：

这一改动带来了惊人的效果提升：

• 任务达成效率飙升：智能体在10步操作内成功完成任务的比例，从原先的43%猛增到了78%。
• 成本与效率双赢：平均每次任务节省了约35%的上下文token消耗，这不仅降低了API调用成本，也让模型的注意力始终保持在“智能区”，从而做出更准确的决策。

三、落地实践：四大支柱

好，现在我们确认了环境比模型更关键，那环境应该怎么设计？综合 OpenAI、Anthropic、LangChain 和 Martin Fowler 的分析，可以拆成四个方向。

3.1 支柱一：上下文工程 —— 给 Agent 一张地图

很多人以为 Harness Engineering 就是写一个超大号的，把全部项目规则塞进去。

OpenAI 自己试过。用他们的原话说：“可预见地失败了。”

上下文窗口是稀缺资源。巨大的指令文件挤掉了任务和代码的空间，Agent 读到后面就漏掉前面的关键约束。

正确的做法：是地图，不是说明书。

Mitchell Hashimoto 的 Ghostty 项目的只有几百行，每一行对应一个历史上 Agent 犯过的错、指向文档目录中的具体文件。文档是活的反馈循环，不是静态制品。

具体操作：

1. 标注清楚 docs/ 下每份文档是什么、什么时候该读
2. 每份文档头部带元信息：最后更新时间、状态、覆盖范围
3. Agent 根据当前任务按需检索，而非一股脑全加载

文档的质量不取决于写得多详细。取决于 Agent 能不能在正确时机读到正确的东西。

3.2 支柱二：架构约束 —— 把规则变成代码

口头约定在 Agent 面前无效。它不会"记住上次说好的"。

OpenAI 团队建立了严格的层级依赖模型：

Types → Config → Repo → Service → Runtime → UI

下层不能反向依赖上层。这套规则被编码为自定义 Linter，在 CI 中强制阻断。人写的还是 AI 写的，违规就合不进去。

一个关键细节：Linter 的错误信息不只是"你违反了规则 X"，还会解释规则为什么存在、正确做法是什么。Agent 读到错误能自动理解并修正，不需要人类介入。

规则写在文档里 → Agent 仍然可以违反。

规则编码为系统级阻断 → 从根本上阻止违规。

3.3 支柱三：反馈循环 —— 沉默是成功，噪声是失败

这是最反直觉的一根。

人类喜欢详细的反馈报告，但Agent 不是。4000 行测试输出里，真正有价值的信息可能只有失败那几行，但 Agent 会把全部内容读一遍，注意力被通过的测试、覆盖率数据、性能指标稀释。

正确的设计是"沉默即成功"：

• 每步完成后自动触发检查脚本。通过 → 零输出。失败 → 结构化错误信息。
• Agent 标记任务完成前，系统强制拦截，要求它对照需求逐项确认边界条件、错误处理、测试更新。
• 同一文件被修改超过 3 次且测试仍失败，触发干预：“检测到重复编辑，建议回滚后重新审视需求。”

对人类来说，详细的信息可以帮助理解；但对 Agent，噪声淹没信号。

3.4 支柱四：熵管理 —— 让 Agent 清理 Agent 的垃圾

这个论断基于AI编程时代两个已经发生的事实：

1. AI 复制的速度远超人类：AI编程智能体能够瞬间分析整个代码库，并识别出其中“最普遍”的模式。一旦你允许一个临时的、不完美的妥协方案（比如为了赶进度绕过架构约束）合入主分支，智能体就会将这个“坏模式”视为可参考的先例，在几分钟内生成的新代码中，大规模复制并在代码库的每个角落复用这种模式。人类引入坏模式的速度是线性的，而AI扩散它的速度是指数级的。
2. “集中清理”模式已失效：OpenAI 的内部工程团队在早期实践后发现，传统的“每周五集中清理技术债”模式已不可行。因为在AI辅助开发的背景下，技术债务的堆积速度远超人类团队的清理速度。当一周的工作被智能体加速完成后，堆积的技术债可能在几天甚至几小时内就达到了积重难返的地步。

为了解决上述困境，OpenAI 的工程师 Ryan Lopopolo 提出了一个新的实践：“垃圾收集日”（Garbage Collection Day）。

它的核心机制与传统模式截然不同：

1. 频率与节奏：不是每周一次，而是每天一次。在每个工作日的下午（例如4点到5点），团队会固定进入“清理模式”。
2. 工作内容：在这一个小时里，工程师不再开发新功能，而是专门用来审视当天AI Agent生成的所有代码、合并请求（PR）、以及CI/CD流水线的反馈。
3. 核心任务：快速识别出当天新引入的“坏模式”或临时代码妥协，并立即将它们“编译”成可供AI自动执行的规则，比如：

这本质上就是把偿还技术债的动作，从一个耗时巨大的“大项目”，拆解为融入到每天工作流末尾的、自动化、可积累的“小习惯”。

技术债像高息贷款，持续小额偿远比集中清账更可持续。

四、怎么开始：Harness Engineering 三阶段路线图详解

4.1 Harness Engineering 三阶段路线图

Harness Engineering 不是"一把梭"，推荐渐进式推进。

这个三阶段路线图，是目前将Harness Engineering从理念落地为实践的最清晰、最可操作的指南之一。它精准地捕捉到了从“信息混乱”到“自动化治理”的渐进式演进路径，每一步都为下一步打下基础。

下面为你详细拆解每个阶段的要点、具体操作和核心目标。

4.2 Phase 1：信息层 (1-2天) —— 从“百科全书”到“地图”

这个阶段的核心目标是解决“信息过载与定位困难”。

核心问题：一个巨大的AGENTS.md文件如同百科全书，AI智能体阅读耗时、推理负担重，且在需要更新时容易产生冲突。信息获取的信噪比极低。

解决方案：文档索引化与结构化。

4.3 Phase 2：约束层 (3-5天) —— 从“软规范”到“硬检查”

这个阶段的核心目标是将最重要的架构规则自动化、可执行化。

核心问题：仅靠文档中的“严禁……”类规范是软约束，AI Agent可能会忽略或“忘记”。必须将它们转化为硬性检查，在代码生成或提交时自动执行，失败则阻断流程。

解决方案：规则自动化与CI/CD集成。

4.4 Phase 3：自动化层 (1-2周) —— 从“人工治理”到“系统自愈”

这个阶段的核心目标是建立自动化的管理和持续优化机制。

核心问题：前两个阶段主要依赖人工定义规则。当任务规模和复杂度提升时，需要系统具备更强的自动管理和优化能力。

解决方案：引入多Agent协作与自动化治理Agent。

4.5 路线图总结

4.6 总结

这个三阶段路线图的精妙之处在于它的渐进性和闭环性：

渐进性：从成本最低、最容易开始的“信息整理”入手；逐步升级到“自动化检查”；最终实现“系统化治理”。每一步都为下一步提供了必要的输入（信息层输出清晰的约束目标，约束层输出可被自动化的规则）。

闭环性：核心落在“Agent每翻一次车，就往Harness里加一个检查点”这个习惯上。这使得Harness本身成为一个“活的”、持续进化的系统，而不是一次性的配置。团队的认知和经验被持续地、低成本地编码进系统，形成组织知识的有序沉淀。

Harness Engineering 正是一个将原本琐碎的、依赖于个人经验的“AI编程技巧”，系统化、工程化、自动化的实践框架。

五 总结：你不需要更聪明的 AI，你需要更好的缰绳

ThoughtWorks 的 Birgitta Böckeler 有一句被反复引用的话：

“为了获得更高的 AI 自主性，运行时必须受到更严格的约束。增加信任需要的不是更多自由，而是更多限制。”

这就像高速公路上的护栏，正因为有它们的存在，你才敢开到 120甚至更高的时速。

2026 年的工程师正在经历一个静默的角色转移，以前问"怎么写出更好的代码"、“怎么写出更好的 prompt”、“怎么让模型看到更多信息”，现在问：怎么设计一个 Agent 能在里面稳定、可靠、不失控地工作的环境？

这件事跟写代码的创造力是两条线，它更像系统工程、更像控制论，但同时也是未来几年最能放大个人生产力的技能。

模型质量在快速趋同，GPT、Claude、Grok 的差距会越来越小。但在同一个基线模型下，你设计的文档结构、lint 规则、Hook 脚本、Agent 分工模式——才是真正拉开生产力差距的地方。