Harness Engineering 核心概念详解

文章目录1. Harness Engineering 的本质定义1.1 核心定义1.2 诞生的历史时刻1.3 Harness 的本意2. Agent Model Harness 核心公式2.1 公式解读2.2 LangChain 工程师的精炼定义2.3 类比CPU 与操作系统3. Harness 三大支柱详解3.1 支柱一上下文工程Context Engineering核心命题OpenAI 的惨痛教训两层上下文工程方案AGENTS.md 设计原则反直觉的设计原则3.2 支柱二架构约束Architectural Constraints核心命题OpenAI 的发现精妙设计错误信息即教学时刻规则库的演进3.3 支柱三熵管理Entropy Management核心命题OpenAI 的初始方案不可持续最终方案让 Agent 清洁 Agent 的烂摊子Mitchell Hashimoto 理念的系统化体现4. Harness 核心组件全景4.1 组件架构图4.2 关键组件详解4.2.1 跨会话状态管理Cross-Session State4.2.2 上下文压缩Compaction4.2.3 自验证循环Self-Verification Loop5. Harness 与传统软件工程的核心区别5.1 根本性差异5.2 思维转变6. 关键挑战与解决方案6.1 Challenge 1: 无状态问题6.2 Challenge 2: Context Rot6.3 Challenge 3: 架构漂移6.4 Challenge 4: 验证缺失6.5 Challenge 5: 费用失控7. 核心术语速查表1. Harness Engineering 的本质定义1.1 核心定义Harness Engineering是指围绕 AI Agent特别是 Coding Agent设计和构建约束机制、反馈回路、工作流控制和持续改进循环的系统工程实践。它解决的核心问题是当 AI Agent 拥有了强大的代码生成能力后如何确保其输出的可靠性、一致性和长期可维护性。1.2 诞生的历史时刻2026年2月5日 Mitchell HashimotoHashiCorp 联合创始人、Terraform 创作者 首次正式定义 每当你发现 Agent 犯了一个错误 你就花时间设计一个解决方案 使 Agent 永远不再犯同样的错误。 我称之为 Harness Engineering。仅仅六天后OpenAI 发布了历史性的实验报告3 人工程师团队5 个月时间借助 Codex Agent 构建了超过100 万行代码的产品零行人工手写代码人均日合并 3.5 个 PR效率约为传统模式的10 倍1.3 “Harness” 的本意┌─────────────────────────────────────────────┐ │ │ │ Harness挽具/驾驭具 │ │ │ │ ←─────── │ │ (被驾驭者) (驾驭者) │ │ │ │ 通过约束和引导让强大的力量为人类服务 │ │ │ └─────────────────────────────────────────────┘核心理念模型Model是强大的非确定性智能Harness 是驾驭这种智能的工程系统目标不是限制智能而是让智能有用2. Agent Model Harness 核心公式2.1 公式解读┌──────────────────────────────────────────────────────────┐ │ │ │ Agent Model Harness │ │ │ │ ┌──────────────────┐ ┌────────────────────┐ │ │ │ │ │ │ │ │ │ Model模型 │ │ Harness驾驭具 │ │ │ │ │ │ │ │ │ │ • 大语言模型 │ │ • 约束机制 │ │ │ │ • 提供智能 │ │ • 反馈回路 │ │ │ │ • 非确定性 │ │ • 状态管理 │ │ │ │ • 无状态 │ │ • 验证机制 │ │ │ │ │ │ • 工具调度 │ │ │ └──────────────────┘ └────────────────────┘ │ │ │ │ │ 模型提供智能Harness 让智能有用 │ │ — Harrison Chase, LangChain CEO │ │ │ └──────────────────────────────────────────────────────────┘2.2 LangChain 工程师的精炼定义“如果你不是模型你就是 Harness。”— Vivek Trivedy, LangChain 工程师理解要点Harness 是围绕 LLM 的一切代码、配置和执行逻辑状态管理 → Harness工具调度 → Harness反馈回路 → Harness验证机制 → Harness上下文压缩 → Harness每一样都属于 Harness 的范畴2.3 类比CPU 与操作系统传统计算机架构 AI Agent 架构 ┌─────────────┐ ┌─────────────┐ │ CPU │ │ Model │ │ (计算能力) │ → │ (智能核心) │ └─────────────┘ └─────────────┘ ↓ ↓ ┌─────────────┐ ┌─────────────┐ │ Operating │ │ Harness │ │ System │ → │ (驾驭系统) │ │ (让能力可用) │ │ (让智能有用) │ └─────────────┘ └─────────────┘ 模型是 CPUHarness 是操作系统——CPU 再强OS 拉胯也白搭。 — Harrison Chase3. Harness 三大支柱详解OpenAI 实验报告经过 Martin Fowler 团队的深度分析后被归纳为三个彼此依存的支柱。理解这三个支柱就理解了 Harness Engineering 的全部核心。┌─────────────────────────────────────────────────────────┐ │ Harness Engineering 三大支柱 │ ├─────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────────────────┐ │ │ │ │ │ │ │ 上下文工程Context │ │ │ │ 让 Agent 知道该知道的事 │ │ │ └──────────────────────────────┘ │ │ │ │ │ ┌──────────────┴──────────────┐ │ │ │ │ │ │ ┌────────────────────┐ ┌────────────────────────┐ │ │ │ 架构约束Arch │ │ 熵管理Entropy │ │ │ │ 让 Agent 不做 │ │ 让 Agent 清理 │ │ │ │ 不该做的事 │ │ 自己的烂摊子 │ │ │ └────────────────────┘ └────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────┘3.1 支柱一上下文工程Context Engineering核心命题从 Agent 的视角任何它在运行时无法访问的内容等同于不存在。OpenAI 的惨痛教训❌ 错误做法 团队在 Slack 上就某个架构模式达成了共识 但没有写进代码仓库。 结果 Codex Agent 在之后的所有会话中 完全无法知道这个约定 一次次地走弯路。 ✅ 正确做法 知识必须被推送进仓库 成为版本控制下的文档。两层上下文工程方案┌─────────────────────────────────────────────────────────┐ │ 上下文工程架构 │ ├─────────────────────────────────────────────────────────┤ │ │ │ 第一层AGENTS.md项目导航地图 │ │ ├─ 约 100 行简洁明了 │ │ ├─ 每行都是指向深度文档的指针 │ │ └─ 过长的 AGENTS.md 会挤占任务 Token │ │ │ │ 第二层深度文档知识库 │ │ ├─ 架构设计文档docs/architecture.md │ │ ├─ API 文档docs/api.md │ │ ├─ 编码规范docs/coding-standards.md │ │ └─ 质量评分标准docs/quality.md │ │ │ └─────────────────────────────────────────────────────────┘AGENTS.md 设计原则!-- ✅ 好的 AGENTS.md导航地图 -- ## 项目概览 用户认证服务Spring Boot PostgreSQL ## 构建命令 - 完整构建./gradlew build - 运行测试./gradlew test ## 架构约束 - 依赖方向domain → application → infrastructure - 详见docs/architecture.md#dependency-rules ## 编码规范 - 使用懒加载N1 用 fetch join 解决 - 详见docs/coding-standards.md !-- ❌ 坏的 AGENTS.md百科全书 -- ## 架构约束详细说明10000 字 ... # 问题挤占任务 Token导致性能下降反直觉的设计原则约束反而提升效率当 Agent 面对可以生成任何东西的开放空间时它会浪费 Token 探索死路。而当 Harness 通过文档和规则定义了清晰的边界后Agent 能更快收敛到正确的解决方案。3.2 支柱二架构约束Architectural Constraints核心命题与其告诉 Agent “写好代码”不如机械地强制执行好代码的样子。OpenAI 的发现仅靠提示词约束架构边界是不可靠的。他们最终构建了混合执行机制┌─────────────────────────────────────────────────────────┐ │ 混合执行机制 │ ├─────────────────────────────────────────────────────────┤ │ │ │ LLM 驱动的代理审查 确定性自定义 Linter │ │ │ │ ┌──────────────────┐ ┌────────────────────┐ │ │ │ │ │ │ │ │ │ Agent 生成代码 │ → │ Linter 检查 │ │ │ │ │ │ (纯代码实现) │ │ │ └──────────────────┘ └────────────────────┘ │ │ │ │ │ ↓ │ │ ┌────────────────────┐ │ │ │ │ │ │ │ 错误信息 │ │ │ │ 修复指南 │ │ │ │ (Teaching Moment) │ │ │ └────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────┘精妙设计错误信息即教学时刻// ❌ 触发 Linter 错误的代码// domain/UserService.javaimportcom.example.infra.DatabaseRepository;// 违反架构约束// ✅ Linter 输出包含修复指引/* [ARCH-001] domain 层不得直接引用 infrastructure 层。 原则保持依赖方向 domain → application → infrastructure 修复建议 在 application 层定义 UserRepository 接口 由 infrastructure 层实现该接口。 参见docs/architecture.md#dependency-rules 示例 // application/UserRepository.java public interface UserRepository { OptionalUser findById(Long id); } // infrastructure/SqlUserRepository.java public class SqlUserRepository implements UserRepository { // 实现细节 } */规则库的演进┌─────────────────────────────────────────────┐ │ │ │ 每一条 Linter 规则背后都是 │ │ Agent 曾经犯过的某个错误 │ │ │ │ 规则库随着项目迭代越来越健壮 │ │ │ │ 这是一个正向的复利飞轮 │ │ │ └─────────────────────────────────────────────┘3.3 支柱三熵管理Entropy Management核心命题AI 生成的代码库随着时间推移会自然累积熵——文档与代码脱节、命名规范漂移、死代码堆积。Harness 需要内置对抗熵增的机制。OpenAI 的初始方案不可持续❌ 人工清理模式 每周五整个团队20% 的工时 用于手动清理AI 垃圾代码。 问题显然不可持续最终方案让 Agent 清洁 Agent 的烂摊子建立一组后台垃圾回收 Agent周期性运行┌─────────────────────────────────────────────────────────┐ │ 后台垃圾回收 Agent │ ├─────────────────────────────────────────────────────────┤ │ │ │ 文档一致性 Agent │ │ 任务验证文档与当前代码是否匹配开修复 PR │ │ 频率每日 │ │ │ │ 约束违规扫描器 │ │ 任务发现绕过了早期检查的约束违反 │ │ 频率每 PR │ │ │ │ 模式执行 Agent │ │ 任务识别并修复偏离既定模式的代码 │ │ 频率每周 │ │ │ │ 依赖审计器 │ │ 任务追踪并解决循环或不必要的依赖 │ │ 频率每周 │ │ │ └─────────────────────────────────────────────────────────┘Mitchell Hashimoto 理念的系统化体现“每当 Agent 犯一个新类型的错误就回头加一条约束。”日积月累Harness 越来越健壮Agent 能犯的错越来越少正向的复利飞轮 4. Harness 核心组件全景4.1 组件架构图┌─────────────────────────────────────────────────────────────────┐ │ Harness 架构 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 上下文工程层 │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ │ │ AGENTS.md │ │ 代码库索引 │ │ 关键文档指针 │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 工具调度层Tool Dispatch │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ │ │ 文件操作工具 │ │ 命令执行工具 │ │ 测试运行工具 │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 反馈回路层Feedback Loops │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ │ │ 自验证循环 │ │ 错误分析 │ │ 循环检测 │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 架构约束层Constraints │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ │ │ 自定义 Linter│ │ 结构测试 │ │ 依赖规则检查 │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 状态管理层State Management │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ │ │ 进度追踪文件 │ │ 上下文压缩 │ │ 跨会话记忆 │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 熵管理层Entropy Management │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ │ │ GC Agent │ │ 文档同步 │ │ 依赖审计 │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘4.2 关键组件详解4.2.1 跨会话状态管理Cross-Session State问题LLM 天生无状态每次新会话都是失忆重启解决方案结构化进度文件// .agent-progress.json — 跨会话状态追踪{feature:用户认证模块,status:in_progress,completed_steps:[✅ 数据库 Schema 设计,✅ UserRepository 接口定义,✅ JWT 工具函数实现],current_step: LoginController 编写中,next_steps:[⬜ 编写单元测试,⬜ 集成测试,⬜ 文档更新],blockers:[],last_updated:2026-03-16T14:30:00Z}4.2.2 上下文压缩Compaction问题Context Rot - 随上下文增长LLM 指令跟随能力逐渐劣化策略智能摘要将旧对话历史压缩为关键信息摘要工具输出截断只保留关键信息全量写磁盘分层存储热数据在上下文冷数据在外部存储# 工具输出截断示例outputresult.stdoutresult.stderriflen(output)2000:outputoutput[:1000]\n...[截断]...\noutput[-500:]4.2.3 自验证循环Self-Verification Loop问题Agent 如果没有外部强制根本不会主动测试代码解决方案强制 Build-Verify 循环1. Plan计划任务分解是否清晰 ↓ 2. Build构建代码是否可编译测试是否已编写 ↓ 3. Verify验证测试是否全部通过是否满足任务要求 ↓ (失败) 4. Fix修复回到步骤 2 ↓ (成功) 完成效果LangChain 在 Terminal Bench 2.0 上从 52.8% 提升到 66.5%从全球第 30 名跃升至第 5 名5. Harness 与传统软件工程的核心区别5.1 根本性差异┌─────────────────────────────────────────────────────────┐ │ 传统软件工程 vs Harness Engineering │ ├─────────────────────────────────────────────────────────┤ │ │ │ 传统工程 Harness 工程 │ │ │ │ 确定性算法 ←→ 非确定性 LLM │ │ (相同输入→相同输出) (输出可能变化) │ │ │ │ 异常捕获、重试 ←→ 分析根因、修改环境 │ │ (让同类失败不再发生) │ │ │ │ 单元测试、集成测试 ←→ Agent Trace 分析 │ │ (自验证循环) │ │ │ │ Code Review ←→ Harness 约束 │ │ 垃圾回收 Agent │ │ │ │ 算法与数据结构 ←→ 环境设计、 │ │ 反馈回路构建 │ │ │ │ 数据库/缓存 ←→ 跨会话进度文件/ │ │ 上下文压缩 │ │ │ └─────────────────────────────────────────────────────────┘5.2 思维转变传统软件工程师思维 Harness 工程师思维 ┌──────────────────┐ ┌──────────────────┐ │ │ │ │ │ 我如何实现 │ → │ 我如何设计 │ │ │ │ 让 AI 实现 │ │ │ │ │ └──────────────────┘ └──────────────────┘ ┌──────────────────┐ ┌──────────────────┐ │ │ │ │ │ 代码怎么写 │ → │ 环境如何设计 │ │ │ │ 让代码正确 │ │ │ │ │ └──────────────────┘ └──────────────────┘OpenAI 工程团队坦言“我们最困难的挑战现在集中在设计环境、反馈回路和控制系统上。工程师的工作从写代码变成了设计让 AI 能写好代码的环境。”6. 关键挑战与解决方案6.1 Challenge 1: 无状态问题问题LLM 天生无状态每次新会话都是失忆重启同样的错误会一遍遍重演Harness 解决方案✅ 结构化进度文件.agent-progress.json✅ 跨会话状态持久化✅ 上下文压缩机制6.2 Challenge 2: Context Rot问题上下文窗口被工具输出、历史记录填满即使支持 100 万 Token性能衰减在 25.6 万 Token 左右便出现LLM 指令跟随能力显著下降Harness 解决方案✅ 智能上下文压缩Compaction✅ 工具输出截断✅ 分层存储策略6.3 Challenge 3: 架构漂移问题AI 生成的代码库随时间累积熵文档与代码脱节命名规范漂移死代码堆积Harness 解决方案✅ 确定性自定义 Linter✅ 后台垃圾回收 Agent✅ 持续的熵管理机制6.4 Challenge 4: 验证缺失问题Agent 如果没有外部强制根本不会主动测试代码Agent 可能在任务未完成时宣布成功幻觉式成功现象Harness 解决方案✅ 强制自验证循环Build-Verify✅ PreCompletionChecklistMiddleware✅ 最终测试套件验证6.5 Challenge 5: 费用失控问题Agent 可能陷入无限重试循环无人监控的 Agent 可能产生巨额 API 账单真实案例$50,000 的一夜损失Harness 解决方案✅ API 调用预算监控与硬限制✅ 循环检测机制✅ 人类审批节点Human-in-Loop✅ 费用上限告警7. 核心术语速查表术语英文一句话解释驾驭工程Harness Engineering围绕 AI Agent 构建约束、反馈、控制的系统工程实践驾驭具Harness围绕 LLM 的一切代码、配置和执行逻辑上下文腐烂Context Rot随上下文增长LLM 指令跟随能力逐渐劣化的现象项目地图AGENTS.md约 100 行的项目导航文件指向深度文档上下文压缩Compaction智能摘要旧上下文防止 Context Rot自验证循环Self-Verification Loop强制 Agent 检验自己工作的机制垃圾回收 AgentGC Agent周期性运行、对抗代码库熵增的后台 Agent架构约束Architectural Constraints通过 Linter 测试机械执行的架构规则可撕裂原则Rippable Harness随模型能力提升主动删除不再需要的 Harness 组件教学时刻Teaching Moment错误信息内嵌修复指引的设计模式