Harness Engineering - 是什么、怎么设计、往哪走本文核心知识来自addyosmani的文章 Harness Engineering前言LangChain 的 Viv 有句话Agent Model Harness。如果你不是模型那你就是 Harness。原始大模型不是 Agent。只有赋予它工具、反馈循环和约束它才可靠。这就是 Harness Engineering 要解决的问题。本文从三个角度展开Harness是什么、怎么设计、往哪走。什么是harness?Viv 的一句话Agent Model Harness. If you’re not the model, you’re the harness.harness是指除模型本身之外的所有代码、配置和执行逻辑。原始模型并非agent。只有当harness赋予它状态、工具执行、反馈循环和可强制执行的约束时它才成agent。具体而言harness包括指令与行为约束层System prompts,CLAUDE.md,AGENTS.md, skill , subagent prompts这些内容定义 Agent 的角色、行为规范以及项目上下文。能力扩展层Tools, skills, MCP servers, and their descriptions运行基础设施filesystem, sandbox, browser这些决定Agent 在哪里运行以及它拥有怎样的执行能力。**编排层: **subagent spawning, handoffs, model routing一个复杂开发任务, 如何拆分任务、如何分配 Agent、如何传递上下文都属于 Harness 的职责。Hooks 和 Middleware用于确定性执行不完全依赖 Model 自己决定下一步而是通过系统规则约束 Agent 行为。例如 Agent 修改代码 - Hook 自动触发 - 运行 lint/test -反馈错误 - Agent 修复可观测性logs, traces, cost and latency meteringFilesystem 与 Git持久化状态Filesystem 是 Agent Harness 中最基础的能力之一但因为它很普通往往容易被低估。Model 只能直接操作 Context 中的信息。如果没有 FilesystemAgent 本质上只能在聊天窗口里复制粘贴内容而无法形成真正的工作流。引入 Filesystem 后Agent 获得了存放代码、数据、文档的工作空间 能将中间结果移出 Context减少上下文压力在此基础上加入 Git则进一步提供版本管理错误回滚实验分支。实际上大多数 Harness 能力最终都会依赖 FilesystemFilesystem 是 Agent 持久化状态和持续工作的基础设施。Bash 和 Code Execution通用能力工具当前主流 Agent 的执行方式通常是 ReAct LoopReason ↓ Action / Tool Call ↓ Observation ↓ RepeatSimon Willison 认为现在的 Agent 已经非常擅长执行 Shell 命令大量任务都可以通过少量精心设计的命令完成。因此Bash Code Execution 正逐渐成为 Agent 最通用的工具接口。这类似于给一个人几个专用厨房工具或者直接给他一个完整厨房。后者虽然复杂但提供了更强的自主解决问题能力。Simon Willison 是 Django 框架的联合创始人也是当下 AI 应用开发领域最具影响力的独立实践者和意见领袖。他从 Python Web 开发顶流成功转型目前专注于 LLM 应用、提示工程和 AI Agent 安全研究凭借高频率的实战博客和开源工具如llm、Datasette在 AI 编程圈拥有极高的声誉。Sandbox让 Agent 安全执行Bash 只有在安全环境里运行才有价值。直接在个人电脑上执行 agent生成的代码存在风险。sandbox 为 agent 提供隔离的运行环境使其可以执行 code检查文件安装 依赖验证工作成果通过 allow-list 限制 commands使用 network isolation按需创建或销毁环境。优秀 sandbox 还应具有良好默认配置例如预装 language runtimes、packages、Git、test CLIs 和 headless browser。browser、logs、screenshots 和 test runners 使 agent 能观察自己的成果从而闭合 self-verification loop。Memory 和 Search让 Agent 持续积累知识Model 的知识来源主要有两个Training weightsCurrent Context当无法修改 Model 权重时扩展知识最主要的方法就是Context Injection文件系统成为一种简单但有效的 Memory 机制。文件系统再次成为基础。AGENTS.md等 memory files 可以在每次启动时注入 contextagent 更新这些文件后harness 在后续 session 中重新加载从而让一个 session 中获得的知识传递到下一个 session。这是比较粗糙但确实有效的 continual learning。对于 模型训练之后的信息例如新仓库版本、最新 文档 或当天数据则需要 web search等 MCP tools。这些能力应当直接纳入 harness而不是每次都由用户临时提供。Battling context rotcontext rot 指的是随着 context window 不断被填满model 的 reasoning 和任务完成能力逐渐下降。context 是稀缺资源因此 harness 在很大程度上就是 context engineering 的 delivery mechanism。常见技术包括Compaction当 context 接近上限时harness 对旧内容进行总结并把部分信息 offload 到其他位置让 agent 能继续工作而不是等 API 因超出限制而失败。Tool-call offloading两千行 logs 之类的大型 tool result 会占据大量 context却未必带来同等信息量。harness 可以只保留 result 的开头与结尾把完整内容存入 文件系统让 agent 在真正需要时读取。Skills with progressive disclosure如果启动时把所有 tools 和 MCP instructions 全部放入 contextagent 还未行动性能就已经受到影响。skills 可以只在任务需要时暴露相关 instructions 和 tools。Full context resetsAnthropic 在 long-running harness 中还使用完整的 context reset结束当前 session根据简洁、结构化的 hand-off 文件 重建一个新 session。对于特别长的任务仅靠 compaction 并不足够。有时需要像给新工程师进行 onboarding 一样用一份清晰 brief 重新开始。Hooks强制执行层Hooks 是区分“告诉 Agent 应该做什么”和“系统强制 Agent 做什么”的关键机制。它本质上是一段在 Agent 生命周期特定节点自动执行的脚本例如Tool Call 前文件修改后Commit 前Session 启动时。Hooks 适合处理那些 Agent 不应该忘记、但又经常遗漏的事情。例如每次修改代码后自动执行 Type Check、Lint、Test阻止危险命令如rm -rf、git push --force、DROP TABLE提交代码或创建 PR 前要求人工审批写入文件后自动格式化代码。HumanLayer 提出的一个重要原则是Success is silent, failures are verbose.成功保持安静失败提供详细反馈也就是说验证通过时不要额外消耗 Context只有失败时才将错误信息注入 Agent Loop让 Agent 根据反馈自动修正。因此Hooks 本质上是在 Harness 中建立一个低成本、高反馈的控制机制不依赖 Agent 自觉遵守规则而是通过系统约束和反馈循环让 Agent 在错误发生时能够自动发现并修复。AGENTS.md 与 Tool 选择AGENTS.md是 Agent Harness 中高杠杆的配置点会在每轮对话中注入 System Prompt用于定义项目规则如代码规范、测试方式、目录约束等。设计原则保持简短它应该像 Checklist而不是完整的 Style Guide。规则越多单条规则的注意力越低。基于真实问题迭代每条规则都应该来自过去的错误或明确约束而不是提前猜测。Tool 设计同样如此。Tool 的 Name、Description、Schema 都会进入 Prompt因此少量高质量 Tool 往往优于大量重复 Tool。同时Tool Description 本身也是 Prompt 的一部分MCP Server 的内容会直接影响 Agent 行为因此 Tool 设计不仅决定能力也决定安全边界。核心原则少而精的规则 清晰的 Tool 定义比堆积 Instructions 和工具更能提升 Agent 可靠性。从行为反推 Harness 设计Viv 提出的一个最有价值的设计方法是不要从“我要构建什么 Harness”出发而应该从“希望 Agent 表现出什么行为”出发再反推需要哪些 Harness 能力。即目标行为 → Harness 设计每一个 Harness 组件都应该对应 Model 本身无法可靠完成的一类行为。例如需要持久化处理真实数据→ Filesystem Git需要编写并执行代码→ Bash Code Execution需要安全执行任务→ Sandbox 默认工具环境需要记住新知识→ Memory Files、Web Search、MCP需要处理长 Context→ Compaction、Tool Offloading、Skills需要完成长期任务→ Ralph Loop、Planning、Verification这种设计方式的价值在于每个 Harness 组件都有明确职责。如果一个组件无法回答“它解决了 Agent 的什么具体行为问题”那么它很可能是不必要的复杂度。核心原则不要为了堆叠 Harness 能力而设计 Harness而应该围绕 Agent 想要实现的行为反向构建所需能力。Long-horizon Execution长程任务长程任务是 Agent 最具价值、也是最难实现的能力之一。目前 Model 仍容易出现Early stopping提前结束复杂任务拆解能力不足跨多个 Context Window 后失去连续性。因此需要通过 Harness 设计来解决这些问题。**Ralph Loop **的核心思路是当 Agent 试图结束任务时由 Hook 拦截退出并将原始目标重新注入新的 Context Window迫使 Agent 继续执行。每轮 iteration 使用新的 Context但通过文件系统读取上一轮 State从而将 Single-session Agent 转变为 Multi-session Agent。**Planning **则是让 Agent 先将目标拆解为多个步骤并保存为 Plan File。执行过程中Agent 根据计划推进每完成一步通过 Self-verification 检查结果如果失败Hook 将错误信息反馈回 Agent让其修正。此外Anthropic 的实践表明将Generator生成和Evaluator评估分离通常比让 Agent 自我评估更可靠因为 Agent 往往会高估自己的结果。类似的模式还有 Sprint Contract在开始执行前先明确“完成”的标准Done Condition减少任务范围漂移Scope Drift。核心思想长程 Agent 的关键不是单纯提升 Model 能力而是通过 Planning、Verification 和 Feedback Loop让 Harness 帮助 Agent 持续完成复杂任务。Harness 决定 Agent 能力的释放上限模型能力决定 Agent 的理论上限而Harness 决定这些能力能够被释放多少。很多开发者遇到 Agent 失败时会默认认为Agent 表现不好是因为 Model 不够强需要等待下一代模型。但 Harness Engineering 认为很多问题并不是 Model 的限制而是 Harness 设计不足。例如Agent 不知道项目规范 → 将规则加入AGENTS.mdAgent 执行危险操作 → 通过 Hook 和 Permission Gate 拦截Agent 在复杂任务中迷失 → 引入 Planner / Executor 分离Agent 生成错误代码 → 加入 Type Check、Test 等 Feedback Loop。正如 HumanLayer 所说“这不是 Model 问题而是配置问题。”一个典型案例是 Terminal Bench 2.0同一个 Claude Opus 4.6 模型在不同 Harness 环境下表现差异巨大。Viv 的团队仅通过优化 Harness就将 Coding Agent 排名从 Top 30 提升到 Top 5。他们没有更换 Model而是优化Tools、System Prompt、Verification、Feedback Loop。这说明当前 Agent 的关键瓶颈往往不是 Model 能力不足而是Model 与实际应用之间存在 Harness Gap。未来 Agent Engineering 的竞争不只是等待更强的模型而是通过更优秀的 Harness让现有 Model 发挥更接近理论上限的能力。Harness 不会消失它会移动一种常见但过于简单的观点是随着 Model 能力不断增强Harness 的重要性会逐渐降低。但实际情况更加复杂。Model 的进步确实会让部分旧的 scaffolding辅助机制失去必要性。例如Opus 4.6 显著缓解了 context anxiety上下文焦虑问题。过去Sonnet 4.5 在接近 context limit 时容易因为误判剩余上下文空间不足而提前结束任务。随着这一能力缺陷被 Model 自身修复原本用于缓解该问题的 anxiety-mitigation scaffolding焦虑缓解机制便可以被移除。然而这并不意味着 Harness 变得不重要而是意味着 Harness 的关注点会向新的复杂问题迁移。图中显示的就是GEN N: Harness: 规划 工具 验证GEN N1: Model吸收: 规划 验证 Harness新增: 长期记忆 多AgentGEN N2: Model吸收更多 Harness新增: 动态Context 自调试 ;模型越来越聪明会吞掉旧 Harness 的“智能部分”但 Harness 不会消失而会向更复杂的系统工程方向发展记忆、协作、评估、上下文管理、可靠执行Harness-as-a-ServiceHaaSViv 提出Harness-as-a-ServiceAgent 开发正在从LLM API转向Harness API。过去LLM API 只提供模型能力开发者需要自己实现 Loop、Tool Calling、State、Approval Flow。现在Harness API如 Claude Agent SDK、Codex SDK、OpenAI Agents SDK直接提供 Agent Runtime包括 Loop、Tools、Context Management、Hooks 和 Sandbox开发者只需进行业务定制。Agent 开发模式也从自己构建 Agent Runtime转变为选择 Harness Framework围绕 System Prompt、Tools、Context、Subagents 四个核心进行优化。这样 Agent 出问题时不需要重新造一个 Agent而是在已有 Harness 上迭代配置。Viv 的观点Good agent building is an exercise in iteration. You can’t do iterations if you don’t have a v0.1.优秀 Agent 不是一次设计出来的而是在 v0.1 基础上通过持续反馈不断优化 Harness。生产环境中的 Harness 形态目前公开资料中对成熟 Harness 架构描述最清晰的案例之一是 Fareed Khan 对 Claude Code 架构的拆解。Claude Code 的整体架构可以分为多个层Input Layer输入层负责用户交互包括 User Interface、Session Manager、Permission GateKnowledge Layer知识层负责上下文和知识管理包括 Skill Registry、Context Compressor、Task Graph、Memory StoreIntegration Layer集成层负责 MCP Runtime 和外部服务接入Execution Layer执行层负责 Tool Dispatch、Streaming Runtime、Prompt CacheOutput Layer输出层返回经过验证的任务结果Observability Layer可观测层包括 Event Bus 和 Background ExecutorMulti-agent Layer多 Agent 层负责 Subagent Spawn、Mailbox、FSM Protocol、Autonomous Board 和 Worktree Isolator。整个系统的核心是 Agent Loop各个层围绕它提供能力支持。前文讨论的 Harness 概念几乎都能在这张架构图中找到对应组件Context Injection → Knowledge LayerLoop State → Memory Store 和 Worktree IsolatorDestructive-action Hooks → Permission GateSubagent Context Firewall → Multi-agent LayerTool Dispatch Registry → MCP Servers 和 Bash 的统一入口。Khan 的观点与 Viv 的核心思想一致只是通过一个真实产品进行验证Claude Code 的演进不仅取决于底层 Model 能力更取决于围绕 Model 构建的 Harness。换句话说优秀 Agent 的竞争不只是“使用什么模型”而是“如何构建让模型发挥能力的运行环境”。结语总结开头的问题harness是什么、怎么设计、往哪走从最简单的来看**Agent Model Harness。**harness就是除了模型之外的所有东西包括工具约束提示词等有了这些模型之外的东西才组成了能帮我们稳定完成任务的agent而我们需要设计harness的目的正是出于模型的输出本质是概率性事件harness是我们对模型不确定性不信任部分的具像化所以我们也应该从这些不信任的行为反推harness的设计对于harness往哪走随着模型的发展有一部分harness的能力会被模型吸收但是在这过程中又会有新的问题需要harness解决