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 态度 | 推荐：简单、可组合、透明 | 谨慎：务必理解底层假设 |
Anthropic 的警告
可以先用框架快速起步，但务必理解底层代码。对底层假设的错误理解是客户错误的常见来源。
二、为什么需要 Harness？
裸 LLM 直接当 Agent 用，会出现两种典型的失败模式。
2.1 两种失败模式
失败模式一：一口吃成胖子（One-shot Everything）
Agent 尝试一次性完成所有功能，上下文耗尽后留下半成品代码。下一个会话启动时，面对的是没有文档的半成品，只能猜测之前发生了什么，花大量时间恢复基本功能。
失败模式二：过早宣布完成（Premature Victory）
后期 Agent 看到已有进展，就认为任务已经完成。实际上功能远未达到生产质量。
2.2 Context Anxiety
上下文焦虑
模型在接近感知到的上下文限制时，会开始过早收尾 -- 即使任务远未完成。
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 格式）：
{
"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
}为什么用 JSON 而不是 Markdown？
实验发现，模型更容易不当修改 Markdown 文件（改写内容、删除条目），而 JSON 格式的结构化约束让模型更倾向于只修改 passes 字段。
每次会话的启动流程：
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/ │
│ (任务锁文件) │
│ │
└──────────────────────────────────────────────┘协调机制：
- Agent 想做某个任务 → 写入
current_tasks/文件声明占用 - Git 同步 → 其他 Agent 看到锁文件 → 跳过该任务
- 完成后推送 → 删除锁文件 → 释放任务
项目数据：
| 指标 | 数值 |
|---|---|
| 并行 Agent 数 | 16 |
| 总会话数 | ~2000 |
| 总成本 | ~$20,000 |
| 产出 | 10 万行 Rust 编译器 |
| 目标 | 可在 x86/ARM/RISC-V 编译 Linux |
关键教训：
并行 Harness 的核心经验
- 写极高质量的测试：Agent 会自主解决你给的问题，验证器必须近乎完美
- 站在 Claude 的角度思考：测试是为 Claude 写的，不是为人类
- 维护 README 和进度文件：帮助新会话快速定位
- 尊重模型限制：上下文窗口有限、长文件处理困难、错误信息理解受限
五、Harness 设计原则总结
七大核心原则
- 增量进展 > 一次性完成：每次只做一个原子任务，完成后立即验证
- 结构化交接 > 依赖 Compaction：用 progress file + git history + feature list 传递状态
- 分离评估 > 自我评估：独立 Evaluator 用怀疑态度审查，不信任 Agent 自评
- 测试驱动 > 信任模型判断：强制端到端测试（如 Puppeteer 浏览器自动化）
- 干净状态 > 半成品代码：每次会话结束时，代码应处于可合并到 main 的状态
- 最小工具集 > 臃肿工具箱：工具功能不重叠，Agent 能明确知道该用哪个
- 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 |
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 -- Anthropic Engineering Blog, 2025.11
- Harness Design for Long-Running Application Development -- Anthropic Engineering Blog, 2026.03
- Building a C Compiler with a Team of Parallel Claudes -- Anthropic Engineering Blog, 2026.02
- Claude 4 Prompting Guide - Multi-Context Window Workflows -- Anthropic Docs
- Claude Agent SDK Quickstart -- GitHub