# Harness Engineering 为什么AI犯错时该追问系统 日期: 2026-06-26T07:39:00Z 摘要: 当AI编码Agent反复犯错时，问题往往不在模型本身，而在它周围的系统。本文梳理Harness Engineering的核心框架、实践数据和跨语言社区的落地经验。 关键词: - Harness Engineering - AI Agent - 编码Agent - 前馈反馈 - 质量保证 - 智能体工程 - Martin Fowler - OpenAI - Anthropic --- ## 一个反直觉的结论 LangChain 做了一个实验。固定模型不变，只改它周围的基础设施，Terminal Bench 2.0 的分数从 52.8 跳到 66.5。没换模型，没换 prompt 技巧，没加 few-shot。 这组数字指向一个反直觉的结论：AI 编码 Agent 的质量瓶颈，往往不在模型本身，而在模型周围的系统。 2026 年 2 月，OpenAI 发了一篇文章叫 [Harness Engineering](https://openai.com/index/harness-engineering/)，描述了一个团队用 Codex 写了一百万行代码、没有一行是人手写的实验。同年 4 月，[Martin Fowler](https://martinfowler.com/articles/harness-engineering.html) 写了系统性分析。[Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) 连发三篇长时运行 Agent 的工程报告。CMU 和 Amazon 的[综述论文](https://openreview.net/pdf/f358711a95aaaf61fdeffd4ef3fc60fba9b8da57.pdf)梳理了 170 多个开源项目。一个新术语在三个月内从零散讨论结晶为工程学科。 Harness，本意是马具。缰绳、鞍具、辔头，把一匹有力但方向感不强的马引到正确方向。AI 是马，Harness 是你为它搭建的整套控制系统。 ## 三层演进 Harness Engineering 不是凭空出现的。它是 AI 工程方法论三阶段演进的最新一层。 第一阶段是 Prompt Engineering，控制对象是指令措辞。失败模式是指令不清晰，时间边界是单轮对话。第二阶段是 Context Engineering，Andrej Karpathy 在 2025 年底将它理论化，控制对象是 Token 的选择、排序和压缩。失败模式是上下文中信息错误或遗漏，时间边界是一个上下文窗口。第三阶段是 Harness Engineering，控制对象是工具编排、状态持久化、验证循环和错误恢复。失败模式是无限循环、多会话漂移和不安全操作，时间边界是完整任务生命周期。 三层是嵌套关系。Phil Schmid 的比喻最直接：模型是 CPU，Harness 是操作系统。CPU 再强，OS 拉胯也白搭。mtrajan 的区分更干脆：Context Engineering 管「给 Agent 看什么」，Harness Engineering 管「系统怎么防崩、怎么量化、怎么修」。 ## 前馈与反馈 Martin Fowler 的框架是目前最清晰的分析工具。他把 Harness 分成两层：Guides 和 Sensors。 Guides 是前馈控制，在 Agent 行动前引导它。包括 AGENTS.md、Skills、设计文档、LSP、codemod。目标是提高第一次尝试就正确的概率。Sensors 是反馈控制，在 Agent 行动后观察和纠正。包括测试、结构检查、自定义 linter、review agent。目标是让 Agent 自我修正。 两个都有才是完整的 Harness。只有 feedback，Agent 会重复犯同样的错，因为没有机制在行动前预防。只有 feedforward，Agent 永远不知道规则有没有生效，因为没有机制在行动后验证。 这两个维度再叠加执行类型，形成四象限。Computational guides 是确定性工具，比如 LSP 和 codemod。Inferential guides 是需要推理的内容，比如 AGENTS.md 和设计文档。Computational sensors 是确定性检查，比如测试和静态分析。Inferential sensors 是需要判断的验证，比如 review Agent 和 AI judge。 Fowler 还提出三个调节维度。Maintainability harness 关注代码风格和复杂度限制，最容易实现，行业已有大量成熟工具。Architecture fitness harness 确保模块边界和依赖方向正确。Behaviour harness 验证功能行为符合预期，这是当前最难的领域，仍未完全解决。 他的核心洞察是：好的 Harness 不是要消除人类介入，而是把人类的注意力导向最关键的地方。 ## 为什么 Harness 的设计质量差异这么大 最近有人提出一个观点：research 和 engineering 不是两种技能，是同一种能力的两种表达。在 frontier AI lab 的语境下，这种能力是在不确定环境中构建有用抽象的能力。 教育体系训练人在已有答案的环境中工作。教材知道答案，教授知道答案，面试官通常也知道答案。frontier lab 的工作环境完全不同。没有人知道哪些架构决策五年后会被认为是显然的，没有人知道哪些瓶颈是根本性的，没有人知道哪些能力是缺失的。 Research 的产出不是论文，是「在缺乏确定性时依然能推进」的能力。Engineering 的核心同样不是编码速度，而是在复杂系统中构建压缩模型的能力。现代 AI 基础设施更像一座城市而非一台机器。新城区不断建设，旧道路因为依赖关系而保留，不同的人理解不同的街区。没有人拥有完整的地图。理解是分布式的，挑战不再是学习每个细节，而是构建有用的抽象。 这解释了为什么同样是搭建 harness，有人只加了几条 linter 规则就让 Agent 稳定运行，有人写了大量检查却收效甚微。前者是在不完整信息中快速找到杠杆点的人，后者是在所有可能性面前停不下来的人。Herbert Simon 的 bounded rationality 说得很精确：专家的能力不是考虑所有可能性，而是丢掉大部分可能性的同时保留重要的那些。 Harness 本身就是一种抽象。它把「Agent 可能犯的所有错误」压缩为「几条不变量和检查规则」，用有限的约束覆盖无限的失败模式。好的 harness 设计者本质上是在做研究者做的事：在不确定性中识别出值得投入的方向，然后用最少的结构约束住最多的风险。 ## OpenAI 的实践 OpenAI 的百万行实验提供了最具体的一手证据。Ryan Lopopolo 在文章中写道：工程师的工作从写代码变成了设计环境、指定意图、构建反馈循环。 他们做了几个关键设计决策。 第一，强制不变量而非微管理实现。每个业务域分为固定层级，依赖方向严格验证。代码只能在层级内「向前」依赖，跨域通过单一接口接入。这种约束通过自定义 linter 和结构测试机械执行。 第二，linter 的错误信息直接注入修复指令给 Agent。这被称为「正向 prompt injection」，让确定性检查的输出对 LLM 友好。 第三，仓库知识是系统真相源。执行计划、技术债务、质量评分都是仓库一等公民。Slack 讨论中达成的架构共识，如果没写进仓库，对 Agent 来说就跟对三个月后入职的新员工一样不可见。 第四，选择「无聊」技术。可组合性好、API 稳定、训练集覆盖度高的技术，Agent 更容易建模。他们甚至自己实现了 map-with-concurrency 工具，因为通用的 p-limit 风格包无法与他们的 OpenTelemetry 基础设施深度集成。 第五，定期垃圾回收。编码「黄金原则」到仓库，建立定期清理流程，让 Agent 扫描漂移并建议修复。 这些约束不是限制，而是速度的前提。正如 Fowler 所言：「通过强制不变量而非微管理实现，让 Agent 快速交付而不破坏基础。」 ## Anthropic 的长时运行方案 Anthropic 面对的问题不同。他们要让 Agent 跨多个上下文窗口连续工作数天。 他们发现了两个关键失败模式。第一个是 context anxiety：模型感知到上下文窗口即将耗尽时，会主动提前收尾，静默输出不完整结果。不产生任何错误信号，极难发现。第二个是一次性做太多：Agent 倾向于 one-shot 整个项目，导致上下文耗尽时功能半成品，下一个 session 要从猜测上一个 Agent 做了什么开始。 解决方案是三 Agent 架构。Planner 分解产品规格为功能列表。Generator 每次只做一个功能，sprint 模式推进。Evaluator 用 Playwright 实际操作应用验证行为。 Generator 和 Evaluator 在每个 sprint 前协商「完成合同」，定义具体实现细节和可测试行为。通过文件通信，一个写一个读，不用共享上下文。这避免了多 Agent 协作中的上下文污染问题。 Context reset 比 compaction 更有效。完全清空上下文窗口启动新 Agent，配合结构化交接文件。Anthropic 发现 Sonnet 4.5 的 context anxiety 强到 compaction 不够用，必须做 context reset。后来 Opus 4.5 大幅缓解了这个问题，才得以取消 reset。 ## 中文社区的落地 中文社区的讨论集中在工程化落地。 腾讯云开发者社区的一篇[万字长文](https://cloud.tencent.com/developer/article/2658287)把 Harness 拆成九个组件：设计规格文档、Rule、Skill、Sub Agent、Workflow、Scripts、dev-map、任务看板、MCP。核心观点是 Harness Engineering 不是让 AI 更聪明，而是把 AI 从临场发挥的模型变成可约束、可协作、可校验的执行系统。 综合多个独立信息源的交叉对比，梳理出六大共识和三个空白区。共识包括基础设施是瓶颈、文档要活、思考与执行分离、上下文不是越多越好、约束必须自动化、工程师角色在转变。空白区是棕地项目改造、功能验证体系、AI 代码长期可维护性。 [iDao 的实操文章](https://www.idao.fun/blog/2026-05-16-harness-engineering-deep-coding-tutorial)最直接，给出了五阶段增量搭建路径：AGENTS.md → docs/ → Linter+CI → Verify Loop → GC。其中三层验证机制值得记录：verify.py 跑 lint + type + arch + tests，失败后最多修复三次，三次仍失败就升级给人类。这个「三次规则」来自真实教训，一个 Agent 曾经连续 47 次重试同一个测试。 SegmentFault 上的一篇[中文综述](https://segmentfault.com/a/1190000047720515)提供了术语演进的完整时间线，从 Karpathy 的 Context Engineering 到 Hashimoto 首创 Harness Engineering 术语，再到 Fowler 的系统性分析。 ## 日语社区的独特视角 日语社区提供了两个英文社区较少讨论的角度。 Zenn 上的一篇文章《[ハーネスエンジニアリングでハーネスをつける対象は、AI？ いいえ、あなたです。](https://github.com/daiksud/zenn/blob/main/articles/harness-engineering-not-only-for-ai.md)》把 Harness 的对象从 AI 扩展到人。核心论点是：为 AI 整备的 Harness 同时降低了人类的 onboarding 成本。文档里写清楚「SQL 注入对策必须执行」，AI 不会忘，新来的工程师读一遍就懂。Harness 不只是给 AI 加的，也是给不够强的工程师加的。 Wantedly 工程博客的一篇[实践文章](https://www.wantedly.com/companies/wantedly/post_articles/1038437)介绍了用 LLM 本身做 guardrail 的设计。他们用 Self-consistency（多次采样取一致结果）吸收 LLM 的概率性抖动，用 Exponential backoff + Full Jitter 保证 API 通信稳定。人类审查边界案例后，把具体例子作为 few-shot 加入 prompt，持续提升判定精度。 [Qiita 上的实践指南](https://qiita.com/cvusk/items/9c3e2738eede36eb206f)则把 Harness Engineering 精炼为十个要点，从项目规则文件设计到代码库设计，每个要点都附带具体实现方法。其中关于规则文件的建议最实用：每行都要问「删掉这一行 Agent 会不会犯错」，不会就删。关键规则用 IMPORTANT 或 YOU MUST 强调，Agent 的遵守率会明显提升。 ## 交叉验证 搜索结果之间存在大量交叉验证。 LangChain 的实验数据被几乎所有文章引用，52.8 → 66.5 这组数字已经成为 Harness Engineering 论证力最强的单一证据。OpenAI 的百万行实验同样被广泛引用，但不同来源给出的细节侧重不同：OpenAI 原文强调架构约束和不变量，转载文章更强调「人类不写一行代码」的戏剧性。 Anthropic 的 context anxiety 发现在多个来源中被独立验证。iDao 的文章提到 Agent 连续 47 次重试，与 Anthropic 描述的一次性做太多模式一致。Wantdely 的 Self-consistency 方案则从另一个方向验证了 LLM 的概率性抖动是 Harness 需要处理的核心问题。 Fowler 的 Guides + Sensors 框架在所有英文和中文分析文章中都被作为基础分析工具引用。但中文社区在此基础上增加了更多组件分类，腾讯云文章的九组件模型比 Fowler 的四象限更细粒度，更适合实际工程落地。 值得注意的是，日语社区的「Harness 也给人用」视角在英文和中文社区中几乎没有被讨论。这可能反映了日本软件工程文化中对「できる人材」培养的持续焦虑。 ## 一个操作性结论 Harness Engineering 的核心论点可以压缩为一句话：模型犯错时，先追问系统为什么允许它犯这个错。 这个追问的优先级高于换模型、调 prompt、加 few-shot。原因很简单。模型是概率系统，错误是必然的。Harness 的价值在于让错误在到达人类之前被捕获和修正。 Mitchell Hashimoto 的原话最精确：「当 Agent 犯错时，不要只希望它下次做得更好。花时间设计一个方案，确保它永远不会再犯同样的错。」 如果你正在构建或使用 AI 编码 Agent，Fowler 的框架是一个好的起点。检查你的 Guides 是否完整，Sensors 是否到位，两者是否形成了闭环。如果 Agent 反复犯同一个错，这第一次是模型的问题，第二次是系统的问题。 Research 是压缩不确定性，Engineering 是压缩复杂度。两者在 frontier AI lab 中指向同一种能力：在不完整的地图上找到正确的方向。当知识本身变得越来越便宜，代码生成变得越来越便宜，唯一稀缺的是决定什么值得投入注意力的判断力。harness engineering 之所以在这个时间点成为显学，正是因为它把这种判断力编码成了可复用、可验证的系统结构。 *** ## One More Thing 我把这次搜索到的核心文献整理了一份索引，方便后续查阅。 OpenAI: [Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/) Martin Fowler: [Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html) Anthropic: [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) Anthropic: [Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps) LangChain: [Improving Deep Agents with harness engineering](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering) CMU/Amazon: [Agent Harness Engineering: A Survey](https://openreview.net/pdf/f358711a95aaaf61fdeffd4ef3fc60fba9b8da57.pdf) Mitchell Hashimoto 原始定义: [Lysander 的整理](https://lysander.bond/en/blog/harness-engineering-guide/) ## 相关文章 - [模型优先](https://fanshikun.com/model-first-then-agent/) - [智能体时代人的位置](https://fanshikun.com/智能体时代人的位置/) - [简单需求自建](https://fanshikun.com/简单需求自建/) - [让博客对 Agent 友好](https://fanshikun.com/让博客对-agent-友好/)