Harness Engineering 工程化教程：AI Agent 复杂长任务实践指南

二、Harness Engineering 为什么会出现？

Agent 的核心挑战

当我们说'AI Agent 能自主完成复杂任务'时，隐含了一个假设：Agent 能够在长时间、多步骤的复杂任务中保持一致性。

但这个假设与 LLM 的特征存在冲突：

LLM 是无状态的：每次推理都是独立的函数调用，f(context) → output
复杂工作是有状态的：需要记住'我做了什么'、'为什么这么做'、'下一步该做什么'

LLM 的模式是 next token prediction：给定 context，预测下一个 token。这个模式本身就是无状态的。但 Agent 需要完成的是 task completion：记住目标，规划步骤，执行，验证，直到完成。这是有状态的工作。

Anthropic 用一个比喻描述了这个挑战：这就像一个软件项目由工程师轮班完成，每个新工程师到来时都不记得上一班发生了什么。

Harness 在无状态的 LLM 和有状态的任务之间搭建桥梁，类似于操作系统让无状态的 CPU 运行有状态的程序。

Context 的动态性挑战

在 Agent 已成为主流应用形态的今天，业界开始意识到：Agent 的主要挑战已经从'能不能跑'转移到'能不能持续可靠地跑'。

LangChain 的 Harrison Chase 在最近的 Sequoia Training Data 访谈中给出了一个直白的洞察：

'Everything's context engineering.'

理解这句话的背后，可以想你这样一种情况：当 Agent 需要执行第 14 步操作时，它的 context 取决于前 13 步的任意组合。你无法预测它会看到什么，也无法保证它记得什么。

这与传统软件有本质区别。

传统软件的状态是确定性的：给定相同的输入和初始状态，你总能得到相同的输出。但 Agent 的 context 是动态构建的：

• 第 1 步可能调用了工具 A，返回了 100 行数据
• 第 7 步可能基于这些数据做了决策，但只保留了摘要
• 第 14 步的 context 中，可能只剩下'工具 A 返回了客户列表'这样的描述

Agent 在第 14 步'看到'的世界，是前 13 步的任意组合动态构建出来的。这就是为什么 context engineering 成为 Agent 系统的核心挑战。

这个挑战在生产环境中体现为三个具体瓶颈：

瓶颈 1：从'单步智能'到'长时程可靠性'的 机制 Gap

各种眼花缭乱 Benchmark 刷榜制造了一个幻觉：模型在单轮任务上的准确率已经很高（>85%），但这无法预测它在第 50 步、第 100 步之后的表现。

'A 1% difference on a leaderboard cannot detect the reliability if a model drifts off-track after fifty steps.'

'排行榜上 1% 的差异无法检测出模型在第 50 步之后是否会偏离轨道的可靠性。'

– Philipp Schmid

Durability（持久可靠性）是一个独立于 Capability（单步能力）的维度。一个在 MMLU 上得 90 分的模型，可能在执行 100 步的工作流时完全跑偏。

Anthropic 在构建 Claude Code 时，发现了两个典型的失败模式：

1. 'All-or-nothing' 模式：Agent 试图一次性完成所有功能，导致 context 耗尽，下一个 session 接手时发现代码写了一半、没有文档、无法继续
2. '过早胜利' 模式：Agent 看到一点进展就宣布任务完成，实际上核心功能还没实现

这两个失败模式的共同点是：Agent 缺乏'我在做什么'的持续认知。它在每个时刻都很聪明，但时间一长后就失去方向，不知道自己应该做什么了。

Feature List、Progress Notes、Git Commits 等机制给 Agent 提供'记忆的外部化存储'，让长时程任务（Long-horizon Tasks）成为可能。

瓶颈 2：Context 爆炸与 Attention 机制的限制

现在的 Agent 应用动辄需要处理 10 万+ token 的 context。但百万级别的 context window 扩大并没有解决根本问题。'Lost in the middle' 现象是 Transformer 架构 attention 机制的数学特性。

这导致了一个常见的使用困扰：把 100 页文档全部塞进 context，效果还不如给 Agent 一个 100 行的'地图'，让它按需检索。

OpenAI 的 Codex 团队在构建 100 万行代码的 Agent 维护系统时，核心策略就是'渐进式披露'：

• 不是把整个 codebase 塞进 context
• 而是给 Agent 一个 AGENTS.md（100 行），作为稳定的入口点
• Agent 从这个地图出发，通过工具调用按需检索详细内容

为什么这样更有效？因为每次检索的内容都在 attention 的有效范围内，而不是被埋在中间 60% 的 attention sink 里。

'Context engineering is not about compression, it's about architecture.'

'Context 工程的核心不是压缩，而是架构设计。'

– Harrison Chase, LangChain

文件系统、compaction、动态子 Agent 等机制把'信息检索'从 Agent 的负担变成系统的能力，让 Agent 只看到它需要的信息。

瓶颈 3：从'能跑'到'可维护'的工程化 Gap

OpenAI 的 Codex 团队用 5 个月构建了一个 100 万行代码的应用，完全由 AI 生成和维护。但他们遇到的最大挑战不是'让 AI 写代码'，而是'让 AI 写的代码可维护'。

他们的核心发现是：

'Our most difficult challenges now center on designing environments, feedback loops, and control systems.'

'我们现在面临的最大挑战集中在设计环境、反馈循环和控制系统上。'

– OpenAI Codex Team

生产系统的可靠性要求，远超 benchmark 的评估标准。

Terminal Bench 2.0 的数据也提供了佐证：

• GPT-5.2-Codex 在不同 harness 配置下的分数从 52.8% 到 66.5%（26% 的相对提升）
• 模型从 GPT-5.2-Codex 升级到 GPT-5.3-Codex，在 SWE-Bench Pro 上只提升了 0.7%（56.4% → 56.8%）

这说明：当模型能力达到一定水平后，系统设计成为效果的主要瓶颈。

LangChain 的实验也证实了这一点：他们的 deepagents-cli 在 Terminal Bench 2.0 上从 52.8% 提升到 66.5%，13.7 个百分点的提升。关键是：只改了 harness，模型固定在 GPT-5.2-Codex。

使用更大的模型已经不是性能优化的主要路径。Harness 的设计，才是决定 Agent 能否在生产环境中可靠工作的最关键因素。

可验证性：Harness 的核心价值

业界主流的 Harness Engineering 实践，都指向了同一个技术原则：

'The ability to improve a system is proportional to how easily you can verify its output.'

—— Jason Wei

如果你无法验证 Agent 在第 50 步做了什么、为什么做、做得对不对，你就无法优化它。

• Anthropic 通过 feature list（200+ 个明确的 pass/fail 标准）+ git commits，让每一步的进展都可验证
• LangChain 通过 middleware 强制验证循环，让 Agent 无法跳过测试就宣布完成
• OpenAI 通过 custom linters + structural tests，让架构约束变成可自动检查的规则

**Harness Engineering 把