Coding Agent难在Harness

一篇近日公开的实证研究，正在把 Coding Agent 的竞争焦点从「谁用了更强的模型」推向「谁为模型搭好了更可靠的工作环境」。截至 2026 年 9 月 18 日，预印本《An Empirical Study of Harness Design for Coding Agents》（arXiv:2609.20804）系统讨论了一个越来越现实的问题：当底层模型相同，为什么不同 Coding Agent 的工程表现仍会拉开明显差距？

答案不是再加一段提示词，而是重新设计 Harness。

**Harness 是包裹在模型外部、负责提供工具、上下文、执行状态、验证反馈和权限边界的工程系统。**模型负责判断下一步做什么，Harness 则决定模型能看到什么、能操作什么、如何知道自己做错了，以及什么时候必须停下来。

这篇研究最值得关注的地方，不是给出一套所谓「最佳配置」，而是把过去经常被打包讨论的 Agent 系统拆成了三个可分析的变量：工具链、上下文和验证策略。它传递出的核心判断很明确：Coding Agent 的效果不是模型能力的简单投影，而是模型与 Harness 交互后的系统结果。

Harness 不是外壳，而是 Agent 的操作系统

**Coding Agent 是能够读取代码库、修改文件、运行命令并根据结果继续行动的软件开发代理。**与只能回答问题的代码助手相比，它需要连续执行搜索、规划、编辑、编译、测试和修复等动作，任何一个环节的信息失真都可能让后续步骤整体偏航。

过去一年里，行业容易把 Agent 表现归因于模型版本、推理强度或上下文窗口，但真实的软件工程任务并不是一道静态题目。Agent 要面对不完整文档、历史包袱、隐式架构约束、缓慢测试、随机失败和相互冲突的工具输出，这些问题都发生在模型之外。

**Harness Engineering 是对 Agent 执行环境、反馈路径和约束机制进行系统设计的工程方法。**它不负责替模型写代码，而是把代码库变成一个模型能够理解、操作和验证的环境。

一个完整的 Coding Agent Harness，至少包含以下六层：

| 层级 | 解决的问题 | 常见机制 | 设计失败的后果 | |---|---|---|---| | 任务入口 | Agent 到底要完成什么 | Issue 模板、验收条件、范围约束 | 做了很多工作，却没有解决目标问题 | | 上下文 | Agent 需要知道什么 | AGENTS.md、仓库地图、设计文档、状态文件 | 信息缺失或上下文被无关内容污染 | | 工具 | Agent 可以执行什么 | 文件搜索、编辑器、Shell、浏览器、数据库只读工具 | 只能猜测，无法观察真实运行结果 | | 权限 | Agent 不可以做什么 | 沙箱、路径白名单、分支保护、最小权限 | 修改越界、泄露凭证或破坏环境 | | 验证 | 如何判断结果正确 | 编译、Lint、单测、集成测试、端到端测试 | Agent 把「代码写完」误认为「任务完成」 | | 状态与退出 | 如何继续，以及何时停止 | Git 提交、进度文件、重试上限、人工升级 | 无限循环、重复尝试或跨会话失忆 |

这六层不是附加功能，而是 Agent 从演示走向生产的必要条件。一个只能修改文件、却不能运行测试的 Agent，本质上仍是一台高成本的代码生成器；一个能运行所有命令、却没有权限边界的 Agent，则更像拥有仓库写权限的不稳定自动化脚本。

实证研究的价值：把「模型不行」拆成可测量问题

**Harness 的研究难点在于多个变量会同时影响结果。**如果一次升级同时更换模型、改写系统提示、增加工具并扩展测试，很难判断最终提升来自哪里。

这篇论文的重要贡献，是将 Harness 设计放到实证框架中分析，而不是继续依赖个别团队的成功故事。工具是否足够精确、上下文是否经过筛选、验证能否产生可操作反馈，都可以通过消融和对照实验观察，而不必笼统归结为「Agent 更聪明了」。

这一思路也改变了 Coding Agent 的评测方式。单看任务完成率远远不够，团队还需要同时观察回归错误、工具调用次数、Token 消耗、墙钟时间和人工介入率。

| 指标 | 代表什么 | 为什么不能忽略 | |---|---|---| | 任务成功率 | 最终是否满足验收条件 | 最直接，但无法说明成本和过程稳定性 | | 首轮通过率 | 第一次修改能否通过验证 | 能反映上下文和计划质量 | | 回归率 | 是否破坏原有功能 | 只测新增功能会掩盖真实风险 | | 中位迭代次数 | Agent 修复了多少轮 | 迭代过多通常意味着反馈不清晰 | | Token 消耗 | 上下文与推理成本 | 成功率相近时，成本可能相差数倍 | | 墙钟时间 | 从接单到完成的实际时间 | 测试过慢会抵消自动化价值 | | 人工介入率 | 多少任务需要人类救场 | 决定系统能否真正后台运行 |

公开实践已经给出过类似信号。Terminal Bench 2.0 的一项复盘显示，在底层 GPT-5.2-Codex 不变的情况下，通过加入自验证循环、上下文工程、循环检测和更合理的推理编排，得分从 52.8% 提升至 66.5%，增加 13.7 个百分点，相对增幅约为 25.9%。这不是论文自身的实验数据，但它说明 Harness 优化足以产生接近一次模型换代的收益。

工具链设计：不是工具越多越好，而是闭环越短越好

**工具链是 Agent 感知并改变软件环境的接口集合。**一个有效的最小工具链，应当覆盖搜索、读取、编辑、执行和检查差异五种基本动作。

Agent 最常见的问题不是没有工具，而是工具输出不适合机器继续推理。例如，一次测试命令输出 5 万行日志，人类可以凭经验跳到最后寻找报错，但模型可能把大量上下文消耗在无关警告上；一个只返回「失败」的内部工具，则没有告诉 Agent 下一步该改哪个文件。

因此，工具首先要提供结构化、局部且可行动的反馈。好的错误输出应该明确指出失败对象、位置、原因和建议动作，而不是把整份构建日志原样塞回上下文。

**工具粒度过粗会让 Agent 失去定位能力，工具粒度过细则会增加决策成本。**例如，只提供一个「修复项目」按钮，Agent 无法知道内部发生了什么；反过来，如果读取一段文件都要组合多个低层调用，Agent 又会把大量推理花在操作协议上。

实践中更可靠的组合通常是：

1. 使用代码搜索和符号索引定位相关实现，而不是默认遍历整个仓库。
2. 使用局部编辑或补丁机制修改代码，同时保留清晰的 Diff。
3. 使用确定性命令完成编译、格式化、静态检查和测试。
4. 将超长日志写入文件，只向 Agent 返回摘要、错误行和文件路径。
5. 在独立容器或 Git Worktree 中运行任务，避免并发 Agent 相互污染。
6. 对删除文件、修改 CI、变更依赖和访问生产资源设置更高权限门槛。

这里的关键不是 MCP、Shell 或某个特定编辑器协议谁更先进，而是工具能否形成短闭环：Agent 做出修改后，应在尽可能少的步骤内获得可信结果。

上下文设计：把「全都告诉它」改成渐进式披露

**上下文管理是选择、组织和更新 Agent 当前可见信息的过程。**它的目标不是填满上下文窗口，而是让与当前决策最相关的信息保持最高可见度。

很多团队的第一反应，是把编码规范、目录说明、架构文档、历史事故和部署流程全部塞进一个巨大的 AGENTS.md。这个方案短期有效，长期通常会退化：文件越来越长，规则互相冲突，过期内容无人清理，每次任务都要为无关信息支付 Token 和注意力成本。

更合理的做法，是把 AGENTS.md 设计成仓库入口和目录，而不是百科全书。根文件只保留全局原则、常用命令、禁止事项和文档索引，具体模块的知识放回对应目录，由 Agent 在任务需要时继续读取。

| 上下文层级 | 应包含的信息 | 加载方式 | |---|---|---| | Tier 0：全局入口 | 构建命令、测试入口、仓库边界、关键禁令 | 每次任务默认加载 | | Tier 1：任务上下文 | Issue、验收条件、相关模块、已知限制 | 接单时加载 | | Tier 2：实现上下文 | 源码、接口、局部设计文档、相邻测试 | 搜索后按需加载 | | Tier 3：诊断上下文 | 失败日志、性能数据、浏览器证据 | 验证失败时加载 | | Tier 4：历史状态 | 已完成步骤、未解决问题、Git 提交 | 跨会话恢复时加载 |

**渐进式披露是根据当前任务阶段逐步开放信息，而不是一次性注入全部资料。**这种设计不仅节省 Token，更重要的是减少旧决策、重复日志和无关代码对模型注意力的干扰。

部分实践者把上下文占用约 40% 视为模型从「聚焦区」走向「混乱区」的观察点，但这个数字不能直接当成行业标准。不同模型的注意力分布、缓存机制和长上下文训练方式并不相同，团队应该通过任务回放找到自己的压缩或重置阈值。

长任务还需要解决跨会话失忆。相比要求新会话重新阅读全部聊天记录，更稳妥的方式是维护结构化状态文件，记录目标、已完成工作、当前测试结果、关键决策和下一步动作。新 Agent 接班时先读状态，再检查 Git Diff 和最近提交，效果类似工程团队的交接班记录。

验证策略：Agent 写完代码，只完成了一半工作

**验证策略是用可重复的证据判断 Agent 输出是否满足功能、质量和安全要求的机制。**它是 Harness 中最接近「信任基础设施」的一层。

模型可以解释代码为什么正确，但解释不能替代执行。只让 Agent 自我审查，很容易形成生成者与评审者共享同一盲区的情况：它用同一种错误理解写出代码，再用同一种理解证明代码没有问题。

更可靠的验证顺序应该从便宜、确定的检查开始，再逐步进入昂贵、开放的检查：

| 验证层 | 典型手段 | 成本 | 适合发现的问题 | |---|---|---:|---| | 语法与格式 | Parser、Formatter、类型检查 | 低 | 语法错误、类型不匹配、格式违规 | | 静态规则 | Linter、依赖规则、自定义架构检查 | 低至中 | 循环依赖、越层调用、危险模式 | | 局部测试 | 单元测试、受影响测试选择 | 中 | 函数行为、边界条件、局部回归 | | 集成验证 | 服务联调、数据库迁移、契约测试 | 中至高 | 模块协作、接口兼容、状态问题 | | 端到端验证 | 浏览器自动化、截图、用户流程回放 | 高 | UI 行为、真实流程、环境差异 | | 推理型评审 | AI Review、人类 Review | 不稳定 | 设计问题、可维护性、需求偏差 |

验证结果还必须能够驱动下一轮行动。一个好的失败反馈，不只是说「测试未通过」，而是告诉 Agent 哪个用例失败、预期与实际值是什么、失败发生在哪个提交之后，以及是否可能属于不稳定测试。

**验证闭环是修改、执行、读取失败、重新定位和再次修改的循环。**这个循环必须设置退出条件，通常可以限制为 3 至 5 轮；超过上限仍无法通过时，应保存当前状态并升级给人类，而不是允许 Agent 无限消耗时间和 Token。

修复 Agent 也不能绕过原有门禁。即使它是在处理 Review 意见，也必须重新经过静态检查、测试和权限策略；否则系统等于在控制闭环里留了一个以「修 Bug」为名的旁路。

三个变量不是相加，而是相乘

**工具、上下文和验证之间存在明显的交互效应。**强工具配上错误上下文，会让 Agent 更快地改错地方；完整上下文配上薄弱验证，会产出看似合理但无法运行的代码；严格验证配上低质量错误信息，则可能让 Agent 在同一个失败点反复打转。

因此，团队不能只问「有没有测试」或「有没有 AGENTS.md」，而应该检查整个闭环是否畅通。

| 组合 | 典型表现 | 判断 | |---|---|---| | 强模型 + 弱工具 + 弱验证 | 代码看起来不错，但无法证明可用 | 演示级 | | 强工具 + 过量上下文 + 弱验证 | 动作很多、成本很高、容易跑偏 | 高消耗低可靠 | | 适量上下文 + 强验证 + 差反馈 | 能发现错误，但修复效率低 | 闭环不完整 | | 可发现上下文 + 确定性工具 + 分层验证 | 能自主定位、修改、验证和退出 | 生产级基础 |

这也是实证研究带来的重要提醒：不存在脱离仓库环境的万能 Harness。前端项目需要浏览器证据，编译器项目更依赖测试子采样和性能基准，数据工程项目则必须强化数据权限、Schema 验证和结果可追溯性。

一个可落地的最小 Harness，先做这八件事

**小团队不需要一开始就建设复杂的多 Agent 平台。**对于 2 至 3 人的开发团队，先搭出最短可验证闭环，收益通常高于增加更多角色和编排层。

P0：先让 Agent 能安全完成一次任务

1. **建立仓库入口文件。**用简短的 AGENTS.md 写清构建命令、测试入口、目录边界和禁止事项。
2. **提供一键验证命令。**Agent 不应该猜测应该依次运行哪些脚本。
3. **隔离工作空间。**每个任务使用独立分支、容器或 Git Worktree。
4. **限制危险操作。**删除文件、修改权限、访问外部系统和变更 CI 必须额外确认。
5. **保留可检查的 Diff。**不要让 Agent 直接产生无法审计的工作区状态。
6. **设置最大迭代次数。**建议先从 3 至 5 轮开始，再根据回放数据调整。
7. **保存结构化进度。**跨会话任务必须记录完成项、失败项和下一步。
8. **明确完成定义。**只有满足验收条件并通过验证，任务才算完成。

P1：再优化成本和长期稳定性

**第二阶段的目标是减少无效上下文与重复失败。**团队可以增加受影响测试选择、日志摘要、架构 Linter、浏览器证据和失败分类，并把 Agent 经常犯的错误逐步沉淀为机器可执行规则。

Ghostty 等项目采用的思路很值得借鉴：AGENTS.md 中的规则不来自一次性头脑风暴，而是来自真实失败案例。Agent 每出现一种可复现错误，团队就决定应该通过文档、工具、测试还是权限机制防止它再次发生。

P2：最后才考虑多 Agent 编排

**多 Agent 不是可靠性的起点，而是单 Agent 闭环成熟后的扩展手段。**如果单个 Agent 连测试失败都无法正确定位，增加规划 Agent、编码 Agent 和评审 Agent，只会把问题变成更昂贵的消息传递系统。

专业化角色在大规模场景中确实有价值，例如让不同 Agent 分别负责实现、去重、性能、文档和安全检查。但每个角色都需要明确输入、输出、权限和退出条件，否则角色数量越多，状态同步和错误归因越困难。

最容易踩的五个坑

**第一个坑是把提示词长度误认为工程成熟度。**数百行规则会迅速过期，而且自然语言约束的强制力弱于测试、类型系统和 Linter。

**第二个坑是让 AI 评审替代确定性验证。**AI Review 适合发现设计异味和需求偏差，但不能替代编译、单测和端到端执行。

**第三个坑是允许 Agent 无限重试。**没有预算和退出条件的自修复循环，会把同一种失败重复包装成新的推理过程。

**第四个坑是只在绿地项目验证 Harness。**拥有十年历史、测试不一致和文档残缺的棕地仓库，才是多数企业真正面对的环境；此时应先建立基线、分模块启用规则，避免一次引入成千上万条无法处理的告警。

**第五个坑是把 Harness 当成一次性交付。**模型能力、工具协议和代码库结构都会变化，曾经必要的 Reviewer、压缩器或 Linter 可能逐渐成为额外成本，必须持续通过数据决定保留还是删除。

团队应该怎样评估自己的 Harness

**Harness 评估应该使用真实历史任务，而不是只挑适合展示的 Demo。**一个务实的方法，是从过去 3 个月的 Issue 中抽取 50 至 100 个任务，覆盖修 Bug、小功能、重构、测试补充和文档修改，并在固定模型、固定推理强度下进行 A/B 测试。

每次实验至少记录任务成功率、首轮通过率、中位迭代次数、Token、墙钟时间、回归率和人工介入率。只有这样，团队才能判断新增的上下文是否真正提高成功率，还是仅仅增加了成本；新增的 Reviewer 是否捕获了真实错误，还是制造了更多噪声。

固定模型版本与推理配置同样重要。如果实验期间同时更换模型，就无法区分提升来自 Harness 还是底层能力。生产环境还应该保存关键工具调用、验证结果和停止原因，以支持事故回放。

结论：下一轮竞争，不只是谁的模型更强

**Coding Agent 的真正门槛，正在从代码生成能力转向系统工程能力。**模型决定了 Agent 能想到什么，Harness 决定这些想法能否在真实代码库里被安全执行、及时纠错并形成可交付结果。

这篇实证研究的意义，就在于把 Harness 从经验主义推向可测量的工程对象。它没有证明存在一套适合所有项目的万能模板，反而说明团队需要围绕自己的仓库、任务和风险建立证据。

对开发团队来说，当前最有价值的动作不是再写一版更长的系统提示，而是检查三个问题：Agent 能否直接获得必要工具，当前上下文是否只包含有效信息，验证失败是否能够变成下一步可执行动作。

如果这三个问题没有答案，再强的模型也只能偶尔交出漂亮 Demo；如果工具、上下文和验证形成闭环，一个并非最新的模型，也可能稳定完成过去必须由人类盯守的工程任务。

参考来源

• OpenAI Codex GitHub 仓库：了解 Codex CLI 的仓库执行环境、工具能力与开源实现。
• Anthropic Claude Code GitHub 仓库：了解长时间编码任务、工具调用及项目级工作方式。
• Terminal Bench GitHub 仓库：用于评估 Agent 在终端环境中完成真实任务的基准项目。
• Harness Engineering 深度解析：汇总上下文管理、长任务状态交接、测试框架和棕地项目改造实践。

注：核心论文为《An Empirical Study of Harness Design for Coding Agents》，预印本编号 arXiv:2609.20804。按照链接域名限制，本文未在参考链接区附上 arXiv 地址。