上周Google Cloud / Gemini 工程师 Addy Osmani 写了一篇文章题目叫《Agent Harness Engineering》。只看标题的话Harness Engineering 这个话题其实已经不算新鲜了。从年初到现在Harness Engineering 这个词在国内外技术圈反复被提及。国内也有不少企业实践文章比如阿里云的那篇《Harness Engineering耗时一周我是如何将应用的 AI Coding 率提升至 90% 的》可见文末延伸阅读。如果只是解释“什么是 Harness”这篇文章不会有太多新信息。但 Addy 这篇文章出现以后再加上 Anthropic 之前连续发布的几篇关于长程 Agent、长程应用开发、Managed Agent 和 Agent Eval 的工程分享以及 OpenAI 关于 Codex 团队如何用 Agent 交付内部产品的案例御三家的 Harness 思路刚好拼到了一起。如果说 Gemini 这边的 Addy 负责把 Harness Engineering 讲成一个清晰的方法论OpenAI 展示了 Codex 进入生产级代码库的案例那么 Anthropic 更像是在把 Harness 拆成一整套 Agent 操作系统。合起来看它们说的是同一层东西模型之外的工程系统。这层系统现在常被叫作 Harness。Harness 要解决什么问题一个 Agent 连续跑几个小时以后真正麻烦的地方常常不是它能不能继续往下跑而是它是否还知道自己在做什么。它怎么知道刚才做到哪一步怎么判断任务真的完成了上下文变长以后怎么避免跑偏下一轮 Agent 接手时怎么知道哪些已经做完哪些只是半成品同一个错误反复出现时怎么把它变成系统里的规则而不是每次都重新碰壁这些问题看起来像是模型能力问题但放到真实工程里很多其实是系统问题。人类工程师接手长任务时也不会只靠记忆。我们会看需求文档、任务列表、提交记录、测试结果、代码规范和运行日志也会通过 CI、Code Review 和线上指标判断修改是否真的生效。Agent 也是一样。它要持续完成任务不能只靠一次 prompt 和一段上下文而需要一套外部环境来承接它的行动。所以Harness 要解决的不是“怎么让模型更聪明”而是怎么让模型在一个可持续、可验证、可恢复、有边界的环境里工作。Addy给这件事一个名字Addy Osmani 在《Agent Harness Engineering》里引用了一个很短的公式Agent Model Harness这个公式有用因为它把很多混在一起的问题拆开了。我们平时说“这个 Agent 好不好用”大多时候都会归因到模型模型聪不聪明代码写得好不好推理稳不稳。但一个编码 Agent 的表现还取决于它有什么工具、能读到什么上下文、在哪里运行、是否有测试反馈、有没有权限边界、出错后能不能回到一个干净状态。Addy 的文章把 Harness 拆成很多组成部分System Prompt、AGENTS.md / CLAUDE.md、工具、MCP、文件系统、Git、沙箱、Hooks、子 Agent、上下文策略、日志、追踪、成本和延迟观测。但重点不在记名词而在换一种看 Agent 的方式。一个 Agent 要完成工作至少需要下面的条件它需要一个地方放状态。文件系统和 Git 就是最基础、也最清楚的选择。没有它们Agent 就只能把所有东西塞进上下文里上下文一长丢失和误读就会出现。有了文件和版本历史Agent 才能留下计划、记录修改、回滚错误也能让下一轮接着上次中断的地方继续推进。它需要安全地行动。Shell、代码执行、浏览器、MCP 工具都让 Agent 能做事但行动总要发生在某个边界内。沙箱、命令 allowlist、权限确认、网络隔离都是 Harness 的一部分。它需要反馈。测试、lint、类型检查、浏览器截图、日志和指标可以把“我觉得完成了”变成“系统验证过了”。如果测试失败错误信息回到 Agent 的循环里它才有机会修正。它还需要规则。但规则不能无限膨胀。Addy 提到一个很实用的原则每次 Agent 犯错都把它当成一个信号。Agent 忘了项目约定就把约定写进 AGENTS.mdAgent 跳过测试就让 Hook 或 Reviewer 卡住Agent 执行危险命令就在工具层拦掉。这一步不能只靠堆提示词。更准确地说是把真实失败沉淀成工程约束。这也间接地解释了为什么 Harness 很难“下载即用”。通用框架能提供循环、工具、沙箱和接口但真正有用的规则往往来自某个团队自己的失败历史。一个好的 AGENTS.md 不应该是愿望清单更像飞行检查单短明确每一条最好都能追溯到某个真实风险。Addy 那篇文章还有一个判断适合放到后面一起看Harness 不会随着模型变强而消失它只会跟着模型能力的边界一起演变。如果模型已经能稳定做某些事原来补这块短板的脚手架就该删掉否则它会变成负担和噪音。与此同时更强的模型会让更复杂的任务进入可做范围这些任务会暴露新的失败模式于是新的 Harness 结构又出现了。这就让 Harness 像是一层活的工程系统而不是一次性配置。Anthropic把 Harness 拆成一套 Agent 操作系统在这三家里Anthropic 是把 Harness 拆得最细的一家。它不只是讨论“怎么让 Agent 写代码”还从 Claude Code 的具体使用方式一直讲到 Claude Agent SDK、Context Engineering、Tool Design、MCP Code Execution、Long-Running Harness、Managed Agents 和 Agent Eval 等多个工程角度。看起来 Anthropic 这些文章主题都很分散但其实都在补同一套系统上下文怎么进入工具怎么暴露状态怎么保存反馈怎么回流权限和执行环境怎么隔离以及最后怎么判断 Agent 真的做对了。也就是上面提到过的 Harness 所要解决的问题。长程任务先看长程任务。在《Effective harnesses for long-running agents》里Anthropic 观察到一个很具体的问题当 Agent 要跨多个上下文窗口做长任务时任务很容易散掉。第一个原因是 Agent 想一次做太多。给它一个大目标比如做一个完整 Web 应用它会试图一口气完成。结果常常是在上下文快耗尽时留下一堆半成品。下一轮 Agent 进来都不知道哪些已经做完哪些只是看起来做了只能先花时间重新判断当前进度。第二个原因是过早宣布完成。项目已经有一些文件和功能以后后续 Agent 容易看到“进展不少”然后判断任务差不多结束了。但真实情况可能是核心功能没跑通测试没跑边界情况没处理。这两个问题不只是“模型不够聪明”还有过去记录缺失的问题。我们接手长项目时尚且需要任务列表、提交记录、进度说明、验收标准和测试环境。Agent 会更依赖这些东西因为每一轮上下文都可能不完整。Anthropic 的一个解法是拆出 Initializer Agent 和 Coding Agent。Initializer Agent 先做地基设置运行环境生成 Feature List写 Progress File留下初始提交。后续 Coding Agent 每次都只做增量工作从 Git History、Progress File 和 Feature List 中理解当前任务状态选一个还没完成的功能推进并在结束时留下干净状态。Feature List 的设计很关键。它不能停在一句“做一个像 claude.ai 的应用”这种概述性需求而是要将概述性需求拆解成一组可检查的功能要求。每个功能有步骤有 Pass / Fail 状态。Anthropic 后来选择用 JSON 存 Feature List也明确要求 Coding Agent 不要删除或改写测试要求只能更新状态。这说明一件事长程 Agent 的问题很大一部分是交接问题。Harness 要让下一轮 Agent 不必靠猜。再往前一步是上下文怎么进入 Agent。上下文工程在 Context Engineering 相关实践里Anthropic 讨论的不是“把更多的内容塞进上下文”而是如何让 Agent 在需要时拿到正确的信息。上下文不是越多越好。入口太长、工具太多、说明太杂都会挤占模型处理真正任务的空间。比较好的方式是让信息保持可导航短入口、结构化文档、按需读取、必要时通过工具查询。Agent 不需要一开始读完整本手册它更需要一张地图知道什么时候该去哪里找信息。这和长程 Agent 里的 Progress File、Feature List 是同一个逻辑重要的信息不能只留在上下文里而要放到 Agent 能稳定发现、稳定读取的位置。然后是工具怎么设计。工具的设计Anthropic 在 Tool Design 和 MCP Code Execution 相关内容里强调过一个问题工具不是越多越好。工具描述、参数结构、返回格式和错误信息都会影响 Agent 的行动质量。如果工具的描述含糊不清Agent 可能根本不知道什么时候该用如果返回结果太长关键信息会被淹没如果错误信息不可读Agent 就很难进行自我修正。MCP 工具一多还会带来新的上下文开销光是工具定义和中间结果就可能占掉大量 token。所以 Harness 不只是“给 Agent 接工具”。更重要的是把工具设计成 Agent 能理解、能选择、能验证的行动接口。另一个问题是自评。反馈机制在《Harness design for long-running application development》里Anthropic 讨论了 Planner、Generator、Evaluator 的结构。这个结构的价值不在于多拆了几个 Agent而在于解决了一个很具体的问题生成者评价自己时经常偏乐观。尤其是前端设计、产品体验、架构质量这类任务没有一个简单的单元测试能告诉你交付质量“好不好”。Agent 自己做完之后很容易就给自己一个不错的评价。Anthropic 的做法是把生成和评价拆开让 Evaluator 按明确标准检查结果并用 Playwright 去操作真实页面。他们的例子很直观。同一个 retro game maker 任务Solo Agent 跑了 20 分钟成本约 9 美元完整 Harness 跑了 6 小时成本约 200 美元。后者明显更贵更慢但输出质量高很多至少核心玩法能跑起来。此外真正有用的是这个机制Planner 把一句话扩展成多 Sprint 的 SpecGenerator 按 Contract 实现Evaluator 根据可测试标准操作应用、提交具体 bug。这套结构后来也被 Anthropic 重新裁剪优化。随着模型的变强一些原来必要的 Sprint Decomposition 可能变成开销但 Planner 和 Evaluator 在边界复杂的任务上仍然有价值。Anthropic 的判断很克制每个 Harness 组件都编码了一个关于“模型现在还做不好什么”的假设。模型变了假设就要重新检查。到《Managed Agents》这篇Anthropic 又把问题往基础设施层推了一步。被管理的 AgentAnthropic 把 Agent 系统拆成三个部分Session、Harness、Sandbox。Session 是事件日志记录发生过什么。Harness 是调用 Claude、组织上下文、路由工具调用的循环。Sandbox 是执行代码、编辑文件、运行工具的环境。这套 Agent 系统的拆解要解决的是长期运行时的可恢复性和安全边界问题。如果 Harness 和 Sandbox 绑在同一个容器里容器挂了Session 可能也丢如果生成代码和凭证在同一个环境里安全风险也会变大。Anthropic 用 “Brain” 和 “Hands” 来形容这件事Harness 更像负责思考和调度的 BrainSandbox 更像负责执行动作的 HandsSession 则记录整个过程。把这三者拆开以后执行环境可以失败重建Harness 可以无状态恢复Session Log 也可以作为上下文窗口之外的可查询记忆。这跟普通应用架构很像。系统一旦要长期运行就不能把状态、执行和控制逻辑混在一起。Anthropic 的 Agent Eval 文章补上了最后一块怎么知道 Agent 真的变好了Agent 评估他们把 Agent Eval 拆成 Task、Trial、Grader、Transcript、Outcome。这里的重点是 Outcome。一个 Agent 说“已经订好机票”没有意义真正要看环境里的数据库是否出现了预订记录。一个编码 Agent 说“我修好了漏洞”也不够要看测试、静态分析、日志状态和工具调用轨迹。这让评估也成了 Harness 的一部分。Agent 的质量不能只看最终回答还要看它在环境中的行动和结果。所以Anthropic 这组文章真正完整的地方在于它不是只解决一个“长任务怎么跑完”的问题而是在把 Agent 拆成一套操作系统。Agent 操作系统Claude Code 解决具体工作流Claude Agent SDK 把这套能力抽象成可复用的开发接口Context Engineering 解决信息进入方式Tool Design 和 MCP Code Execution 解决工具效率Long-Running Harness 解决跨上下文交接Managed Agents 解决 Session、Harness、Sandbox 的基础设施拆分Agent Eval 负责判断系统是否真的变好了。这些内容合在一起Anthropic 讲的其实不是某个单点技巧而是一个更完整的问题当 Agent 不再只是回答问题而是要长期运行、调用工具、修改环境并接受评估时外部系统应该怎么承接它。OpenAI展示生产级代码库要怎样变形OpenAI 的 Codex 文章最容易被记住的是几个数字他们说团队在五个月里做了一个内部 beta 产品没有人工手写代码代码库大约百万行约 1,500 个 PR估计用手写代码十分之一左右的时间完成。这些数字很醒目但文章真正有价值的地方不在“Agent 写了多少代码”。更值得看的是为了让 Codex 能持续工作他们把代码库改造成了什么样。第一点是Repo 成了记录系统。OpenAI 试过一个巨大的AGENTS.md后来认为这个方式不行。原因很简单上下文是稀缺资源一个巨大说明文件会挤掉任务、代码和相关文档规则太多以后所有规则都变轻大文件也会迅速腐烂难以验证新鲜度。OpenAI 后来没有把所有信息都塞进一个巨大的AGENTS.md而是把AGENTS.md当成 Agent 的入口导航它只告诉 Agent 应该去哪里找信息。真正的知识则放进仓库里的docs/文档目录比如设计文档、执行计划、产品规格、参考资料、质量标准、可靠性说明和安全规则。计划和决策日志也会进入仓库成为 Agent 可以读取的工程记录。这里有一个很实际的判断Agent 看不见的东西就等于不存在。Google Docs、Slack 讨论、人的脑子里的隐性知识如果没有进入它能读取的“可见”范围就不能指望它稳定遵守。第二点是应用本身要对 Agent 可观察。OpenAI 提到他们让 Codex 可以按 Git Worktree 启动应用实例也把 Chrome DevTools Protocol 接入 Agent 运行时让 Codex 能操作页面、看 DOM、截图、复现问题和验证修复。此外日志、指标、trace 也会暴露给 Codex让它能用 LogQL、PromQL 之类接口查询运行状态。这很关键。很多时候Agent 写错代码是因为它没有看到真实运行结果。把 UI、日志和指标变成 Agent 可读的反馈等于把 QA 的一部分还给了系统。第三点是架构约束和品味被编码。OpenAI 说文档本身不足以维持一个 Agent 生成代码库的连贯性。他们用自定义 lint、结构测试、命名规则、文件大小限制、结构化日志要求等方式机械地强制约束 Agent。比如在模块边界处校验传入数据的结构和字段类型但不强行规定一定使用哪个校验库规定业务域内的依赖方向越界就由工具拦下。这和人类团队里的“代码规范”有点像但对 Agent 更重要。人类可以根据上下文关联自行获得边界Agent 却需要明确边界。规则一旦写进工具就能在每个 PR 上重复执行。OpenAI 还写到了“熵”和“垃圾回收”。Agent 会复制代码库里已有模式不管那些模式好不好。吞吐量越高漂移也越快。于是他们把一些“黄金原则”编码到仓库里并定期让后台 Codex 任务扫描偏差、更新质量评分、打开重构 PR。这里也要保留边界。OpenAI 文中明确说这些能力高度依赖特定代码库结构和工具投入不能假设没有类似投入的团队也能直接得到同样结果。它不是一句“让 Agent 自动写代码”就能完成的事。真正的工作是把仓库变成 Agent 可以理解、验证和维护的工作场。可以把 Harness 看成五层把 Addy、Anthropic 和 OpenAI 的文章放在一起可以抽出一个比较实用的诊断框架Harness 至少可以看成五层。第一层是Context。Context 不能只求多关键是可导航。短入口、结构化文档、渐进式披露比一个巨大的说明文件更适合 Agent。Addy 讲 AGENTS.md 不要太长OpenAI 把它当目录Anthropic 用 Progress File 和 Feature List 让下一轮接得上。它们本质上都在处理同一个问题Agent 需要地图不需要被一整本手册淹没。第二层是Action。Agent 要能行动就要有工具。Shell、文件系统、Git、浏览器、MCP、数据库、标准开发 CLI都是 Action 层。工具也不能只求多。工具描述、参数结构、返回格式和错误信息都会进入 Agent 的工作循环。一个好工具应该让 Agent 更容易做对而不是给它更多模糊选择。第三层是Persistence。长程任务不能靠上下文硬撑。Git History、Progress File、Session Log、计划文档、决策记录都在把状态从短暂对话里拿出来放到可恢复、可查询的位置。Anthropic 的 Session Log、OpenAI 的 repo-as-system-of-record、Addy 提到的 FileSystem / Git其实都在强调这一层。第四层是Feedback。没有反馈Agent 很容易停在“看起来完成”。测试、lint、类型检查、静态分析、浏览器自动化、截图、日志、指标、Trace、Eval Grader都是反馈。Anthropic 的 Evaluator 和 Agent EvalOpenAI 的可观察性栈Addy 提到的 Hooks 和 Reviewer Subagent都在把反馈接回循环里。第五层是Governance。Governance 包括权限、沙箱、安全边界、Hooks、审批、人工判断和定期清理。Agent 越能行动越需要边界。Anthropic 把 Sandbox、Harness、Session 拆开是为了可靠性和安全OpenAI 用 lint 和结构测试维持一致性Addy 说失败要变规则也是在把治理从口头提醒变成系统行为。这五层不适合作为采购清单更适合当作诊断框架。当 Agent 做不好一件事时可以先问它是没看到信息不能行动没保存状态缺少反馈还是边界不清很多问题不一定要换模型。也许只是某一层 Harness 没搭好。一个克制的判断Harness 工程并不否认模型重要。更强的模型当然会减少一些脚手架也会让某些复杂机制变得多余。但模型变强以后问题不一定消失只是任务边界会继续外移。以前 Agent 做不了长任务我们关心的是上下文恢复后来它能做长任务了我们开始关心进度交接、外部评价和状态持久化再往后当它能处理更大的代码库时仓库可读性、架构漂移、安全边界和持续清理又会变成新的问题。所以Harness 工程更像一种正在成形的工程语言。它把提示词、工具、文档、测试、沙箱、评估、权限和工作流放到同一张图里让我们可以更系统地讨论一个 Agent 到底需要怎样的外部环境才能持续、稳定地完成任务。对普通开发者来说最直接的启发可以更小让项目入口更短、更清楚把隐性规则写到 Agent 能发现的位置让任务有可检查的完成条件把测试、lint、运行结果接回 Agent 循环给危险操作加边界把重复失败沉淀成工具或规则。工程师过去主要写代码。现在多了一项工作设计一个能让 Agent 持续做对事的环境。这就是 Harness 工程目前最值得关注的地方。延伸阅读阿里开发者Harness Engineering耗时一周我是如何将应用的AI Coding率提升至90%的https://mp.weixin.qq.com/s/rlIyIIZOXFObNIXbPI7gDgGeminihttps://x.com/addyosmani/status/2053231239721885918OpenAIhttps://openai.com/zh-Hans-CN/index/harness-engineering/Anthropic 核心 Harness 文章https://www.anthropic.com/engineering/managed-agentshttps://www.anthropic.com/engineering/harness-design-long-running-appshttps://www.anthropic.com/engineering/effective-harnesses-for-long-running-agentshttps://www.anthropic.com/engineering/demystifying-evals-for-ai-agentsAnthropic 相关工程实践文章https://www.anthropic.com/engineering/claude-code-best-practiceshttps://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdkhttps://www.anthropic.com/engineering/effective-context-engineering-for-ai-agentshttps://www.anthropic.com/engineering/writing-tools-for-agentshttps://www.anthropic.com/engineering/code-execution-with-mcphttps://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skillshttps://www.anthropic.com/engineering/multi-agent-research-systemhttps://www.anthropic.com/engineering/building-c-compilerhttps://www.anthropic.com/engineering/building-effective-agents