Harness Engineering 学习指南

四篇文献 · 三个来源 · 一个结论：模型是引擎，Harness 是车——最好的引擎没有方向盘和刹车也没用。

引言：什么是 Harness Engineering？

我一直密切关注 Harness Design 工程领域，但总是遇到同样的问题：文章散落在各个平台，每篇只讲一个团队的实践，缺乏横向对比；而且很多概念（context reset、progressive disclosure、backpressure）在不同文章里用不同的词描述着相同的东西，初学者很难把它们联系起来。直到我把 Anthropic 的两篇、OpenAI 的一篇和 Huntley 的一篇放在一起阅读，才发现——这四篇文章讲的本质上是同一套方法论，只是各自的实现路径不同。

于是就有了这篇学习指南。我把四篇文章的核心内容做了系统梳理，提炼出它们共同认可的六大工程原则，附上各方的具体做法对比，希望帮你建立对 Harness Engineering 的完整认知，而不是只看到某一个团队的局部经验。

从 AI 工程的演进来看，Harness Engineering 是第三代方法论：

Harness（直译”线束/工装”）指的是围绕 LLM 构建的完整运行环境——包括上下文组装、工具编排、状态管理、验证反馈和生命周期控制。它决定了 agent 能否从”演示级”跨越到”生产级”。

2026 年初，四篇来自不同阵营的文章几乎同时触及了相同的工程本质。本文将从这四篇文献中提炼出六大共识主题，逐一展开。

四篇文献概览

共识一：Context 管理——上下文是稀缺资源

核心洞察：agent 的上下文窗口不是”越多越好”，而是需要精心管理的有限资源。

Anthropic 的发现：Context Anxiety

Anthropic 在长期运行 agent 的实验中发现了一个关键问题——context anxiety（上下文焦虑）。当对话历史不断积累、上下文窗口逐渐填满时，Claude 会表现出明显的行为退化：

• 过早收尾：agent 感知到上下文即将耗尽，开始急于”完成”任务，跳过必要步骤
• 信息丢失：早期的重要决策和约束被后续大量信息淹没
• 一致性下降：agent 在不同上下文位置对同一问题给出矛盾回答

Anthropic 的解决方案是彻底的 context reset——而非试图”压缩”或”摘要”对话历史。完全清空上下文窗口，通过结构化的交接文件重新注入必要信息，效果远好于试图保留”精华”。

“与其让 agent 在一个日益浑浊的池塘里挣扎，不如给它一个干净的新池塘和一份精确的地图。“

OpenAI 的方案：模块化文档，拒绝大而全

OpenAI 在 Codex 的实践中提出了一个鲜明的立场：AGENTS.md 应该是目录，不是百科全书。

传统做法是把所有指令堆进一个巨大的配置文件。OpenAI 发现这会导致 agent 在信息过载中遗漏关键约束。他们推荐的结构：

AGENTS.md          ← 50-100 行的目录索引
docs/
├── architecture/  ← 架构决策、模块边界
├── conventions/   ← 编码、测试、日志标准
├── design/        ← 功能设计文档
├── plans/         ← 冲刺计划、任务列表
└── reference/     ← API 规格、错误码

这被称为渐进式披露（Progressive Disclosure）——agent 在需要时获取适当粒度的信息，而非一次性接收所有内容。这模拟了人类的入职流程：先看总览，再按需深入。

Huntley 的极简主义：每次只分配一个任务的 token

Geoffrey Huntley 的 Ralph 模式将这一原则推到极致。在约 170k token 的上下文窗口中，他的策略是：

• 每个循环只做一件事——规格说明和计划在每次循环开始时注入，用完即丢
• 昂贵操作交给子 agent——搜索可以并发数百个子 agent，但构建/测试限制为单个 agent
• 主上下文只保留当前任务——历史不重要，当前状态才重要

共识提炼

三方不约而同地拒绝了”把所有东西塞进上下文”的朴素策略。区别在于手段：

底层共识：上下文窗口是 agent 的工作记忆。像管理团队的注意力一样管理它——聚焦、清晰、不超载。

共识二：结构化交接——外部化状态即记忆替代

核心洞察：agent 没有记忆，但文件系统有。把状态写入磁盘，就创造了跨 session 的”记忆”。

为什么需要交接？

长时间运行的 agent 任务不可能在一个 session 中完成。每次新 session 启动时，agent 对之前的工作一无所知——这就是 Anthropic 所说的**“换班问题”（shift change problem）**。

如果不解决交接，每个新 session 都在”从零开始”，甚至可能覆盖之前的进度。

Anthropic 的双 agent 架构

Anthropic 在 Effective Harnesses 中设计了一个精巧的初始化-编码分离架构：

Initializer Agent（初始化 agent）：只运行一次，创建整个项目的基础设施——

• init.sh：环境搭建脚本
• claude-progress.txt：工作进度文档
• feature_list.json：200+ 个细粒度功能项，全部标记为 “failing”
• 初始 git commit 建立基线状态

Coding Agent（编码 agent）：在后续 session 中反复运行，每次启动时执行固定协议——

1. 验证工作目录
2. 读取 git log 和进度文档
3. 选择最高优先级的未完成功能
4. 运行基础功能测试
5. 开始实现

关键设计：feature_list.json 中的 200+ 项功能清单不是计划文档，而是防止过早宣告完成的安全网。agent 的一个常见失败模式是”虚假胜利宣言”——在只完成了表面功能后就声称任务完成。细粒度的清单迫使 agent 逐项推进。

“不接受删除或编辑测试的行为，因为这可能导致功能缺失或 bug。“

OpenAI 的 Repo-as-Knowledge-Base

OpenAI 将这一理念提升为原则：仓库即知识库（Repo-Native Knowledge）——agent 看不到 Slack、Google Docs、Wiki 等任何仓库外部的信息。因此，所有决策、计划、规格都必须以 markdown 形式存在于仓库中。

配合这一原则，OpenAI 引入了文档园丁（Doc-Gardener）agent——定期扫描文档与代码的一致性，修复漂移。这解决了”写了文档但没人维护”的经典工程问题。

Huntley 的 TODO.md 模式

Huntley 的方案最为极简：一个 TODO.md 文件就是全部状态。

Ralph 循环：
while true; do
  cat PROMPT.md | claude-code
done

每次循环，Ralph 读取 TODO.md，取最重要的一项执行，更新进度，提交代码。如果 session 中断，下一次循环自然从 TODO.md 的当前状态继续。

Huntley 的洞察是：状态载体需要的是可重建性，而非完整性。 只要 TODO.md + 代码库 + git log 存在，任何 session 都能重建完整上下文。

共识提炼

底层共识：agent 的记忆不在模型里，在文件系统里。设计好外部化状态的格式和协议，agent 就获得了超越单个 session 的”持久记忆”。

共识三：反馈回路——让 agent 验证自己

核心洞察：没有反馈回路的 agent 是在黑暗中射击。自动化验证是 harness 的核心基础设施。

为什么 agent 不能信任自己的判断？

Anthropic 在实验中发现了一个令人不安的现象：agent 对自己工作的评估严重膨胀。 Claude 在被要求评价自己的输出时，倾向于给出过高评分，忽略实际存在的问题。这不是”说谎”——而是生成模型在架构层面缺乏自我批判的能力。

这意味着：不能让写代码的 agent 自己判断代码是否正确。验证必须来自外部。

Anthropic 的 Playwright 实时测试

Anthropic 在 Harness Design 中的 Evaluator agent 使用 Playwright MCP 与正在运行的应用进行交互——不是读代码，而是像真实用户一样点击、导航、验证。

在 Effective Harnesses 中，他们同样发现浏览器自动化是突破性的改进。在引入 Puppeteer MCP 之前，agent 只运行单元测试，很多端到端的问题被忽略。引入后，agent 能以”真实用户体验”验证功能，bug 发现率大幅提升。

OpenAI 的 CI + Linter 自动约束

OpenAI 的做法更加系统化。他们将 CI/CD 重新定义为agent 的自动质量保证系统，采用双层机制：

第一层：确定性 linter

• 错误信息专门为 agent 可读性重新格式化
• 包含修复建议，agent 可以直接执行
• 强制执行六层依赖层级：Types → Config → Repo → Service → Runtime → UI

第二层：LLM 审计 agent

• 检测形式规则无法捕捉的语义/设计违规
• 作为 PR 提交前的最后一道防线

OpenAI 还提出了一个反直觉的合并哲学：等待成本超过修正成本。 更短的 PR 生命周期、更少的阻塞条件、快速回滚优于预防。

Huntley 的 Build/Test 反压

Huntley 的反馈回路最为直接：构建失败和测试失败就是 backpressure 信号。

Ralph 执行一项 TODO
  → 运行 build
    → 失败 → Ralph 修复 → 重试
    → 成功 → 运行 tests
      → 失败 → Ralph 修复 → 重试
      → 全部通过 → 提交，取下一项 TODO

关键不是测试本身，而是测试文档化了”为什么”。Huntley 强调：测试的注释应该解释这个测试存在的原因，这样未来的循环才能理解约束的意图而非仅仅满足约束的形式。

共识提炼

底层共识：反馈回路是 harness 的心跳。没有自动验证，agent 就是在”自说自话”。验证必须是外部的、自动的、快速的。

共识四：任务分解——每次只做一件事

核心洞察：agent 在大任务上的失败率远高于小任务。分解是最有效的成功策略。

为什么 agent 不能”一次搞定”？

即使是最强的模型，在面对”实现一个完整的用户认证系统”这样的任务时也会失败。不是因为模型不懂如何实现——而是因为：

1. 上下文污染：实现过程中积累的中间状态干扰后续决策
2. 错误放大：早期的小错误在后续步骤中被不断放大
3. 注意力漂移：agent 在长任务中逐渐偏离原始目标

Anthropic 的 Feature-by-Feature

Anthropic 的策略是一次实现一个功能（feature-by-feature）。在 Effective Harnesses 中，初始化 agent 创建的 feature_list.json 包含 200+ 个细粒度条目，编码 agent 在每个 session 中只处理一个。

这不是简单的”拆分任务”——而是重新定义了”完成”的粒度。一个 session 的成功标准不是”完成项目”，而是”让一个具体功能从 failing 变为 passing”。

OpenAI 的 Depth-First 分解

OpenAI 提出了更系统的分解方法论——depth-first 分解：

以”实现用户认证”为例：

1. 设计先行：产出领域模型、API 规格、数据库迁移计划
2. 模块实现：按顺序实现后端 API → 前端页面 → 测试用例 → 文档
3. 集成验证：模块集成 + 端到端测试

关键原则：

• 任务原子化：每个子任务有明确的输入、输出和验收标准
• 能力解锁：先构建基础模块（如 auth service），后续复杂功能依赖于此
• 失败反思：任务失败时，分析缺失的能力（工具、文档），而非简单重试

OpenAI 的 Codex 使用这种方法实现了单次 7+ 小时的执行，从一份详细的 markdown 执行计划出发，逐层推进。

Huntley 的单项 TODO

Huntley 把分解简化到了极致：Ralph 每次只取 TODO 中最重要的一项。

他甚至不预先规划完整的任务列表——而是让模型根据当前代码状态和规格说明动态生成优先级列表（fix_plan.md），然后只取第一项执行。

Huntley 反复丢弃和重新生成这些列表，因为随着代码的变化，优先级也在变化。计划的价值不在于被执行，而在于聚焦当下最重要的事。

共识提炼

底层共识：agent 的可靠性与任务的粒度成反比。把大任务分解成小任务，不是效率问题，而是可靠性问题。

共识五：生成与评估分离——不信任 agent 的自我评估

核心洞察：写代码的 agent 不应该评判自己的代码。生成和评估必须由不同的”大脑”完成。

Anthropic 的 GAN 式架构

这是 Anthropic Harness Design 中最核心的架构创新。灵感来自生成对抗网络（GAN），他们构建了三个独立 agent：

• Planner（规划者）：将简短提示扩展为完整规格，识别 AI 功能机会
• Generator（生成者）：迭代实现，在提交 QA 前进行自评
• Evaluator（评估者）：使用 Playwright MCP 交互式验证，对照”冲刺合同”逐项检查

关键发现：

“调优一个独立的评估者使其保持怀疑态度，比让生成者对自己的工作保持批判性要容易得多。”

评估不是”看看代码像不像对的”——而是把主观判断转化为具体的、可评分的维度：设计质量、原创性、工艺水准、功能完整性。这些维度成为 agent 的”评分标准（rubric）“，大幅减少了”AI 味”的输出。

OpenAI 的 CI/Lint 独立验证

OpenAI 的分离更加工程化：

• Codex 写代码——这是生成侧
• CI/Linter 验证——这是评估侧，完全确定性，不依赖 LLM 判断
• LLM Audit Agent——语义层面的评估，捕捉 linter 无法检测的设计违规

三层分离确保了评估的独立性和全面性。特别值得注意的是 linter 错误信息的设计——它们被重新格式化为 agent 可读的修复建议，形成了”失败 → 理解 → 修复”的闭环。

Huntley 的 LLM-as-Judge

Huntley 在处理主观质量评估时引入了 LLM-as-Judge 模式——用一个独立的 LLM 调用来评价 Ralph 的输出质量。

这解决了一个传统自动化测试无法覆盖的问题：代码可能通过所有测试但质量很差。 比如 UI 功能正确但布局丑陋，API 响应正确但数据结构不合理。LLM-as-Judge 提供了”第二双眼睛”，且这双眼睛没有生成者的 bias。

共识提炼

底层共识：这本质上是软件工程中”关注点分离”原则在 agent 系统中的应用。写代码和判断代码好坏是两种完全不同的认知任务，交给不同的系统处理效果更好。

共识六：Harness 随模型进化——复杂度应随能力减少

核心洞察：好的 harness 设计不是一劳永逸的——它应该随着模型能力的提升而逐步简化。

Anthropic 的实证：删除 Context Reset

Anthropic 在 Harness Design 中提供了最直接的证据。当模型从 Sonnet 4.5 升级到 Opus 4.6 后，他们发现之前至关重要的 context reset 机制可以被移除了：

“Opus 4.6 增强的规划和调试能力允许消除 Opus 4.5 所需的 sprint 构造。”

这不是偶然——他们采用了系统化的方法：每次移除一个组件，测试系统是否仍然正常工作。 如果是，说明该组件已经被模型自身的能力”吸收”了。

OpenAI 的渐进简化论

OpenAI 将这一观察上升为哲学原则，描述了四个层面的简化：

1. 模型自主推理：早期需要精心设计的 Chain-of-Thought 提示链，现在模型自己就能规划和反思
2. 原生工具调用：以前需要复杂的函数调度和参数解析逻辑，现在模型原生理解工具定义
3. 更好的上下文利用：以前需要精密的 RAG、分块和压缩策略，现在更长的上下文和更强的理解力允许更直接的信息提供
4. 模型-Harness 协同进化：OpenAI 为 Codex 的 harness 环境专门训练模型，模型原生理解 shell 操作和”compaction”机制，支持 24+ 小时的连续运行

轨迹：更多的脚手架变得不必要。工程重心从补偿模型弱点转向设计高层约束和反馈系统。

Huntley 的持续调音

Huntley 的方法论更加有机：观察失败，针对性修复。

他不是在理论层面设计 harness，而是在实践中迭代：

• Ralph 生成了错误的代码模式？→ 更新 standards 文档，而非修改 prompt
• 某个测试反复失败？→ 分析是测试问题还是 agent 能力问题
• 循环效率下降？→ 检查是否有不再需要的约束可以移除

Huntley 坦承：Ralph 必然会产生缺陷。 关键不是追求零缺陷，而是建立一个持续修正的机制。每次迭代都让 harness 更加贴合当前模型的能力边界。

共识提炼

底层共识：Harness 不是静态产物，而是活的系统。随着模型进化，harness 应该变得更轻、更聚焦——从”代替模型思考”转向”为模型设定边界”。

工程师角色的转变

四篇文章最终都指向同一个结论——软件工程师的角色正在发生根本性转变：

┌─────────────────────┐          ┌─────────────────────┐
│                     │          │                     │
│   过去：写代码       │   ───→   │   现在：设计环境     │
│   直接实现功能       │          │   构建让 agent 能    │
│                     │          │   可靠工作的系统      │
└─────────────────────┘          └─────────────────────┘

OpenAI 明确使用了控制论（Control Theory） 的框架来描述这一转变：工程师的日常工作变成了——

• 设计环境：搭建仓库结构、架构约束、CI/CD 管线、文档体系
• 澄清意图：将高层目标分解为 agent 可执行的任务
• 构建反馈回路：建立自动测试和监控，快速捕获 agent 错误
• 在杠杆点介入：审批 PR、做高风险决策、设定架构方向

这不是”被 AI 取代”——而是从”直接操作”升级为”系统设计”。用 Huntley 的话说：

“人类工程师仍然是不可或缺的——他们引导 Ralph 的方向。“

独特贡献：每篇文章的差异化洞察

在六大共识之外，每篇文章也有独到之处：

Anthropic Effective Harnesses：200+ Feature List 防御术

细粒度功能清单不仅是任务管理工具，更是防止 agent 虚假完成的安全机制。agent 最常见的失败模式之一就是过早宣告胜利。

Anthropic Harness Design：评分维度量化主观判断

将”设计质量”这样的主观概念拆解为具体的可评分维度（设计质量、原创性、工艺水准、功能完整性），用结构化的 rubric 替代模糊的”做得好不好”。

OpenAI：熵管理与文档园丁

OpenAI 独特地提出了熵管理（Entropy Management） 概念——agent 生成的代码库会随时间退化。架构漂移、知识衰变需要专门的清理 agent 来对抗。这是其他文章未触及的运维视角。

Huntley：成本颠覆与维护观重塑

$50k 合同用 $297 完成——这不仅是效率提升，而是对软件工程经济学的根本挑战。同时，Huntley 重新定义了”可维护性”：在 AI 时代，代码的主要维护者不再是人类，而是下一轮 AI 循环。

总结：六大共识速查表

最终共识：Harness 决定上限。 模型能力在快速提升，但没有精心设计的运行环境，再强的模型也只是一个在黑暗中高速运转的引擎。Harness Engineering 是 2026 年 AI 工程师的核心技能。

参考文献

1. Anthropic. Effective Harnesses for Long-Running Agents
2. Anthropic. Harness Design for Long-Running Application Development
3. OpenAI. Harness Engineering: Leveraging Codex in an Agent-First World
4. Geoffrey Huntley. Ralph Wiggum: Software Engineer