Harness Engineering：重塑AI Agent时代的软件工程

这篇文章把 Harness Engineering 从概念到工程实践的完整知识体系梳理了一遍，包括它和 Prompt Engineering、Context Engineering 到底有什么本质区别，以及三大支柱的设计方法和代码实现。话不多说，先看几个核心判断：

• ✅ 理解 Harness Engineering 为什么在2026年成了最热的工程范式
• ✅ 掌握“Agent = Model + Harness”这个核心公式和架构组件
• ✅ 学会 Harness 的三大支柱：上下文工程、架构约束、熵管理
• ✅ 看懂 OpenAI 那场百万行代码实验背后的 Harness 设计
• ✅ 拿到可以直接落地的 AGENTS.md 模板和最佳实践

1. 为什么“更强的模型”不够用？

你部署了一个无人监控的 AI Agent，让它在后台自主处理任务。凌晨三点，Agent 因为某个边界条件陷入了无限重试循环，每分钟都在不断调用付费 API。等你早上打开账单的时候，已经烧掉了5万美元。

这不是虚构的场景。技术播客 Vanishing Gradients 有一期节目《Why Agent Context Isn't Enough》，真实记录了这起事故，同时点出了一个关键悖论：上下文窗口变大，并不等于 Agent 性能的线性提升。即便模型理论上支持100万 Token 的上下文，性能衰减往往在25.6万 Token 左右就开始出现。这种现象叫做 Context Rot（上下文腐烂）——随着对话历史和工具输出不断堆积，模型的指令跟随能力会显著下降。

更深层的问题在于：LLM 天生就是无状态的（Stateless）。每一次新会话对它来说都是白板一张，完全不记得上次做了什么、犯了什么错。这就意味着：

• 你没法指望“让模型变聪明”来解决系统性失败
• 同样的错误会在不同会话里一遍遍重演
• 没有外部机制，你永远没办法“防止 Agent 做不该做的事”

1.2 “提示词/上下文工程”的边界在哪里？

在 Harness Engineering 出现之前，开发者经历了两个工程范式的演进：

Martin Fowler 在他的分析文章里一针见血地总结过：Harness 包含上下文工程，但走得更远——它管理的是工具执行、状态持久化、架构约束和垃圾回收，让 Agent 生成的代码在架构层面保持长期一致性。

1.3 Harness Engineering 的诞生时刻

这个术语的历史出奇地短，但崛起速度极其惊人：

gantttitle Harness Engineering 术语演进时间线dateFormatYYYY-MM-DDsection 前期铺垫Anthropic 称 Claude Agent SDK 为“通用 Harness” :milestone, 2025-11-01, 0dAakash Gupta 预言“2026 是 Agent Harness 年” :milestone, 2026-01-15, 0dsection 正式命名Mitchell Hashimoto 博客：首次正式命名 HE :milestone, 2026-02-05, 0dOpenAI 发布“百万行代码”实验报告 :milestone, 2026-02-11, 0dMartin Fowler 深度分析文章 :milestone, 2026-02-17, 0dsection 行业爆发LangChain 排名从第30跃升第5 :milestone, 2026-02-25, 0darXiv 论文 2603.05344 发表 :milestone, 2026-03-05, 0d

2026年2月5日，HashiCorp 联合创始人、Terraform 的创造者 Mitchell Hashimoto，在个人博客上写下了这个定义：

六天后，OpenAI 发布了一份历史性的实验报告：一个3人工程师团队，用5个月时间，借助 Codex Agent 构建了超过100万行代码的产品，零行人工手写代码，人均日合并3.5个PR，效率大约是传统模式的10倍。这份报告的名字直接就用上了这个新词：Harness Engineering: Leveraging Codex in an Agent-First World。

2. Agent = Model + Harness：核心架构拆解

2.1 Harness 的本质定义

理解 Harness Engineering 最重要的公式只有一个：

LangChain 的工程师 Vivek Trivedy 给出了最精炼的定义：“如果你不是模型，你就是 Harness。” Harness 是围绕 LLM 的一切代码、配置和执行逻辑——状态管理、工具调度、反馈回路、验证机制、上下文压缩……每一样都属于 Harness 的范畴。

flowchart TBsubgraph Harness["? Agent Harness（驾驭层）"]direction TBCTX["? 上下文管理n（AGENTS.md / 压缩 / RAG）"]TOOL["?️ 工具执行层n（MCP / 沙盒 / 文件系统）"]STATE["? 状态持久化n（进度文件 / 跨会话记忆）"]VERIFY["✅ 验证与约束n（Linter / 结构测试 / 自验循环）"]GC["? 熵管理n（文档一致性 Agent / 周期清洁）"]endsubgraph Model["? LLM 模型（智能核心）"]REASON["推理 / 规划 / 代码生成"]endUser["? 工程师n（设计环境，而非写代码）"] --> HarnessHarness <--> Modelstyle Harness fill:#e3f2fdstyle Model fill:#fff3e0style User fill:#e8f5e9

2.2 Harness 与传统软件工程的核心区别

Harness Engineering 借鉴了大量传统软件工程的概念：模块化设计、状态管理、输入输出处理、测试……但有一个根本性差异：

你正在围绕一个非确定性内核进行工程。

传统组件对相同输入会产生相同输出。LLM 却可能幻觉出不存在的函数调用，也可能在任务明明没完成时宣布“成功”。Harness 必须针对意外行为设计优雅的恢复机制（Graceful Recovery）。

2.3 Harness 核心组件全景

一个生产级 Harness 通常由以下几个关键组件组成：

flowchart TBsubgraph Layer1["? 指令层（Instruction Layer）"]AGENTS["AGENTS.md / CLAUDE.mdn项目地图 + 编码规范"]DOCS["docs/ 目录n设计文档 / 架构文档 / 质量评分"]endsubgraph Layer2["? 执行循环（Execution Loop）"]PLAN["计划（Plan）"]BUILD["构建（Build）"]VERIFY2["验证（Verify）"]FIX["修复（Fix）"]PLAN --> BUILD --> VERIFY2 --> FIX --> PLANendsubgraph Layer3["?️ 约束层（Constraint Layer）"]LINT["自定义 Lintern（含修复指引）"]STRUCT["结构化测试n（架构边界）"]SANDBOX["沙盒环境n（隔离执行）"]endsubgraph Layer4["? 持久化层（Persistence Layer）"]PROGRESS["进度追踪文件n（JSON 格式）"]MEMORY["跨会话记忆n（Shift Handoff）"]COMPACT["上下文压缩n（Compaction）"]endLayer1 --> Layer2Layer2 --> Layer3Layer3 --> Layer4style Layer1 fill:#e3f2fdstyle Layer2 fill:#fff3e0style Layer3 fill:#fce4ecstyle Layer4 fill:#e8f5e9

3. Harness 三大支柱

OpenAI 实验报告经过 Martin Fowler 团队的 Thoughtworks 工程师 Birgitta Böckeler 深度分析后，被归纳为三个彼此依存的支柱。理解这三个支柱，就理解了 Harness Engineering 的全部核心。

3.1 支柱一：上下文工程（Context Engineering）

核心命题很简单：从 Agent 的视角看，任何它在运行时无法访问的内容，都等于不存在。

OpenAI 团队吃过一个惨痛的教训：团队在 Slack 上就某个架构模式达成了共识，但没有写进代码仓库。结果 Codex Agent 在之后的所有会话中，完全无法“知道”这个约定，一次次地走弯路。最后的结论是：知识必须被推送进仓库，成为版本控制下的文档。

他们的上下文工程方案分为两层：

flowchart LRsubgraph MapLayer["?️ 地图层（AGENTS.md ≈ 100行）"]MAP["• 项目结构概览n• 构建 & 测试命令n• 架构约束索引n• 深度文档的入口指针"]endsubgraph DeepLayer["? 深度层（docs/ 目录）"]ARCH["architecture.mdn架构图与分层规则"]DESIGN["design/n每个功能的设计文档"]QUALITY["quality.mdn每个模块的质量评分"]BELIEFS["beliefs.mdnAgent-First 运营原则"]endMapLayer -->|"渐进式披露"| DeepLayerstyle MapLayer fill:#e3f2fdstyle DeepLayer fill:#fff3e0

这里有一个反直觉的设计原则：约束反而提升效率。当 Agent 面对“可以生成任何东西”的开放空间时，它会浪费 Token 去探索死路。而一旦 Harness 通过文档和规则定义了清晰的边界，Agent 就能更快收敛到正确的解决方案。

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

核心命题是：与其告诉 Agent “写好代码”，不如机械地强制执行“好代码”的样子。

OpenAI 团队发现，仅靠提示词约束架构边界是行不通的。他们最终构建了混合执行机制：

• LLM 驱动的代码审查：Agent 在提交 PR 前对自己的变更进行代码审查
• 确定性自定义 Linter：纯代码实现，当 Agent 违反架构边界时，错误信息本身就是修复指南

这是一个相当精妙的设计：错误信息变成了教学时刻（Teaching Moment）。当 Agent 违反了“domain 层不能直接引用 infrastructure 层”的规则，Linter 不只是报告“Architecture violation”，而是直接告诉它：

# ❌ 触发 Linter 错误的代码：# domain/UserService.ja vaimport com.example.infra.DatabaseRepository; # 违反架构约束！# Linter 输出（包含修复指引）：[ARCH-001] domain 层不得直接引用 infrastructure 层。原则：保持依赖方向 domain → application → infrastructure。修复建议：在 application 层定义 UserRepository 接口， 由 infrastructure 层实现该接口。参见：docs/architecture.md#dependency-rules

每一条 Linter 规则背后，都是 Agent 曾经犯过的某个错误。规则库随着项目迭代会越来越健壮。

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

核心命题很直白：AI 生成的代码库，随着时间推移会自然累积“熵”——文档与代码脱节、命名规范漂移、死代码堆积。Harness 需要内置对抗熵增的机制。

OpenAI 团队最初靠人工来解决这个问题：每周五，整个团队要拿出20%的工时，手动清理“AI 垃圾代码”。这显然不可持续。他们的解决方案是：让 Agent 来清洁 Agent 留下的乱摊子。

他们建立了一组后台垃圾回收 Agent，周期性运行：

这些 Agent 生成的清理 PR 通常在一分钟内就能审阅完毕，大部分可以自动合并。

4. 核心组件深探：让 Agent 跨越会话工作

4.1 LLM 无状态问题与跨会话记忆

LLM 无状态，是 Harness 存在的根本原因之一。没有 Harness，每个新会话都像“失忆重启”，好比一个软件项目，每次来的工程师都对之前的工作一无所知。

Anthropic 工程团队在实验中验证了这个问题：Claude 在没有 Harness 的情况下，从高层 Prompt 构建一个生产 Web 应用时持续失败，出现了两种核心模式：

1. 一次性主义（One-Shot Thinking）：Agent 尝试在单个会话中完成所有工作 → 上下文耗尽 → 代码库只完成了一半 → 下次会话浪费 Token 猜测已完成的工作
2. 幻觉式成功：后续会话看到部分进展，直接宣布“任务完成”，根本不去验证任何东西是不是真的能工作

解决方案是结构化进度文件，充当工程师交接班记录：

// .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 上下文压缩（Compaction）与 Context Rot

随着会话延长，上下文窗口会被工具输出、历史记录和推理过程填满。即使是号称支持100万 Token 的模型，实际有效上下文也远比标称值低。LangChain CEO Harrison Chase 指出：

Harness 对抗 Context Rot 的三种策略：

flowchart LRsubgraph 问题["⚠️ Context Rot 三种表现"]P1["历史对话过长n推理能力下降"]P2["工具输出巨大n噪声淹没信号"]P3["技能/工具过多n启动即性能劣化"]endsubgraph 方案["✅ Harness 对策"]S1["上下文压缩n（智能摘要旧内容）"]S2["工具输出截断n（保留头尾，全量写磁盘）"]S3["技能渐进加载n（Lazy Skill Loading）"]endP1 --> S1P2 --> S2P3 --> S3style 问题 fill:#ffebeestyle 方案 fill:#e8f5e9

4.3 自验证循环（Self-Verification Loop）

最被低估的 Harness 组件是强制 Agent 检验自己的工作。LangChain 的实验揭示了一个惊人的事实：Agent 如果没有外部强制，根本不会主动测试代码。

LangChain 在 Harness 中引入了 PreCompletionChecklistMiddleware：在 Agent 准备标记任务完成之前，强制执行一个四步验证清单：

1. Plan（计划）：任务分解是否清晰？
2. Build（构建）：代码是否可编译？测试是否已编写？
3. Verify（验证）：测试是否全部通过？是否满足任务要求？
4. Fix（修复）：如果不通过，回到步骤2

这个简单的 Build-Verify 循环，直接把他们的 Coding Agent 在 Terminal Bench 2.0 上的得分从52.8%提升到了66.5%，从全球第30名跃升至第5名，而底层模型一个参数都没有改变。

5. 横向对比：三代工程范式全景

5.1 Prompt / Context / Harness Engineering 三角关系

这三种范式不是替代关系，而是嵌套包含的关系：

flowchart LRsubgraph HE["?️ Harness Engineering（最外层）n管理：环境、约束、验证、生命周期"]subgraph CE["? Context Engineering（中间层）n管理：信息注入、RAG、记忆、上下文优化"]subgraph PE["✏️ Prompt Engineering（核心层）n管理：单次调用的指令质量"]endendendstyle HE fill:#e3f2fdstyle CE fill:#fff3e0style PE fill:#e8f5e9

5.2 主流 Harness 实现框架对比

6. 代码实战：从零搭建一个基础 Harness

6.1 第一步：编写 AGENTS.md（项目地图）

这是 Harness 最低成本、最高回报的起点。Mitchell Hashimoto 的建议是从小开始，每当 Agent 犯错就补充一条规则。

## 项目概览这是一个用户认证服务，使用 Spring Boot + PostgreSQL。## 构建命令- 完整构建：`./gradlew build`- 运行测试：`./gradlew test`- 启动服务：`./gradlew bootRun`## 架构约束- 依赖方向严格遵循：domain → application → infrastructure- infrastructure 层不得直接被 domain 层引用- 所有数据库操作必须通过 Repository 接口## 编码规范- 使用懒加载（Lazy Loading），N+1 问题用 fetch join 解决- 提交信息用中文，句末不加句号- 新增 API 端点必须同时更新 docs/api.md## 关键文档索引- 架构图：docs/architecture.md- API 文档：docs/api.md- 质量评分：docs/quality.md

6.2 第二步：Python 实现基础验证循环 Harness

# harness.py — 基础 Agent Harness 实现# 依赖：pip install anthropicimport jsonimport subprocessimport anthropicfrom pathlib import Pathfrom datetime import datetimeclient = anthropic.Anthropic()# ─── 工具定义 ────────────────────────────────────────tools = [{"name": "read_file","description": "读取项目文件内容","input_schema": {"type": "object","properties": {"path": {"type": "string", "description": "相对路径"}},"required": ["path"]}},{"name": "write_file","description": "写入或更新文件","input_schema": {"type": "object","properties": {"path": {"type": "string"},"content": {"type": "string"}},"required": ["path", "content"]}},{"name": "run_command","description": "执行 shell 命令（构建/测试/Lint）","input_schema": {"type": "object","properties": {"command": {"type": "string", "description": "要执行的命令"}},"required": ["command"]}}]# ─── 工具执行层（Harness 核心） ───────────────────────def execute_tool(tool_name: str, tool_input: dict) -> str:"""工具调度：将 LLM 的工具调用映射到真实执行"""if tool_name == "read_file":try:return Path(tool_input["path"]).read_text()except FileNotFoundError:return f"错误：文件 {tool_input['path']} 不存在"elif tool_name == "write_file":Path(tool_input["path"]).parent.mkdir(parents=True, exist_ok=True)Path(tool_input["path"]).write_text(tool_input["content"])return f"✅ 已写入 {tool_input['path']}"elif tool_name == "run_command":result = subprocess.run(tool_input["command"], shell=True,capture_output=True, text=True, timeout=60)# 工具输出截断：只保留关键信息，防止 Context Rotoutput = result.stdout + result.stderrif len(output) > 2000:output = output[:1000] + "n...[截断]...n" + output[-500:]return output or "(无输出)"return f"未知工具: {tool_name}"# ─── 跨会话状态管理 ───────────────────────────────────def load_progress(task_id: str) -> dict:"""加载上次会话的进度（Harness 跨会话记忆）"""progress_file = Path(f".progress/{task_id}.json")if progress_file.exists():return json.loads(progress_file.read_text())return {"completed_steps": [], "current_step": None}def sa ve_progress(task_id: str, progress: dict):"""保存当前进度，供下次会话恢复"""Path(".progress").mkdir(exist_ok=True)progress["last_updated"] = datetime.now().isoformat()Path(f".progress/{task_id}.json").write_text(json.dumps(progress, ensure_ascii=False, indent=2))# ─── 核心 Harness ReAct 循环 ──────────────────────────def run_agent(task: str, task_id: str, max_steps: int = 20):"""Harness 驱动的 Agent 主循环关键设计：失败时分析根因，而非盲目重试"""# 1. 加载跨会话进度（解决 LLM 无状态问题）progress = load_progress(task_id)# 2. 注入 AGENTS.md（上下文工程）agents_md = Path("AGENTS.md").read_text() if Path("AGENTS.md").exists() else ""# 3. 构建系统提示（内嵌 Build-Verify 强制循环）system_prompt = f"""你是一位专注的工程 Agent。严格遵循以下工作流：1. **Plan**：将任务分解为具体步骤2. **Build**：实现代码，同时编写测试3. **Verify**：运行测试，确认全部通过4. **Fix**：如果测试失败，修复代码，回到步骤 3项目规范（来自 AGENTS.md）：{agents_md}上次会话进度：{json.dumps(progress, ensure_ascii=False)}已完成步骤：{progress.get('completed_steps', [])}当前步骤：{progress.get('current_step', '未开始')}规则：- 完成每个步骤后，运行测试验证- 不得在测试失败时标记步骤为完成- 发现约束违反时，自行修复后继续""".strip()messages = [{"role": "user", "content": task}]# 4. Agent 执行循环（Harness 控制层）for step in range(max_steps):response = client.messages.create(model="claude-opus-4-6",max_tokens=4096,system=system_prompt,tools=tools,messages=messages)# 5. 处理工具调用（工具执行层）if response.stop_reason == "tool_use":tool_results = []for block in response.content:if block.type == "tool_use":result = execute_tool(block.name, block.input)tool_results.append({"type": "tool_result","tool_use_id": block.id,"content": result})messages.append({"role": "assistant", "content": response.content})messages.append({"role": "user", "content": tool_results})# 6. 任务完成（Pre-Completion Check）elif response.stop_reason == "end_turn":# 强制最终验证：运行完整测试套件final_check = execute_tool("run_command", {"command": "pytest -v 2>&1 | tail -20"})if "FAILED" in final_check:# Harness 介入：不允许在测试失败时宣布完成messages.append({"role": "assistant", "content": response.content})messages.append({"role": "user","content": f"⚠️ 检测到测试失败，任务未完成。nn{final_check}nn请修复所有失败的测试。"})continue# 保存进度并退出sa ve_progress(task_id, {"completed_steps": ["ALL"], "status": "done"})print("✅ 任务完成，所有测试通过")return response# 超过最大步骤：保存进度，等待下次恢复sa ve_progress(task_id, progress)print(f"⏸️ 达到最大步骤 {max_steps}，进度已保存")return None# ─── 入口 ─────────────────────────────────────────────if __name__ == "__main__":run_agent(task="实现 JWT 用户认证模块，包含登录、登出、Token 刷新，并编写完整测试",task_id="feature-jwt-auth")

6.3 第三步：LangChain 中间件 Harness 架构

LangChain 的 Harness 采用可组合中间件模式，每层职责单一、可独立测试：

# langchain_harness.py — 中间件模式 Harness 示例# 依赖：pip install langchain langchain-corefrom langchain_core.runnables import Runnable, RunnablePassthroughclass LocalContextMiddleware:"""映射代码库结构，注入项目环境信息"""def invoke(self, state):state["context"] = {"dir_structure": self._scan_project(),"a vailable_tools": ["python", "pytest", "git"]}return stateclass LoopDetectionMiddleware:"""检测 Agent 循环，防止无限重试"""def __init__(self):self.seen_actions = set()def invoke(self, state):action_key = str(state.get("last_action"))if action_key in self.seen_actions:state["force_break"] = True# 触发 Harness 干预self.seen_actions.add(action_key)return stateclass ReasoningSandwichMiddleware:"""推理三明治：高推理力用于规划/验证，中等用于执行避免在简单步骤上浪费高推理 Token"""def invoke(self, state):if state["phase"] in ("plan", "verify"):state["reasoning_effort"] = "high"else:state["reasoning_effort"] = "medium"return stateclass PreCompletionChecklistMiddleware:"""完成前强制验证清单（Harness 最关键的组件之一）"""def invoke(self, state):if state.get("agent_says_done"):checks = [self._run_tests(),# 测试是否通过self._check_lint(), # Lint 是否清洁self._verify_docs(),# 文档是否已更新]state["completion_approved"] = all(checks)return state

7. 最佳实践：构建可持续的 Harness

7.1 渐进构建：不要一步到位

初学者最容易犯的错误，是试图在第一天就构建一个完整的 Harness。正确的做法是渐进演进：

flowchart LRS1["Day 1n? 创建 AGENTS.mdn+基础构建命令"] --> S2["Week 1n? 加入自验证循环n+运行测试的工具"]S2 --> S3["Month 1n? 第一个自定义 Lintern（来自真实错误）"]S3 --> S4["Month 3n? 跨会话状态管理n+进度追踪文件"]S4 --> S5["Month 6n? 后台 GC Agentn+完整 Harness 生态"]style S1 fill:#e8f5e9style S5 fill:#e3f2fd

7.2 常见问题与解决方案

7.3 Harness 健壮性自检清单

在认为 Harness 可以上生产之前，逐条检查：

8. 行业格局与未来展望

8.1 三大 Harness 流派的分歧

2026年初，业界在 Harness Engineering 上已有若干共识，也存在若干分歧：

已形成共识的方面：

• 瓶颈在基础设施，不在模型智能
• AGENTS.md 是 Harness 的必要起点
• 自定义 Linter 的错误信息应内嵌修复指引
• 跨会话状态管理是长任务必需品

仍存分歧的方面：

8.2 Harness Engineering 的未来方向

mindmaproot((Harness 未来))自演化 HarnessAgent 分析自身 Trace 后优化 Harness规则自动从失败案例中提炼并发 Harness数百个 Agent 并行工作于同一代码库跨 Agent 的协调与冲突解决跨模型 Harness单一 Harness 适配多个底层模型模型热切换而不影响产品行为Harness 即服务团队共享 Harness 模板（类黄金路径）行业垂直 Harness（金融 / 医疗 / 法律）

LangChain 正在探索让 Agent 分析自身执行 Trace，自动识别并修复 Harness 层面的失败模式；而“百 Agent 并发共享代码库”的协调问题，将成为下一个重大工程挑战。

9. 总结