---
url: /blog/agent-harness/index.md
---
# Agent Harness 是什么

> **一句话定义**：Agent Harness 是围绕 LLM 构建的外围编排系统 -- 负责提示词管理、工具调度、状态传递、任务分解、质量约束、失败恢复和会话编排，把裸模型变成一个可靠的执行单元。
>
> **核心来源**：基于 Anthropic 工程博客的三篇文章提炼。

***

## 一、什么是 Agent Harness？

### 1.1 定义

**Harness** 原意是"缰绳/挽具" -- 驾驭马匹的装备。在 Agent 语境下，它是**围绕 LLM 构建的外围系统**，负责让裸模型变成一个能实际完成任务的可靠执行单元。

> **类比**：LLM 模型 = 汽车发动机；Agent Harness = 底盘、转向、刹车、仪表盘。发动机再强，没有底盘也跑不起来。

一个完整的 Agent 系统可以分解为三层：

```
┌─────────────────────────────────────────────┐
│               应用层（User-facing）            │
│   IDE 集成、CLI 工具、聊天界面、自动化流水线       │
├─────────────────────────────────────────────┤
│               Harness 层（编排）               │
│   Prompt 管理 · 工具调度 · 状态传递 · 质量约束    │
│   任务分解 · 失败恢复 · 会话编排                  │
├─────────────────────────────────────────────┤
│               模型层（引擎）                   │
│   Claude / GPT / Gemini / 开源模型             │
└─────────────────────────────────────────────┘
```

### 1.2 Harness vs Framework

这两个词容易混淆，但本质不同：

| 维度               | Harness         | Framework    |
| :--------------- | :-------------- | :----------- |
| **本质**           | 针对特定任务的编排方案     | 通用 Agent 开发库 |
| **粒度**           | 一次性的、高度定制化的     | 可复用的、抽象化的    |
| **类比**           | 为特定马匹定制的马鞍      | 马鞍工厂         |
| **代码量**          | 可以是纯 Prompt，零代码 | 通常有大量代码      |
| **灵活性**          | 针对特定场景高度优化      | 通用但可能不够精细    |
| **Anthropic 态度** | 推荐：简单、可组合、透明    | 谨慎：务必理解底层假设  |

> \[!warning] Anthropic 的警告
> 可以先用框架快速起步，但**务必理解底层代码**。对底层假设的错误理解是客户错误的常见来源。

***

## 二、为什么需要 Harness？

裸 LLM 直接当 Agent 用，会出现两种典型的失败模式。

### 2.1 两种失败模式

**失败模式一：一口吃成胖子（One-shot Everything）**

Agent 尝试一次性完成所有功能，上下文耗尽后留下半成品代码。下一个会话启动时，面对的是没有文档的半成品，只能猜测之前发生了什么，花大量时间恢复基本功能。

**失败模式二：过早宣布完成（Premature Victory）**

后期 Agent 看到已有进展，就认为任务已经完成。实际上功能远未达到生产质量。

### 2.2 Context Anxiety

> \[!warning] 上下文焦虑
> 模型在接近感知到的上下文限制时，会开始**过早收尾** -- 即使任务远未完成。

**Compaction（上下文压缩）** 并不能完全解决这个问题。压缩只是把旧信息摘要化，但不提供全新的起点，焦虑可能持续存在。

Anthropic 发现 **Context Reset（上下文重置）** 比 Compaction 更有效：完全清除上下文，通过结构化制品进行交接。

### 2.3 自我评估偏差

Agent 自评倾向于**过度乐观**。尤其是主观任务（如 UI 设计质量），Agent 会给自己的输出打高分，即使实际上远未达标。

**解决方案**：分离评估者 -- 调校为"怀疑态度"的独立 Evaluator，比让生成者自我批评容易得多。

***

## 三、Harness 的核心职责

一个完整的 Harness 需要管理以下七个方面：

| 职责            | 说明             | Anthropic 实例                                       |
| :------------ | :------------- | :------------------------------------------------- |
| **Prompt 管理** | 不同阶段使用不同的提示词   | Initializer Agent vs Coding Agent 用不同 prompt       |
| **工具调度**      | 提供什么工具、如何调用    | Claude Agent SDK 的工具集 + MCP 集成                     |
| **状态传递**      | 跨会话保持记忆        | `claude-progress.txt` + Git history + feature list |
| **任务分解**      | 把大任务拆成原子步骤     | Feature list（200+ JSON 功能点）                        |
| **质量约束**      | 防止 Agent 做蠢事   | "只能改 `passes` 字段"、强制端到端测试                          |
| **失败恢复**      | 出错了怎么回来        | Git revert、回滚到干净状态                                 |
| **会话编排**      | 何时开始、何时结束、何时重置 | Context Reset vs Compaction 策略选择                   |

***

## 四、Anthropic 的三种 Harness 形态

Anthropic 在三篇工程博客中展示了三种不同的 Harness 架构，适用于不同场景。

### 4.1 两阶段 Harness

**来源**：《Effective Harnesses for Long-Running Agents》

**核心思想**：同一个 Harness 结构，第一次运行用不同的 prompt 建环境，之后每次运行用编码 prompt 做增量进展。

```
┌───────────────────┐
│ Initializer Agent │  ← 第一次运行
│ - init.sh         │     建环境
│ - feature_list    │
│ - progress file   │
│ - 初始 git commit  │
└────────┬──────────┘
         │
         ▼
┌───────────────────┐     ┌───────────────────┐
│ Coding Agent #1   │ ──→ │ Coding Agent #2   │ ──→ ...
│ 做一个功能         │     │ 做下一个功能        │
│ git commit        │     │ git commit        │
│ 更新 progress     │     │ 更新 progress     │
└───────────────────┘     └───────────────────┘
```

**关键制品**：

| 制品 | 用途 | 格式 |
|:---|:---|:---|
| `init.sh` | 启动开发服务器、运行基础测试 | Shell 脚本 |
| `claude-progress.txt` | Agent 工作日志，记录每次会话做了什么 | 纯文本 |
| `feature_list.json` | 200+ 功能点清单，每个标记 `passes: true/false` | JSON |
| Git history | 代码变更历史，每次 commit 消息描述做了什么 | Git |

**Feature List 示例**（JSON 格式）：

```json
{
  "category": "functional",
  "description": "New chat button creates a fresh conversation",
  "steps": [
    "Navigate to main interface",
    "Click the 'New Chat' button",
    "Verify a new conversation is created",
    "Check that chat area shows welcome state",
    "Verify conversation appears in sidebar"
  ],
  "passes": false
}
```

> \[!tip] 为什么用 JSON 而不是 Markdown？
> 实验发现，模型更容易不当修改 Markdown 文件（改写内容、删除条目），而 JSON 格式的结构化约束让模型更倾向于只修改 `passes` 字段。

**每次会话的启动流程**：

```bash
pwd                    # 1. 确认工作目录
cat claude-progress.txt # 2. 阅读进度文件
cat feature_list.json   # 3. 查看功能清单
git log --oneline -20   # 4. 查看最近 commit
./init.sh               # 5. 启动开发服务器
# 测试基础功能是否正常    # 6. 确认没有被上一个 Agent 弄坏
# 选择一个未完成的功能开始工作 # 7. 增量进展
```

### 4.2 三 Agent GAN 架构

**来源**：《Harness Design for Long-Running Application Development》

**核心思想**：受 GAN（生成对抗网络）启发，将生成与评估分离。Planner 制定计划，Generator 实现代码，**独立的 Evaluator 用怀疑态度评估**。

```
┌──────────┐      ┌──────────┐      ┌──────────┐
│ Planner  │ ───→ │ Generator│ ───→ │Evaluator │
│  规划器   │      │  生成器   │      │  评估器   │
└──────────┘      └──────────┘      └────┬─────┘
                       ▲                   │
                       └──── 反馈循环 ───────┘
```

**Sprint Contract（冲刺契约）**：

每个冲刺周期，Generator 和 Evaluator 之间有明确的契约：

| 角色 | 输入 | 输出 | 约束 |
|:---|:---|:---|:---|
| **Planner** | 用户需求 | 分步实现计划 | 不写代码，只做规划 |
| **Generator** | 计划 + 评估反馈 | 代码实现 | 必须实现评估器指出的所有问题 |
| **Evaluator** | 代码 + 设计稿 | 评分 + 改进建议 | 必须用怀疑态度，不能自评 |

**前端设计评估四大标准**：

| 标准 | 权重 | 说明 |
|:---|:---|:---|
| **设计质量** | 最高 | 整体一致性、情绪和身份感 |
| **原创性** | 高 | 是否有定制决策，还是模板/AI 默认模式 |
| **工艺** | 中 | 排版层次、间距一致性、色彩和谐 |
| **功能性** | 基础 | 用户能否理解和使用界面 |

> Claude 默认在前两项（设计质量、原创性）较弱，在后两项（工艺、功能性）较强。分离评估器让弱点暴露得更清楚。

**效果**：5-15 轮迭代后显著提升，第 10 轮偶尔出现创造性飞跃（如 3D 空间博物馆）。

### 4.3 并行 Harness

**来源**：《Building a C Compiler with Parallel Claudes》

**核心思想**：无编排者，多个 Agent 在独立容器中并行工作，通过 Git 共享代码库和任务锁文件协调。

```
┌──────────────────────────────────────────────┐
│              Git 共享代码库                     │
├──────────────────────────────────────────────┤
│                                              │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐       │
│  │Claude #1│ │Claude #2│ │Claude #3│ ...    │
│  │ Docker  │ │ Docker  │ │ Docker  │       │
│  └────┬────┘ └────┬────┘ └────┬────┘       │
│       │           │           │             │
│       └───────────┼───────────┘             │
│                   │                         │
│          current_tasks/                     │
│          (任务锁文件)                          │
│                                              │
└──────────────────────────────────────────────┘
```

**协调机制**：

1. Agent 想做某个任务 → 写入 `current_tasks/` 文件声明占用
2. Git 同步 → 其他 Agent 看到锁文件 → 跳过该任务
3. 完成后推送 → 删除锁文件 → 释放任务

**项目数据**：

| 指标 | 数值 |
|:---|:---|
| 并行 Agent 数 | 16 |
| 总会话数 | ~2000 |
| 总成本 | ~$20,000 |
| 产出 | 10 万行 Rust 编译器 |
| 目标 | 可在 x86/ARM/RISC-V 编译 Linux |

**关键教训**：

> \[!tip] 并行 Harness 的核心经验
>
> 1. **写极高质量的测试**：Agent 会自主解决你给的问题，验证器必须近乎完美
> 2. **站在 Claude 的角度思考**：测试是为 Claude 写的，不是为人类
> 3. **维护 README 和进度文件**：帮助新会话快速定位
> 4. **尊重模型限制**：上下文窗口有限、长文件处理困难、错误信息理解受限

***

## 五、Harness 设计原则总结

> \[!tip] 七大核心原则
>
> 1. **增量进展 > 一次性完成**：每次只做一个原子任务，完成后立即验证
> 2. **结构化交接 > 依赖 Compaction**：用 progress file + git history + feature list 传递状态
> 3. **分离评估 > 自我评估**：独立 Evaluator 用怀疑态度审查，不信任 Agent 自评
> 4. **测试驱动 > 信任模型判断**：强制端到端测试（如 Puppeteer 浏览器自动化）
> 5. **干净状态 > 半成品代码**：每次会话结束时，代码应处于可合并到 main 的状态
> 6. **最小工具集 > 臃肿工具箱**：工具功能不重叠，Agent 能明确知道该用哪个
> 7. **Context Reset > Context Anxiety**：完全重置上下文 + 结构化制品，比压缩更有效

***

## 六、Agent 失败模式与解决方案对照表

以下表格总结了 Anthropic 在两阶段 Harness 中发现的四种常见失败模式及对应解决方案：

| 问题 | Initializer Agent 行为 | Coding Agent 行为 |
|:---|:---|:---|
| **过早宣布完成**：Agent 看到已有进展就认为项目完成 | 建立结构化 Feature List（JSON），列出所有功能点，初始状态为 `passes: false` | 每次会话开始时读取 Feature List，选择一个未完成的功能开始工作 |
| **环境状态混乱**：代码有 bug、进展未记录 | 创建 Git 仓库 + `claude-progress.txt` 进度文件 | 会话开始时读进度和 git log，结束时写 commit 和进度更新 |
| **功能标记过早**：Agent 不测试就标记完成 | 建立 Feature List | 用浏览器自动化工具（Puppeteer）做端到端测试，确认后才能改 `passes` |
| **启动浪费时间**：Agent 不知道怎么运行项目 | 编写 `init.sh` 脚本 | 每次会话开始时先读 `init.sh`，启动开发服务器 |

***

## 七、实战参考

### 7.1 开源代码

Anthropic 提供了完整的快速入门代码：

| 资源 | 链接 |
|:---|:---|
| 自主编码快速入门 | [github.com/anthropics/claude-quickstarts/autonomous-coding](https://github.com/anthropics/claude-quickstarts/tree/main/autonomous-coding) |

### 7.2 Prompt 指南

Claude 4 提示词指南中包含了多上下文窗口工作流（Multi-Context Window Workflows）的最佳实践，涵盖 Harness 结构和"不同 prompt 给不同上下文窗口"的建议。

### 7.3 可操作建议

如果你想为自己的 Agent 项目设计 Harness，建议按以下优先级推进：

```
Phase 1（最小可用）
├── 进度文件（progress.txt / progress.md）
├── Git commit 规范
└── Feature List（JSON 格式）

Phase 2（质量保障）
├── 分离的 Evaluator（独立 prompt 或独立模型）
├── 启动脚本（init.sh）
└── 端到端测试工具

Phase 3（高级优化）
├── 多 Agent 并行（Git + 任务锁）
├── Sprint Contract（冲刺契约）
└── Context Reset 策略
```

***

## 八、总结

```
┌─────────────────────────────────────────────────────────┐
│                   Agent Harness 核心要点                  │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  1. 本质：围绕 LLM 的编排系统，把裸模型变成可靠执行单元      │
│                                                         │
│  2. 核心问题：跨上下文窗口的状态传递 + Agent 的过度乐观     │
│                                                         │
│  3. 三种形态：                                            │
│     - 两阶段（Initializer + Coding Agent）               │
│     - 三 Agent GAN（Planner + Generator + Evaluator）    │
│     - 并行（多容器 + Git + 任务锁）                       │
│                                                         │
│  4. 关键制品：progress file + git history + feature list  │
│                                                         │
│  5. 核心原则：增量、结构化交接、分离评估、测试驱动          │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

***

## 参考资料

* [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) -- Anthropic Engineering Blog, 2025.11
* [Harness Design for Long-Running Application Development](https://www.anthropic.com/engineering/harness-design-for-long-running-application-development) -- Anthropic Engineering Blog, 2026.03
* [Building a C Compiler with a Team of Parallel Claudes](https://www.anthropic.com/engineering/building-a-c-compiler-with-a-team-of-parallel-claudes) -- Anthropic Engineering Blog, 2026.02
* [Claude 4 Prompting Guide - Multi-Context Window Workflows](https://docs.claude.com/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices#multi-context-window-workflows) -- Anthropic Docs
* [Claude Agent SDK Quickstart](https://github.com/anthropics/claude-quickstarts/tree/main/autonomous-coding) -- GitHub