Enter your search text in the box above

Select a result to preview

000.Harness Engineering

出处：掘金

原作者：也无风雨也雾晴

太长不读

2026 年 AI Agent 圈最火的一个词：Harness Engineering（驾驭工程）。核心发现：决定 Agent 表现的不是模型本身，而是包裹在模型外面的那套系统

两个标志性实验：

本文从定义、组成、实践三个维度拆解 Harness Engineering，核心结论：

Harness 是什么

一句话定义

Agent Harness 是包裹在语言模型外面的所有非模型代码：提示、工具、中间件、状态管理、反馈回路。模型提供智能，Harness 让智能变得可用

类比

就像带一个能力极强但没有背景知识的新员工入职 —— 你不替他干活，而是准备好入职文档、编码规范、CI 流程和 Review 机制，让他自己高效产出

和 Context Engineering 的关系

2025 年流行的词叫 Context Engineering（上下文工程），关注的是"怎么给模型提供好的输入"。Harness Engineering 是它的超集：

Context Engineering 管"模型看到什么"，Harness Engineering 还管"模型能做什么、怎么验证、出错怎么办"

Harness 由什么组成

六大组件

┌─────────────────────────────────────────────┐
│              Agent Harness                   │
│                                             │
│  ┌─────────────┐  ┌──────────────────────┐ │
│  │ System Prompt│  │ Tools / Skills / MCP │ │
│  │ 身份、约束、  │  │ Agent 能调用什么     │ │
│  │ 行为规范     │  │                      │ │
│  └─────────────┘  └──────────────────────┘ │
│                                             │
│  ┌─────────────┐  ┌──────────────────────┐ │
│  │ Middleware   │  │ Context Architecture │ │
│  │ / Hooks      │  │ 分层上下文、         │ │
│  │ 确定性逻辑   │  │ 渐进加载、压缩策略   │ │
│  └─────────────┘  └──────────────────────┘ │
│                                             │
│  ┌─────────────┐  ┌──────────────────────┐ │
│  │ Persistent   │  │ Verification Loop    │ │
│  │ Memory       │  │ 自我验证、评测、     │ │
│  │ 文件系统状态  │  │ 反馈闭环             │ │
│  └─────────────┘  └──────────────────────┘ │
└─────────────────────────────────────────────┘
                     │
              ┌──────┴──────┐
              │   LLM 模型   │
              │  （不动这里） │
              └─────────────┘

各组件职责

组件 做什么 对应工具
System Prompt 定义 Agent 身份、行为约束、完成标准 CLAUDE.md / AGENTS.md / SOUL.md
Tools Agent 能调用的外部能力 MCP Server、Skill 脚本
Middleware / Hooks 在模型调用前后插入确定性逻辑 Claude Code Hooks、LangChain Middleware
Context Architecture 管理上下文质量，防止 Context Rot Skills 延迟加载、滑动窗口、Prompt Caching
Persistent Memory 跨会话的状态持久化 MEMORY.md、进度文件、git 历史
Verification Loop 验证 Agent 产出是否正确 单元测试、Lint、评测体系

关键认知：这些组件单独看都不新鲜，Harness Engineering 的贡献是把它们当成一个整体来设计

LangChain 实验：只改 Harness，涨了 13.7 分

实验设置

Middleware 管道

LangChain 把 Harness 设计成可组合的中间件链：

Agent Request
  │
  ├→ LocalContextMiddleware
  │    启动时扫描 cwd 及上下级目录
  │    定位 Python 安装路径等工具
  │    减少环境类报错
  │
  ├→ LoopDetectionMiddleware
  │    检测 Agent 是否在重复相同动作
  │    触发时强制换策略
  │
  ├→ ReasoningSandwichMiddleware
  │    "推理三明治"：规划和验证阶段多分配算力
  │    中间执行阶段正常算力
  │    注意：xhigh 设置反而更差（53.9%），因为超时
  │
  ├→ PreCompletionChecklistMiddleware
  │    提交前强制跑验证清单
  │    告诉 Agent "你的产出会被程序化测试"
  │
  ▼
Agent Response

关键发现

改了什么 效果
加 LocalContextMiddleware 环境报错大幅减少
加 LoopDetection 消除死循环，任务完成率上升
推理三明治（high 档） 63.6%（最优）
推理三明治（xhigh 档） 53.9%（超时反而更差）
自我验证提示 Agent 开始主动写测试验证自己
综合以上 52.8% → 66.5%，Top 30 → Top 5

最反直觉的结论：给更多算力不一定更好。推理预算分配比总量更重要 —— 在规划和验证阶段花算力，在执行阶段省算力

OpenAI 实验：零行手写代码，百万行产出

基本数据

四条核心原则

  1. Agent 看不到的内容等于不存在

知识必须存在于代码库本身。AGENTS.md 约 100 行，作为索引指向设计文档、架构图、质量评分 —— 全部版本化，在仓库里维护

AGENTS.md（索引，约 100 行）
  ├→ docs/architecture.md
  ├→ docs/design-decisions/
  ├→ docs/quality-grades/
  └→ docs/execution-plans/
  1. 约束编码化，而非文档化

规则不写在 Wiki 里让人去看，而是编进 Linter、类型系统、CI 规则和结构测试。Agent 选择性遵守文档，但无法绕过编译器

  1. Agent 端到端自主完成

从问题复现 → 实现 → 测试 → 开 PR，全链路不需人介入。人只在最后做 Review（大多数 PR 一分钟内可审完）

  1. 最小化合并阻力

测试偶发失败用重跑处理，不阻塞进度。定期有后台 Codex 任务扫描偏差、更新质量评分、开重构 PR —— 像垃圾回收一样自动清理

不是写一次就丢那的静态文档：

Agent 开始 session → 读 AGENTS.md
       │
Agent 执行任务 → 遇到失败
       │
Agent 更新 AGENTS.md ← 把失败原因和解法写回去
       │
下一个 Agent session → 读到更新后的 AGENTS.md → 不再重复犯错

还有一套"黄金原则"被编码进仓库：

从 Harness 视角重新理解 Claude Code

Claude Code 本身就是一个 Harness。把它的能力映射到 Harness 的六大组件：

Harness 组件 Claude Code 对应 作用
System Prompt CLAUDE.md 项目约定、行为规范
Tools MCP Server + 内置工具（Bash、Read、Edit...） Agent 能做什么
Middleware / Hooks Hooks（PreToolUse / PostToolUse） 工具调用前后插入逻辑
Context Architecture Skills 延迟加载 + Prompt Caching 上下文质量管理
Persistent Memory MEMORY.md + 进度文件 跨会话状态
Verification Loop 测试运行 + Lint + 子 Agent 验证 产出验证

你已经在做 Harness Engineering 了

如果你做过以下任何一件事，你就已经在做 Harness Engineering：

Harness Engineering 不是让你学新东西，而是让你意识到这些散落的实践应该当成一个整体来设计

怎么落地

四象限定位

OpenAI 提出的任务分类框架 —— 先搞清楚你的任务在哪个象限：

                    验证可自动化
                        │
          ┌─────────────┼─────────────┐
          │             │             │
          │  需人审查    │  最适合Agent │
          │  吞吐量受限  │  ← 目标区域  │
  目标     │             │             │
  清晰 ────┤─────────────┼─────────────┤
          │             │             │
          │  Agent无用   │  高效地跑偏  │
          │             │             │
          └─────────────┼─────────────┘
                        │
                   验证靠人工

Harness 的核心工作就是把任务推向右上角 —— 让目标更明确（System Prompt），让验证更自动化（Verification Loop）

落地顺序

第一步：写 CLAUDE.md / AGENTS.md
        ↓ 定义 Agent 能看到什么
第二步：编码化约束
        ↓ 规则进 Linter / CI / 类型系统，不靠 Agent 自觉
第三步：接工具
        ↓ MCP 接外部系统，Skills 定义使用流程
第四步：加 Middleware
        ↓ Hook 在关键节点插入确定性逻辑
第五步：建评测
        ↓ 每个真实失败转成测试用例
第六步：闭环
        ↓ Agent 失败 → 更新文档 → 下次不再犯

一个最小可用 Harness

如果只能做三件事：

  1. 写一份好的 CLAUDE.md：项目结构、命名规范、禁止事项、常用命令。Agent 看不到的等于不存在
  2. 把验收标准变成可执行的：不是"代码要干净"，而是 npm run lint && npm test 通过
  3. 记录失败并更新：每次 Agent 犯错，把原因和解法写回 CLAUDE.md。这就是最小版的反馈闭环

这三件事做到位，你的 Agent 表现会有明显提升 —— 不需要换更贵的模型

常见误区

误区 事实
"换更好的模型就行" LangChain 实验证明：同一模型，只改 Harness，涨 13.7 分
"Harness 就是写好 Prompt" Prompt 只是六大组件之一，还有工具、中间件、评测、记忆
"多给算力就能解决" xhigh 推理档位反而更差，算力分配比总量更关键
"AGENTS.md 写一次就行" 它是动态反馈循环，Agent 失败时要更新，不是静态文档
"把规则写清楚 Agent 就会遵守" 文档化的规则会被忽略，必须编码进 CI / Linter / 类型系统
"Harness 是个新技术要从头学" 你已经在做了 —— CLAUDE.md、MCP、Hooks、Skills 都是 Harness 的一部分

工程师角色的变化

这可能是 Harness Engineering 最深远的影响

之前

工程师的一天：读需求 → 设计方案 → 写代码 → 写测试 → 提 PR → 等 Review → 合并

现在

工程师的一天：分解目标 → 写清楚验收标准 → 配好 Agent 环境 → 启动 Agent → 审查 PR（大多数一分钟搞定）→ 遇到失败更新 AGENTS.md → 循环

核心转变

从"我来写"变成"我来定义什么算对，让 Agent 去写"

OpenAI 给出的数据：3 个工程师，人均每天审查合并 3.5 个 PR。这意味着工程师的瓶颈不再是写代码的速度，而是：

这三项，恰好就是 Harness Engineering 的核心

划重点

参考资料