---
layout: single
title:  "一文读懂 Harness Engineering：AI 时代软件工程的全新范式"
date:   2026-03-30 12:00:00 +0800
categories: [AI 与大模型, DevOps]
tags: [Agent, HarnessEngineering]
---

本文综合 Anthropic、OpenAI、Martin Fowler、LangChain、Mitchell Hashimoto、NxCode、MiniMax 等前沿文章的分析报告。

<!-- more -->

## 一、什么是 Harness Engineering？

### 1.1 词源与隐喻

"Harness" 直译为"马具"——缰绳、鞍座、嚼子，是用来驾驭一匹强大但不可预测的动物的工具。这个隐喻极其精准：

| 隐喻 | 对应实体 |
|------|---------|
| **马匹** | AI 模型——强大、快速，但自身不知道该去哪里 |
| **马具（Harness）** | 基础设施——约束、护栏、反馈循环，引导模型的力量 |
| **骑手** | 人类工程师——提供方向，而不是亲自奔跑 |

没有 Harness 的 AI Agent 就像旷野中的野马——速度快、令人印象深刻，但对完成任何目标完全无用。

### 1.2 正式定义

**Harness Engineering** 是设计和实现以下系统的学科：

1. **约束（Constrain）**——限制 AI Agent 能做什么（架构边界、依赖规则）
2. **告知（Inform）**——告诉 Agent 它该做什么（上下文工程、文档）
3. **验证（Verify）**——检查 Agent 是否正确完成了任务（测试、Linter、CI）
4. **纠正（Correct）**——当 Agent 出错时进行修复（反馈循环、自我修复机制）

### 1.3 与相关概念的区别

| 概念 | 范围 | 焦点 |
|------|------|------|
| **提示工程（Prompt Engineering）** | 单一交互 | 设计有效的 prompt |
| **上下文工程（Context Engineering）** | 模型上下文窗口 | 模型看到什么信息 |
| **Harness Engineering** | **整个 Agent 系统** | 环境、约束、反馈、生命周期 |
| **Agent Engineering** | Agent 内部架构 | 内部 Agent 设计和路由 |
| **平台工程（Platform Engineering）** | 基础设施 | 部署、扩展、运维 |

Harness Engineering **包含** 上下文工程，并借鉴了提示工程，但它在更高的层面上运作——它关乎使 Agent 可靠的**完整系统**，而不仅仅是单一交互的输入。

> **Martin Fowler 团队的总结**："Harness Engineering 不是简单的'提示词工程'，而是一套完整的工程实践和工具链，用于在 AI 大规模参与编码的背景下保持系统质量和可维护性。"

---

## 二、为什么 Harness Engineering 如此重要？

### 2.1 核心论点：模型是商品，Harness 是护城河

LangChain 提供了最令人信服的量化证据：

- **初始状态**：使用 GPT-5.2-Codex 的 Agent 在 Terminal Bench 2.0 上得分 **52.8%**（Top 30 之外）
- **仅优化 Harness**：模型完全不变，通过改进 Harness 系统，得分提升至 **66.5%**（**Top 5**）

**相同的模型，不同的 Harness，截然不同的结果。**

### 2.2 OpenAI 的 100 万行代码实证

OpenAI 团队进行了迄今最大胆的实验：

- **5 个月**的开发时间
- 超过 **100 万行**代码
- **零**行人类手写代码——每一行都由 Codex Agent 生成
- 构建时间约为人类所需时间的 **1/10**
- 产品拥有内部日常用户和外部 Alpha 测试者
- 发布、部署、故障修复——全部由 Harness 系统内的 Agent 完成

工程师的职责？**设计 Harness。明确意图。提供反馈。不编写代码。**

### 2.3 Anthropic 的前后对比

Anthropic 的实验更直观地展示了 Harness 的价值：

| 指标 | 单 Agent | 多 Agent + 完整 Harness |
|------|---------|----------------------|
| **案例：复古游戏工具** | 20 分钟，$9 | 6 小时，$200 |
| **功能完整性** | 核心功能损坏 | 功能丰富，包含 AI 辅助等高级特性 |
| **可用性** | 无法正常游玩 | 完全可玩 |

### 2.4 工程师角色的根本转变

| 角色职责 | 传统工程 | Harness Engineering |
|---------|---------|-------------------|
| 编写代码 | 主要工作 | **从不** |
| 设计架构 | 工作的一部分 | **主要工作** |
| 编写文档 | 事后想法 | **关键基础设施** |
| 评审 PR | 代码评审 | 评审 Agent 输出 + Harness 有效性 |
| 调试 | 阅读代码 | **分析 Agent 行为模式** |
| 编写测试 | 编写测试 | 设计 Agent 执行的测试策略 |

> **OpenAI**："最困难的挑战已从编写代码转向设计环境、反馈循环和控制系统。"

---

## 三、Harness Engineering 的三大支柱

基于 OpenAI 的框架，并被 Martin Fowler、NxCode 等多方验证，Harness Engineering 分为三个核心支柱：

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

**核心原则**：从 Agent 的角度来看，它在上下文中无法访问的任何东西都是不存在的。

#### 静态上下文
- 架构规范、API 合约、风格指南（存入代码仓库）
- `AGENTS.md` 或 `CLAUDE.md` 文件——记录 Agent 需要遵循的项目特定规则
- 交叉链接的设计文档（由 Linter 验证链接有效性）

#### 动态上下文
- Agent 可访问的可观测性数据（日志、指标、追踪）
- Agent 启动时的目录结构映射
- CI/CD 流水线状态和测试结果

#### 关键实践
- **代码仓库是唯一真相源**——所有决策、文档、计划都必须在仓库中，不能散落在 Slack、Google Docs 或人们的大脑里
- **渐进式披露**——使用简洁的 `AGENTS.md` 作为"目录"，而非冗长的百科全书
- **上下文重置**——Anthropic 发现长任务中模型会出现"上下文焦虑"和性能下降，定期重置上下文可有效缓解

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

**这是 Harness Engineering 与传统 AI 提示工程最显著的区别**——不是告诉 Agent "编写好的代码"，而是**机械地强制执行**好代码的样式。

#### 约束执行工具

| 工具类型 | 描述 | 示例 |
|---------|------|------|
| **自定义 Linter** | 自动标记违规的规则引擎 | 依赖方向检查、命名约定 |
| **结构测试** | 验证架构边界的测试（类似 ArchUnit） | `Types → Config → Repo → Service → Runtime → UI` 分层 |
| **预提交钩子** | 提交前的自动检查 | 格式化、lint、基础测试 |
| **LLM 审计器** | 审查其他 Agent 代码是否符合架构规范 | 代码审查 Agent |

#### 核心洞察：约束即赋能

> **矛盾的是，约束解决方案空间使 Agent 更高效，而非更低效。** 当 Agent 可以生成任何东西时，它会浪费 token 探索死胡同。当 Harness 定义了清晰的边界时，Agent 能更快地收敛到正确的解决方案。

### 支柱三：熵管理（"垃圾回收"）

**这是最被低估的组件。** AI 生成的代码库会积累熵——文档与现实脱节、命名约定分歧、死代码堆积、架构漂移。

#### 熵管理 Agent

| Agent 类型 | 职责 |
|-----------|------|
| **文档一致性 Agent** | 验证文档是否与当前代码匹配 |
| **约束违规扫描器** | 查找绕过早期检查的代码 |
| **模式执行 Agent** | 识别并修复与已建立模式的偏差 |
| **依赖审计器** | 跟踪并解决循环或不必要的依赖关系 |

#### MiniMax 的"自进化"范式

MiniMax M2.7 将熵管理推向了新的高度——Agent 不仅维护现有系统，还能**自主进化自己**：

```
分析失败轨迹 → 规划变更 → 修改工具链代码 → 运行评估 → 对比结果 → 决定保留或回滚
```

在超过 100 轮迭代中，M2.7 自动优化了采样参数、工作流指南和循环检测机制，最终性能提升 30%。

---

## 四、Harness 的架构模式

### 4.1 Anthropic 的多 Agent 架构

Anthropic 借鉴了 GAN（生成对抗网络）的"生成器-评估器"对抗循环思想：

**初始架构（基于 Claude Sonnet 4.5）**：
```
规划器（Planner）→ 生成器（Generator）→ 评估器（Evaluator）→ 反馈循环
         ↑                                              |
         └──────────────────────────────────────────────┘
```
- **规划器**：将用户需求扩展为详细产品规格
- **生成器**：采用"冲刺"模式，每次只实现一个功能
- **评估器**：使用 Playwright 等工具实际测试应用
- **关键机制**：上下文重置，解决长任务中的性能下降

**演进后架构（基于 Claude Opus 4.6）**：
随着模型能力的提升，Harness 得以**简化**——移除了冲刺结构，评估器变为可选。这揭示了一个重要原则：**Harness 应该随模型进化而迭代，不断移除不再必要的组件。**

### 4.2 LangChain 的中间件架构

LangChain 将 Harness 构建为可组合的中间件层：

```
Agent 请求
  → LocalContextMiddleware（映射代码库）
  → LoopDetectionMiddleware（防止重复编辑）
  → ReasoningSandwichMiddleware（优化推理计算）
  → PreCompletionChecklistMiddleware（强制验证）
→ Agent 响应
```

每个中间件层增加特定功能，不修改核心 Agent 逻辑。这种模块化方法使 Harness **可测试、可组合、可演进**。

### 4.3 Mitchell Hashimoto 的实用方法

HashiCorp 联合创始人 Mitchell Hashimoto 从实践者角度提出了更接地气的 Harness 策略：

- **AGENTS.md**：记录 Agent 常见错误并制定规则（[Ghostty 项目示例](https://github.com/ghostty-org/ghostty)）
- **验证工具**：开发自动截图、测试脚本，帮助 Agent 自我纠正
- **每天结束前启动 Agent**：利用非工作时间执行后台任务（调研、Issue 分类）
- **外包简单任务**：将高成功率任务交给 Agent，自己专注复杂工作

---

## 五、关键设计模式与技巧

### 5.1 自验证循环（Build & Self-Verify）

**问题**：Agent 常编写代码后就停止，缺乏测试验证。

**解决方案**（LangChain 的四阶段流程）：
1. **规划与探索**：阅读任务、扫描代码库、制定计划
2. **构建**：实现计划并编写测试（包括正常路径和边缘情况）
3. **验证**：运行测试，对比任务要求（而非代码自身）
4. **修复**：分析错误并修正

引入 `PreCompletionChecklistMiddleware`：在 Agent 退出前**强制**其执行验证步骤。

### 5.2 循环检测（Loop Detection）

**问题**：Agent 陷入"毁灭循环"——反复微调错误方案。

**解决方案**：通过钩子跟踪单文件编辑次数，若超过阈值则提示 Agent "重新评估当前方案"。

### 5.3 推理资源分配（Reasoning Sandwich）

**问题**：过度推理导致超时，不足则影响性能。

**解决方案**：采用 **xhigh-high-xhigh** 的"推理三明治"模式：
- **规划阶段**：高推理预算
- **实现阶段**：中等推理预算
- **验证阶段**：高推理预算

| 推理策略 | 得分 |
|---------|------|
| 全程 xhigh | 53.9%（超时过多）|
| 全程 high | 63.6% |
| 推理三明治 | **66.5%** |

### 5.4 评估标准的量化设计

Anthropic 将主观任务（如前端设计质量）转化为可量化的评分标准：

| 维度 | 描述 | 权重 |
|------|------|------|
| 设计质量 | 整体感和一致性 | 高 |
| 原创性 | 定制化决策 vs 模板/AI 生成模式 | 高 |
| 工艺 | 排版、间距、色彩等技术执行 | 中 |
| 功能性 | 独立于美学的可用性 | 中 |

通过对评估 Agent 进行少量样本校准，确保评判标准与人类偏好一致。

### 5.5 上下文注入与时间预算

- **LocalContextMiddleware**：启动时自动映射工作目录、工具路径，减少环境探索错误
- **时间预算提醒**：注入时间限制警告，促使 Agent 合理分配构建与验证时间

---

## 六、构建 Harness 的实践路径

### 级别 1：基础 Harness（个人开发者）

**设置时间**：1-2 小时

- `CLAUDE.md` 或 `.cursorrules` 文件（项目约定）
- 预提交钩子（代码检查和格式化）
- Agent 可运行的测试套件
- 清晰的目录结构和命名规则

**影响**：防止最常见的 Agent 错误

### 级别 2：团队 Harness（小团队，3-10 人）

**设置时间**：1-2 天

- 在级别 1 基础上增加：
- 团队范围的 `AGENTS.md`
- 由 CI 强制执行的架构约束
- 常见任务的共享 prompt 模板
- 由 Linter 验证的"文档即代码"
- 针对 Agent 生成 PR 的代码评审检查清单

**影响**：确保团队间 Agent 行为的一致性

### 级别 3：生产级 Harness（工程组织）

**设置时间**：1-2 周

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

**影响**：Agent 作为自主贡献者运作

---

## 七、常见错误与陷阱

### ❌ 过度设计控制流
下一次模型更新可能会破坏你的精心设计。构建 Harness 时要考虑其"**可剥离性**"——当模型足够智能时，应该能移除复杂的逻辑。

### ❌ 将 Harness 视为静态
Harness 需要随模型演进。每次主要模型更新时，都应审查和更新 Harness 组件。

### ❌ 忽视文档层
最具影响力的 Harness 改进往往是最简单的：**更好的文档**。投资于精确的、机器可读的文档。

### ❌ 没有反馈循环
没有反馈的 Harness 是牢笼，而非指南。Agent 需要知道何时成功、何时失败。

### ❌ 仅限人类访问的文档
架构决策存在于人们的大脑中或 Agent 无法访问的 Confluence 页面 = Harness 存在缺口。Agent 所需的一切都必须存在于**代码仓库**中。

---

## 八、各文章独特贡献总结

| 文章 | 核心贡献 |
|------|---------|
| **Anthropic** | GAN 灵感的多 Agent 架构（规划器-生成器-评估器）；上下文重置机制；主观任务量化评估方法；随模型进化简化 Harness 的实证 |
| **OpenAI** | 首次提出"Harness Engineering"术语；100 万行零人工代码实验；三大支柱框架（上下文、约束、熵管理）；工程师角色转型的完整描述 |
| **Martin Fowler** | 对 OpenAI 框架的独立分析验证；强调"约束即赋能"；提出 Harness 作为新型服务模板的未来方向；AI 友好技术栈的趋势预测 |
| **LangChain** | 中间件架构模式（可组合的 Harness）；量化证明 Harness 的价值（同一模型 Top 30→Top 5）；循环检测、推理三明治、自验证循环等具体技巧 |
| **Mitchell Hashimoto** | 从个人实践者角度出发；AGENTS.md 实践；每天结束前启动 Agent 的工作模式；强调保留复杂任务给人类以维持技能成长 |
| **NxCode** | 最全面的整合指南；三级 Harness 成熟度模型；与其他概念的对比分析；Stripe Minions 案例补充 |
| **MiniMax** | 将 Harness Engineering 推向"自进化"新范式；Agent 自主修改自身工具链；多 Agent 协作与对抗推理；100 轮自动迭代的实验数据 |

---

## 九、核心结论

### 1. Harness 是新的竞争力

模型能力趋于同质化的今天，**Harness 的质量决定了 AI 辅助开发的天花板**。LangChain 的实验完美证明：同一个模型，好的 Harness 可以将性能从 Top 30 提升到 Top 5。

### 2. 工程师不会消失，而是进化

Harness Engineering 不是取代工程师，而是将工程师的角色从"代码工人"提升为"**系统设计师**"。这个新角色需要更深层的架构思维、系统思维和规范编写能力。

### 3. 从简单开始，持续迭代

Anthropic 和 Mitchell 都强调同一个原则：**从简开始**。一个精心编写的 `AGENTS.md` 和基础的预提交钩子，比复杂的中间件更有影响力。同时，随着模型能力的提升，Harness 应该相应简化——移除不再需要的组件。

### 4. 代码仓库即唯一真相源

所有知识（设计文档、架构图、产品规范、执行计划）都必须以版本化的方式存入代码仓库。Slack 中的讨论、Google Docs 里的规范、人们大脑中的架构决策——这些对 Agent 来说都是"不存在的"。

### 5. 未来方向：自进化系统

MiniMax 的实验预示了 Harness Engineering 的下一个阶段——Agent 不仅能被 Harness 驾驭，还能**自主改进自己的 Harness**。当"设计-执行-评估-改进"的循环完全由 AI 自主完成时，真正的自进化 AI 系统就诞生了。

---

*"如果说 2025 年是 AI Agent 证明它们可以编写代码的一年，那么 2026 年就是我们认识到难点不在于 Agent 本身，而在于 Harness 的一年。"* — NxCode