my_wiki/wiki/concepts/Harness-Engineering-Complete-Guide.md

---
title: "Harness 工程完整指南"
source: "https://www.nxcode.io/resources/news/harness-engineering-complete-guide-ai-agent-codex-2026"
author: "NxCode Team"
published: 2026-03-01
last_updated: 2026-04-11
tags:
  - concepts
  - harness-engineering
raw_sources:
  - path: raw/Harness Engineering The Complete Guide to Building Systems That Make AI Agents Actually Work (2026).md
    hash: "sha256:9d6e5bbc3d3a10bb9d027137d2a8040fbb16fccd7db904e0fef4b5cc93f57313"
---

# Harness 工程完整指南

## 页面定位
本页是 Harness 工程的完整指南（NxCode 来源案例页）：概念与隐喻、实践模式、实施路径。负责该来源的完整叙事；统一定义与六大维度见 [[Harness-Engineering|Harness 工程]] 核心页，其他来源案例见 [[Meta-Harness|Meta-Harness]] 等页。

如果说 2025 年是 AI 智能体证明它们可以编写代码的一年，那么 2026 年就是我们认识到**智能体不是难点——Harness 才是**的一年。

OpenAI 的 Codex 团队刚刚构建了一个生产应用程序，**超过 100 万行代码**，其中**零行是由人工手写的**。工程师没有编写代码。他们设计了让 AI 可靠编写代码的系统。那个系统——约束、反馈循环、文档、linter 和生命周期管理——就是行业现在所称的 **Harness**。

**Harness 工程**是设计这些系统的新学科。它正在改变软件工程师的含义。

---

## 什么是 Harness 工程？

### 马的隐喻

"Harness" 一词来自马具——缰绳、马鞍、衔铁——用于将强大但不可预测的动物引导到正确方向的完整设备集。这个隐喻是有意的：

- **马**是 AI 模型——强大、快速，但它自己不知道去哪里
- **Harness**是基础设施——约束、护栏、反馈循环，以富有成效地引导模型的力量
- **骑手**是人类工程师——提供方向，而不是亲自奔跑

没有 Harness，AI 智能体就像开放领域中的纯种马。快速、令人印象深刻，但完全无法完成任何有用的事情。

### 正式定义

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

1. **约束** AI 智能体可以做什么（架构边界、依赖规则）
2. **告知** 智能体应该做什么（上下文工程、文档）
3. **验证** 智能体正确完成了工作（测试、linting、CI 验证）
4. **纠正** 智能体出错时的问题（反馈循环、自我修复机制）

Martin Fowler 将其描述为*"我们可以用来控制 AI 智能体的工具和实践"*——但这不仅仅是安全。一个好的 Harness 使智能体**更有能力**，而不仅仅是更受控制。

---

## 为什么 Harness 工程现在很重要

### 模型是商品，Harness 是护城河

AI 行业正在面对的令人不安的事实是：**底层模型的重要性不如其周围的系统。**

LangChain 明确证明了这一点。他们的编码智能体在 Terminal Bench 2.0 上从 **52.8% 提升到 66.5%**——从 **前 30 名跃升至前 5 名**——通过只改变 Harness，模型本身没有任何变化：

| 更改 | 他们做了什么 | 影响 |
|------|-------------|------|
| 自我验证循环 | 添加完成前检查清单中间件 | 在提交前捕获错误 |
| 上下文工程 | 启动时映射目录结构 | 智能体从一开始就理解代码库 |
| 循环检测 | 跟踪重复的文件编辑 | 防止"末日循环" |
| 推理三明治 | 规划/验证使用高推理，实现使用中推理 | 在时间预算内提高质量 |

**相同的模型。不同的 Harness。显著更好的结果。**

### OpenAI 的 100 万行代码证明点

OpenAI 的实验是迄今为止最引人注目的证据：

- **5 个月**的开发
- 最终产品中**超过 100 万行代码**
- **零手动编写的行**——每一行都是由 Codex 智能体生成的
- **以人类所需时间的约 1/10 构建**
- 产品有**内部日常用户和外部 alpha 测试者**
- 它**交付、部署、崩溃并得到修复**——所有这些都由 Harness 内的智能体完成

工程师的工作？设计 Harness。指定意图。提供反馈。不编写代码。

---

## Harness 工程的三大支柱

OpenAI 的框架将 Harness 工程组织为三个核心类别：

### 1. 上下文工程

上下文工程是关于确保智能体在正确的时间拥有正确的信息。

**静态上下文**：
- 存储库本地文档（架构规范、API 契约、风格指南）
- 编码项目特定规则的 `AGENTS.md` 或 `CLAUDE.md` 文件
- 由 linter 验证的交叉链接设计文档

**动态上下文**：
- 智能体可访问的可观测性数据（日志、指标、追踪）
- 智能体启动时的目录结构映射
- CI/CD 管道状态和测试结果

**关键规则**：从智能体的角度来看，它无法在上下文中访问的任何内容都不存在。Google Docs、Slack 线程或人们头脑中的知识对系统是不可见的。**存储库必须是唯一的真实来源。**

### 2. 架构约束

这是 Harness 工程与传统 AI 提示最显著不同的地方。与其告诉智能体"编写好的代码"，不如**机械地强制执行好代码的样子。**

**依赖分层**：
```
Types → Config → Repo → Service → Runtime → UI
```

每一层只能从其左侧的层导入。这不是建议——它由结构测试和 CI 验证强制执行。

**约束强制执行工具**：
- **确定性 linter**——自动标记违规的自定义规则
- **基于 LLM 的审计器**——审查其他智能体代码的架构合规性的智能体
- **结构测试**——像 ArchUnit，但用于 AI 生成的代码
- **预提交钩子**——任何代码提交前的自动检查

**为什么约束可以改善输出**：矛盾的是，约束解决方案空间使智能体**更有生产力**，而不是更少。当智能体可以生成任何东西时，它会浪费 token 探索死胡同。当 Harness 定义清晰的边界时，智能体会更快地收敛到正确的解决方案。

### 3. 熵管理（"垃圾收集"）

这是最被低估的组件。随着时间的推移，AI 生成的代码库会积累熵——文档与现实脱节、命名约定发散、死代码积累。

Harness 工程通过**定期清理智能体**来解决这个问题：
- **文档一致性智能体**——验证文档与当前代码匹配
- **约束违规扫描器**——找到通过早期检查的代码
- **模式强制执行智能体**——识别并修复与既定模式的偏差
- **依赖审计器**——跟踪并解决循环或不必要的依赖

这些智能体按计划运行——每天、每周或由特定事件触发——保持代码库对人类审查者和未来 AI 智能体都健康。

---

## Harness 工程实践：团队实际如何做

### OpenAI 方法：零人工代码

OpenAI 的 Harness 工程团队结构：

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

### Stripe 方法：规模化的 Minions

Stripe 的内部编码智能体，称为 **Minions**，现在每周产生**超过 1,000 个合并的拉取请求**：

1. 开发者在 Slack 中发布任务
2. Minion 编写代码
3. Minion 通过 CI
4. Minion 打开 PR
5. 人类审查并合并

第 1 步和第 5 步之间没有开发者交互。Harness 处理一切——测试执行、CI 验证、风格合规和文档更新。

### LangChain 方法：中间件优先

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

```
Agent Request
  → LocalContextMiddleware (映射代码库)
  → LoopDetectionMiddleware (防止重复)
  → ReasoningSandwichMiddleware (优化计算)
  → PreCompletionChecklistMiddleware (强制执行验证)
  → Agent Response
```

每个中间件层都添加特定功能，而不修改核心智能体逻辑。这种模块化方法使 Harness 可测试且可演进。

---

## 构建你的第一个 Harness：实用框架

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

如果你正在使用 Claude Code、Cursor 或 Codex 进行个人项目：

**需要设置什么**：
- 带有项目约定的 `CLAUDE.md` 或 `.cursorrules` 文件
- 用于 linting 和格式化的预提交钩子
- 智能体可以运行以自我验证的测试套件
- 具有一致命名的清晰目录结构

**设置时间**：1-2 小时 **影响**：防止最常见的智能体错误

### 级别 2：团队 Harness（小团队）

对于 3-10 个共享代码库的开发者团队：

**添加到级别 1**：
- 带有团队范围约定的 `AGENTS.md`
- 由 CI 强制执行的架构约束
- 常见任务的共享提示模板
- 由 linter 验证的文档即代码
- 专门针对智能体生成 PR 的代码审查检查清单

**设置时间**：1-2 天 **影响**：跨团队一致的智能体行为

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

对于运行数十个并发智能体的组织：

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

**设置时间**：1-2 周 **影响**：智能体作为自主贡献者运作

---

## 常见的 Harness 工程错误

### 1. 过度工程化控制流

> *"如果你过度工程化控制流，下一次模型更新会破坏你的系统。"*

模型改进迅速。2024 年需要复杂管道的能力现在由单个上下文窗口提示处理。构建你的 Harness 以**可剥离**——当模型变得足够智能不需要时，你应该能够删除"智能"逻辑。

### 2. 将 Harness 视为静态的

Harness 需要与模型一起演进。当新模型版本改进推理时，你的推理优化中间件可能会适得其反。每次重大模型更新时审查和更新 Harness 组件。

### 3. 忽略文档层

最有影响力的 Harness 改进通常是最简单的：**更好的文档**。如果你的 `AGENTS.md` 含糊不清，你的智能体输出也会含糊不清。投资于精确、机器可读的文档，作为智能体的基础事实。

### 4. 没有反馈循环

没有反馈的 Harness 是一个笼子，而不是指南。智能体需要知道它何时成功何时失败。内置：
- 任务完成前的自我验证步骤
- 作为智能体工作流一部分的测试执行
- 按任务类型划分的智能体成功率指标

### 5. 只有人类的文档

如果你的架构决策存在于人们的头脑中或智能体无法访问的 Confluence 页面中，Harness 就有差距。**智能体需要的一切都必须在存储库中。**

---

## Harness 工程与相关概念

| 概念 | 范围 | 焦点 |
|------|------|------|
| **提示工程** | 单次交互 | 制作有效的提示 |
| **上下文工程** | 模型上下文窗口 | 模型看到什么信息 |
| **Harness 工程** | 整个智能体系统 | 环境、约束、反馈、生命周期 |
| **智能体工程** | 智能体架构 | 内部智能体设计和路由 |
| **平台工程** | 基础设施 | 部署、扩展、运营 |

Harness 工程**包括**上下文工程并借鉴提示工程，但它在更高层次上运作——它是关于使智能体可靠的完整系统，而不仅仅是单次交互的输入。

---

## 这对软件工程师意味着什么

### 工作正在改变

Harness 工程代表了软件工程师工作的真正演变：

| 之前 | 之后 |
|------|------|
| 编写代码 | 设计 AI 编写代码的环境 |
| 调试代码 | 调试智能体行为 |
| 审查代码 | 审查智能体输出 + Harness 有效性 |
| 编写测试 | 设计测试策略 |
| 维护文档 | 构建文档作为机器可读基础设施 |

这并不意味着工程师变得不那么技术。如果说有什么不同的话，Harness 工程需要**更深**的架构思考——你正在设计必须在没有你持续干预的情况下工作的系统。

### 重要的技能

基于在 NxCode 构建 AI 驱动产品的所见：

1. **系统思维**——理解约束、反馈循环和文档如何交互
2. **架构设计**——定义可强制执行且富有成效的边界
3. **规范编写**——足够精确地表达意图，让智能体可以执行
4. **可观测性**——构建揭示智能体行为模式的监控
5. **迭代速度**——快速测试和完善 Harness 配置

### 实践经验：什么有效

使用多个智能体系统（Claude Code、Codex、Cursor）构建 AI 驱动的 Web 应用程序。产生最大差异的模式：

- **存储库优先文档**：每个架构决策、命名约定和部署过程都在 repo 中。没有任何东西存在于 Slack 或 Google Docs 中。
- **增量约束构建**：从基本 linting 开始，随着模式出现添加架构约束，不要尝试预先设计完美的 Harness。
- **智能体特定审查检查清单**：AI 生成的代码与人类代码有不同的失败模式。审查过程考虑常见的智能体模式（过度抽象、不必要的错误处理、文档漂移）。
- **多提供商 Harness 设计**：Harness 适用于 Claude、GPT 和 Gemini 模型。提供商无关设计意味着可以切换模型而无需重建整个系统。

---

## 关键要点

1. **Harness 工程是新学科**——设计使 AI 智能体可靠的系统——约束、反馈循环、文档和生命周期管理
2. **模型是商品；Harness 是护城河**——LangChain 通过只改变 Harness 从基准前 30 名跃升至前 5 名
3. **OpenAI 用零人工代码构建了 100 万+行**——证明 Harness 工程在生产规模上有效
4. **三大支柱**：上下文工程、架构约束和熵管理
5. **简单开始**：一个好的 `AGENTS.md` 和预提交钩子比复杂中间件更有影响力
6. **工程师的工作正在演变**——从编写代码到设计 AI 编写代码的环境
7. **构建可剥离的 Harness**——当模型改进时，过度工程化会破裂；保持适应性

---

## 相关研究

- [[Harness-Engineering|Harness 工程]]
- [[OpenAI-Codex-Harness-Engineering|OpenAI Codex Harness 工程]]
- [[LangChain-Harness-Engineering|LangChain Harness 工程实践]]
- [[Harness-Engineering-for-Coding-Agent-Users|面向编码智能体用户的 Harness 工程]]
- [[Harness-Engineering-First-Thoughts|Harness 工程：最初的思考]] - Martin Fowler 团队的早期备忘录