文章目录
-
- [1. Harness Engineering 的本质定义](#1. Harness Engineering 的本质定义)
-
- [1.1 核心定义](#1.1 核心定义)
- [1.2 诞生的历史时刻](#1.2 诞生的历史时刻)
- [1.3 "Harness" 的本意](#1.3 "Harness" 的本意)
- [2. Agent = Model + Harness 核心公式](#2. Agent = Model + Harness 核心公式)
-
- [2.1 公式解读](#2.1 公式解读)
- [2.2 LangChain 工程师的精炼定义](#2.2 LangChain 工程师的精炼定义)
- [2.3 类比：CPU 与操作系统](#2.3 类比：CPU 与操作系统)
- [3. Harness 三大支柱详解](#3. Harness 三大支柱详解)
-
- [3.1 支柱一：上下文工程（Context Engineering）🎯](#3.1 支柱一：上下文工程（Context Engineering）🎯)
- [3.2 支柱二：架构约束（Architectural Constraints）🎯](#3.2 支柱二：架构约束（Architectural Constraints）🎯)
-
- 核心命题
- [OpenAI 的发现](#OpenAI 的发现)
- 精妙设计：错误信息即教学时刻
- 规则库的演进
- [3.3 支柱三：熵管理（Entropy Management）🎯](#3.3 支柱三：熵管理（Entropy Management）🎯)
-
- 核心命题
- [OpenAI 的初始方案（不可持续）](#OpenAI 的初始方案（不可持续）)
- [最终方案：让 Agent 清洁 Agent 的烂摊子](#最终方案：让 Agent 清洁 Agent 的烂摊子)
- [Mitchell Hashimoto 理念的系统化体现](#Mitchell Hashimoto 理念的系统化体现)
- [4. Harness 核心组件全景](#4. Harness 核心组件全景)
-
- [4.1 组件架构图](#4.1 组件架构图)
- [4.2 关键组件详解](#4.2 关键组件详解)
-
- [4.2.1 跨会话状态管理（Cross-Session State）](#4.2.1 跨会话状态管理（Cross-Session State）)
- [4.2.2 上下文压缩（Compaction）](#4.2.2 上下文压缩（Compaction）)
- [4.2.3 自验证循环（Self-Verification Loop）](#4.2.3 自验证循环（Self-Verification Loop）)
- [5. Harness 与传统软件工程的核心区别](#5. Harness 与传统软件工程的核心区别)
-
- [5.1 根本性差异](#5.1 根本性差异)
- [5.2 思维转变](#5.2 思维转变)
- [6. 关键挑战与解决方案](#6. 关键挑战与解决方案)
-
- [6.1 Challenge 1: 无状态问题](#6.1 Challenge 1: 无状态问题)
- [6.2 Challenge 2: Context Rot](#6.2 Challenge 2: Context Rot)
- [6.3 Challenge 3: 架构漂移](#6.3 Challenge 3: 架构漂移)
- [6.4 Challenge 4: 验证缺失](#6.4 Challenge 4: 验证缺失)
- [6.5 Challenge 5: 费用失控](#6.5 Challenge 5: 费用失控)
- [7. 核心术语速查表](#7. 核心术语速查表)
1. Harness Engineering 的本质定义
1.1 核心定义
Harness Engineering 是指围绕 AI Agent（特别是 Coding Agent）设计和构建约束机制、反馈回路、工作流控制和持续改进循环的系统工程实践。
它解决的核心问题是：当 AI Agent 拥有了强大的代码生成能力后，如何确保其输出的可靠性、一致性和长期可维护性。
1.2 诞生的历史时刻
2026年2月5日
Mitchell Hashimoto（HashiCorp 联合创始人、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 │ → │ (驾驭系统) │
│ (让能力可用) │ │ (让智能有用) │
└─────────────┘ └─────────────┘
"模型是 CPU，Harness 是操作系统------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 设计原则
markdown
<!-- ✅ 好的 AGENTS.md：导航地图 -->
## 项目概览
用户认证服务，Spring Boot + PostgreSQL
## 构建命令
- 完整构建：`./gradlew build`
- 运行测试：`./gradlew test`
## 架构约束
- 依赖方向：domain → application → infrastructure
- 详见：docs/architecture.md#dependency-rules
## 编码规范
- 使用懒加载，N+1 用 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) │ │
│ └────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘精妙设计：错误信息即教学时刻
java
// ❌ 触发 Linter 错误的代码：
// domain/UserService.java
import com.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 {
Optional<User> 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 天生无状态，每次新会话都是"失忆重启"
解决方案：结构化进度文件
json
// .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 指令跟随能力逐渐劣化
策略：
- 智能摘要：将旧对话历史压缩为关键信息摘要
- 工具输出截断：只保留关键信息，全量写磁盘
- 分层存储：热数据在上下文，冷数据在外部存储
python
# 工具输出截断示例
output = result.stdout + result.stderr
if len(output) > 2000:
output = output[:1000] + "\n...[截断]...\n" + output[-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 检验自己工作的机制 |
| 垃圾回收 Agent | GC Agent | 周期性运行、对抗代码库熵增的后台 Agent |
| 架构约束 | Architectural Constraints | 通过 Linter + 测试机械执行的架构规则 |
| 可撕裂原则 | Rippable Harness | 随模型能力提升主动删除不再需要的 Harness 组件 |
| 教学时刻 | Teaching Moment | 错误信息内嵌修复指引的设计模式 |