Harness Engineering：驯服 AI Agent 的系统工程学

当 LangChain 团队在 Terminal Bench 2.0 上把他们的编码 Agent 从 Top 30 拉到 Top 5 时，他们没有换模型、没有加数据、没有做微调。他们只改了一样东西——Harness。[1][2]

这个结果揭示了一个正在重塑软件工程的事实：模型是商品，Harness 才是护城河。

本文将从概念起源、核心架构、三大支柱、工程实践和未来演进五个维度，对 Harness Engineering 进行一次完整的技术拆解。

一、什么是 Harness Engineering

1.1 术语溯源

"Harness" 一词来自马具——缰绳、鞍具、嚼子——一整套用于引导强大但不可预测的动物朝正确方向前进的装备。这个隐喻是刻意的：[2]

• 马 = AI 模型。强大、快速，但自己不知道该往哪跑
• 马具 = 基础设施。约束、护栏、反馈回路，将模型的能力引导到生产力上
• 骑手 = 人类工程师。提供方向，而不是亲自跑

没有 Harness 的 AI Agent，就是一匹在空旷草原上的纯血马——跑得快、看着帅、但什么活也干不了。

1.2 形式化定义

Harness Engineering 是设计和实现以下系统的工程学科：[2]

1. Constrain（约束）：限定 Agent 能做什么——架构边界、依赖规则
2. Inform（告知）：让 Agent 知道该做什么——上下文工程、文档
3. Verify（验证）：确认 Agent 做对了——测试、Lint、CI 校验
4. Correct（纠正）：Agent 出错时修正它——反馈回路、自修复机制

Martin Fowler 将其描述为"让 AI Agent 保持在正轨上的工具和实践"，但它不仅仅是安全——一个好的 Harness 让 Agent 更有能力，而不仅仅是更受控。[2]

1.3 与相关概念的边界

Harness Engineering 包含 Context Engineering，借鉴 Prompt Engineering，但它运作在更高的层面——它关注的是让 Agent 可靠运行的完整系统，而不仅仅是单次交互的输入。[2]

二、为什么是现在

2.1 LangChain 的实验证明

LangChain 使用 deepagents-cli 在 Terminal Bench 2.0 上进行了系统性实验。模型固定为 gpt-5.2-codex，仅调整 Harness，得分从 52.8% 提升到 66.5%，提升了 13.7 个百分点。[1]

他们压缩了优化空间，只聚焦三个旋钮：System Prompt、Tools、Middleware（即模型调用和工具调用前后的 Hook）。[1]

核心改进点：

同一个模型，不同的 Harness，截然不同的结果。[1][2]

2.2 OpenAI 的百万行代码验证

OpenAI 的 Codex 团队构建了一个超过 100 万行代码的生产应用，其中零行由人类手写。[2]

• 5 个月开发周期
• 100 万+ 行代码
• 零手写代码——每一行都由 Codex Agent 在 Harness 内生成
• 构建时间约为人类的 1/10
• 产品有内部日活用户和外部 Alpha 测试者
• 它能发布、部署、出错、被修复——全部由 Agent 在 Harness 内完成

工程师的工作？设计 Harness。指定意图。提供反馈。不写代码。[2]

三、三大支柱：技术架构深度拆解

3.1 支柱一：Context Engineering

Context Engineering 的核心命题：从 Agent 的视角看，它在上下文中访问不到的东西就不存在。[2]

静态上下文

repo/
├── AGENTS.md              # 项目级规则编码
├── docs/
│   ├── architecture.md    # 架构规范
│   ├── api-contracts.md   # API 契约
│   └── style-guide.md     # 风格指南
└── .cursorrules           # 工具级配置

AGENTS.md 或 CLAUDE.md 文件是 Harness 的基石。它们将项目特定的规则编码为机器可读的文档，作为 Agent 的 ground truth。[2]

动态上下文

LangChain 的 LocalContextMiddleware 在 Agent 启动时运行，执行以下操作：[1]

1. 映射 cwd 及父/子目录结构
2. 运行 bash 命令发现可用工具（如 Python 安装路径）
3. 注入环境信息，减少 Agent 自行搜索的错误面

Agent Request
  → LocalContextMiddleware (映射代码库)
  → [Agent 获得完整环境认知]

关键原则：仓库必须是唯一的真相来源。Google Docs、Slack 线程、人脑中的知识对 Agent 来说是不可见的。[2]

时间预算注入

Agent 天生不擅长时间估算。LangChain 注入时间预算警告，在截止时间前推动 Agent 从实现转向验证。[1]

[Time Budget Warning] 
剩余时间: 3分钟
建议: 停止新功能开发，转入验证阶段

3.2 支柱二：Architectural Constraints（架构约束）

这是 Harness Engineering 与传统 AI Prompting 分歧最大的地方。不是告诉 Agent "写好代码"，而是机械地强制执行好代码的样子。[2]

依赖分层

Types → Config → Repo → Service → Runtime → UI

每一层只能从左侧的层导入。这不是建议——它由结构化测试和 CI 验证强制执行。[2]

约束执行工具链

┌─────────────────────────────────────────────┐
│              约束执行层                       │
├─────────────────────────────────────────────┤
│  确定性 Linter     → 自动标记违规             │
│  LLM 审计员        → Agent 审查其他 Agent 代码 │
│  结构化测试         → 类似 ArchUnit 的架构测试  │
│  Pre-commit Hooks  → 提交前自动检查           │
└─────────────────────────────────────────────┘

为什么约束能提升产出？这看似矛盾，但约束解空间让 Agent 更高效而非更低效。当 Agent 可以生成任何东西时，它浪费 Token 探索死胡同。当 Harness 定义了清晰的边界，Agent 更快收敛到正确解。[2]

Reasoning Sandwich（推理三明治）

LangChain 发现了一个关键的计算资源分配策略：[1]

┌──────────────┐
│  xhigh 推理   │  ← 规划阶段：充分理解问题
├──────────────┤
│  high 推理    │  ← 实现阶段：高效执行
├──────────────┤
│  xhigh 推理   │  ← 验证阶段：捕获错误
└──────────────┘

全程使用 xhigh 推理只得到 53.9%（因为 Agent 超时），而 high 得到 63.6%。推理三明治策略最终推到了 66.5%。[1]

核心洞察：在规划和验证上花更多推理计算，在实现上节省。

3.3 支柱三：Entropy Management（熵管理）

这是最被低估的组件。随着时间推移，AI 生成的代码库会积累熵——文档与现实脱节、命名约定分化、死代码堆积。[2]

Harness Engineering 通过周期性清理 Agent 来解决这个问题：

这些 Agent 按计划运行——每日、每周或由特定事件触发——保持代码库对人类审查者和未来 AI Agent 都保持健康。[2]

四、Self-Verification：最关键的工程模式

4.1 问题：Agent 的"一次通过"偏见

当今模型最常见的失败模式：Agent 写了一个方案，重新读了自己的代码，确认看起来没问题，然后停止。[1]

模型对自己的第一个看似合理的方案有偏见。它们没有自然倾向进入"构建-验证循环"。

4.2 解决方案：强制验证回路

LangChain 在系统提示中添加了问题解决方法论：[1]

1. Planning & Discovery
   → 阅读任务，扫描代码库，基于任务规范和验证方式构建初始计划

2. Build
   → 带着验证思维实现计划。构建测试（如果不存在），
     测试 happy path 和 edge case

3. Verify
   → 运行测试，阅读完整输出，
     与任务要求对比（而非与自己的代码对比）

4. Fix
   → 分析错误，回顾原始规范，修复问题

PreCompletionChecklistMiddleware

这是一个确定性的上下文注入机制。在 Agent 准备退出时拦截它，提醒它对任务规范运行验证：[1]

class PreCompletionChecklistMiddleware:
    """
    在 Agent 尝试完成任务前拦截，
    强制执行验证检查清单
    """
    def intercept_before_exit(self, agent_context):
        checklist = [
            "是否运行了所有测试？",
            "测试输出是否与任务规范匹配？",
            "是否处理了边界情况？",
            "文件路径是否与规范完全一致？"
        ]
        agent_context.inject(
            f"在完成前，请验证以下清单:\n"
            + "\n".join(f"- {item}" for item in checklist)
        )

这类似于 Ralph Wiggum Loop——一个 Hook 在 Agent 退出时强制它继续执行，但这里用于验证。[1]

4.3 Loop Detection：防止死循环

Agent 一旦决定了计划就会变得短视，导致"死循环"——对同一个破碎方案做 10+ 次微小变体。[1]

class LoopDetectionMiddleware:
    """
    通过工具调用 Hook 追踪每个文件的编辑次数。
    超过 N 次编辑后注入上下文建议重新考虑方案。
    """
    def __init__(self, max_edits_per_file=5):
        self.edit_counts = {}
        self.threshold = max_edits_per_file
  
    def on_tool_call(self, tool_name, file_path):
        if tool_name in ["edit_file", "write_file"]:
            self.edit_counts[file_path] = \
                self.edit_counts.get(file_path, 0) + 1
          
            if self.edit_counts[file_path] >= self.threshold:
                return ContextInjection(
                    f"你已经编辑 {file_path} {self.edit_counts[file_path]} 次了。"
                    f"考虑重新审视你的方案，可能需要一个完全不同的方法。"
                )

重要说明：这是一个设计启发式，围绕当今模型的已知缺陷进行工程化。随着模型改进，这些护栏可能不再必要，但今天它们帮助 Agent 正确且自主地执行。[1]

五、Middleware 架构：可组合的 Harness 层

LangChain 将 Harness 结构化为可组合的中间件层：[2]

Agent Request
  → LocalContextMiddleware      (映射代码库)
  → LoopDetectionMiddleware     (防止重复)
  → ReasoningSandwichMiddleware (优化计算)
  → PreCompletionChecklistMiddleware (强制验证)
  → Agent Response

每个中间件层添加特定能力，而不修改核心 Agent 逻辑。这种模块化方法使 Harness 可测试且可演进。[2]

5.1 Trace Analyzer：闭环改进

LangChain 将 Trace 分析做成了一个 Agent Skill，作为跨运行分析错误并改进 Harness 的配方：[1]

1. 从 LangSmith 获取实验 Traces
        ↓
2. 生成并行错误分析 Agent 
   → 主 Agent 综合发现 + 建议
        ↓
3. 聚合反馈，对 Harness 做针对性修改

这类似于机器学习中的 Boosting——聚焦于前一轮运行中的错误。人类在第 3 步可以很有帮助（虽然不是必需的），用于验证和讨论提议的更改。过拟合到单个任务的更改对泛化不利，可能导致其他任务的回归。[1]

六、实践框架：从个人到组织

Level 1：基础 Harness（个人开发者）

适用于使用 Claude Code、Cursor 或 Codex 的个人项目：

项目根目录/
├── CLAUDE.md / .cursorrules    # 项目约定
├── .pre-commit-config.yaml     # Lint + 格式化
├── tests/                      # Agent 可运行的测试套件
└── [清晰的目录结构 + 一致命名]

搭建时间：1-2 小时。效果：防止最常见的 Agent 错误。[2]

Level 2：团队 Harness（3-10 人团队）

在 Level 1 基础上增加：

• AGENTS.md：团队级约定
• CI 强制执行的架构约束
• 常见任务的共享 Prompt 模板
• 文档即代码，由 Linter 验证
• 专门针对 Agent 生成 PR 的 Code Review 清单

搭建时间：1-2 天。效果：团队间一致的 Agent 行为。[2]

Level 3：生产 Harness（工程组织）

在 Level 2 基础上增加：

• 自定义中间件层（循环检测、推理优化）
• 可观测性集成（Agent 读取日志和指标）
• 按计划运行的熵管理 Agent
• Harness 版本控制和 A/B 测试
• Agent 性能监控仪表板
• Agent 卡住时的升级策略

搭建时间：1-2 周。效果：Agent 作为自主贡献者运作。[2]

七、常见反模式

反模式 1：过度工程化控制流

"如果你过度工程化控制流，下一次模型更新就会破坏你的系统。"

模型快速改进。2024 年需要复杂 Pipeline 的能力，现在可能一个上下文窗口 Prompt 就能搞定。构建你的 Harness 使其"可撕裂"——当模型足够聪明不需要某个"智能"逻辑时，你应该能轻松移除它。[2]

反模式 2：把 Harness 当静态物

Harness 需要随模型演进。当新模型发布改进了推理能力，你的推理优化中间件可能变得适得其反。每次重大模型更新时审查和更新 Harness 组件。[2]

反模式 3：忽视文档层

最有影响力的 Harness 改进往往是最简单的：更好的文档。如果你的 AGENTS.md 含糊不清，你的 Agent 输出也会含糊不清。[2]

反模式 4：没有反馈回路

没有反馈的 Harness 是笼子，不是向导。Agent 需要知道它什么时候成功、什么时候失败。[2]

反模式 5：仅面向人类的文档

如果你的架构决策存在于人脑中或 Agent 无法访问的 Confluence 页面里，Harness 就有缺口。Agent 需要的一切都必须在仓库中。[2]

八、工程师角色的演变

Harness Engineering 代表了软件工程师工作内容的真正演变：[2]

这不意味着工程师变得不那么技术化。恰恰相反，Harness Engineering 需要更深层的架构思维——你在设计必须在没有你持续干预的情况下工作的系统。[2]

关键技能矩阵：

1. 系统思维：理解约束、反馈回路和文档如何交互
2. 架构设计：定义可执行且高效的边界
3. 规范写作：足够精确地表达意图，让 Agent 能执行
4. 可观测性：构建揭示 Agent 行为模式的监控
5. 迭代速度：快速测试和优化 Harness 配置

九、核心洞察总结

Harness Engineering 的本质可以浓缩为一句话：

Harness 工程师的目的：代表 Agent 准备和交付上下文，使 Agent 能够自主完成工作。[1]

模型会继续变强。但"尖刺智能"（spiky intelligence）的本质不会消失——模型在某些任务上惊人地好，在另一些上莫名其妙地差。Harness 的工作就是把这种不均匀的智能塑造成我们关心的任务上的稳定表现。[1]

开放的研究方向包括：多模型系统（Codex + Gemini + Claude 协同）、持续学习的记忆原语使 Agent 能自主改进、以及跨模型测量 Harness 变更的方法论。[1]

这个领域还很年轻，但方向已经清晰：未来的软件工程不是写代码，而是设计让 AI 可靠地写代码的系统。

参考来源：

• [1] LangChain Blog: Improving Deep Agents with Harness Engineering
• [2] NxCode: Harness Engineering Complete Guide 2026