Agent Harness 设计哲学解析：释放 Claude 潜能的实践指南

Anthropic联合创始人Chris Olah曾提出一个精辟的见解：像Claude这样的生成式AI系统，更像是被“培育”而非“构建”出来的。开发者设定环境与引导方向，但其最终涌现出的能力结构与行为模式，往往超出最初的精确预期。

这为应用开发者带来了一个持续性的挑战：我们设计的智能体框架（Agent Harness）中，往往固化了许多关于“Claude当前能力局限”的预设。然而，随着Claude模型自身的快速迭代与进化，这些预设会迅速过时。因此，即便是当下总结的最佳实践，也需要定期回顾与更新。

那么，如何构建一个既能充分利用Claude最新能力，又能有效平衡响应速度与成本效益的应用呢？以下三个核心设计模式提供了关键思路。

1. 优先利用Claude的原生理解能力

一个基础而有效的策略是：尽可能使用Claude本身就熟知和擅长的工具来构建你的应用。

回顾2024年底，Claude 3.5 Sonnet在SWE-bench Verified基准测试中取得了49%的优异成绩，当时领先业界。值得注意的是，它仅使用了两个核心工具：一个bash终端工具，以及一个文本编辑器工具（用于查看、创建和修改文件）。后续推出的Claude Code也建立在这两个基础工具之上。Bash本身并非为智能体交互设计，但Claude理解其语法与逻辑，并且随着模型版本更新，其使用效率越来越高。

图片

SWE-bench Verified基准测试结果直观反映了各版本Claude在代码任务上的能力演进。

在实际开发中，你会发现Claude能够灵活组合这些通用工具，形成解决各类复杂问题的模式。例如，所谓的“智能体技能”（Agent Skills）、程序化工具调用、记忆管理工具等，本质上都是bash和文本编辑器这两种基础能力的延伸与组合应用。

图片

程序化工具调用、技能库和记忆系统，均可视为在bash与文本编辑器基础上构建的高级功能。

2. 持续反思：哪些工作可以交给Claude自动完成？

智能体框架中编码的规则，常常是为了弥补“Claude自身无法完成”的环节。随着Claude能力的不断增强，这些预设需要被持续验证和淘汰。

将动作编排决策权交给Claude

一个常见的预设是：每次工具调用的结果都必须完整返回Claude的上下文窗口，由模型分析后决定下一步。但这种模式处理速度慢、Token消耗大。如果结果只是原样传递给下一个工具，或者Claude真正需要关注的仅是输出中的一小部分，那么这种开销就得不偿失。

图片

Claude发起工具调用，工具在特定执行环境中运行并返回结果。

举例来说，为了分析大型数据表中的某一列，传统方式需要将整张表读入上下文，大量无关行会浪费Token。当然，可以通过在工具层硬编码过滤器来解决，但这本质上是让框架代替Claude做决策。更好的方式是让Claude自己来编排。

赋予Claude一个代码执行工具（如bash或特定语言的REPL）可以优雅地解决此问题：Claude能够编写代码来表达一系列工具调用及其间的逻辑关系，自主决定哪些中间结果需要传递、哪些需要过滤、哪些可以直接通过管道传递给后续步骤，整个过程无需经过上下文窗口的往返。只有代码执行的最终输出才需要进入上下文。

图片

Claude可以通过编写代码来直接定义工具调用序列与数据处理逻辑。

这样，编排决策权就从框架转移到了模型自身。具备强大编码能力的模型，本身就是高效的通用智能体引擎。这一模式的威力不仅体现在编码任务上：在测试智能体网页浏览能力的BrowseComp基准中，为Opus 4.6模型增加过滤自身工具输出的能力后，其准确率从45.3%显著提升至61.6%。

让Claude自主管理上下文信息

与任务相关的上下文信息能引导Claude使用bash、文本编辑器等通用工具。另一个常见预设是：系统提示词应预先加载详尽的任务指令。问题在于，预加载的提示难以跨多任务扩展：每个额外的Token都在消耗Claude有限的注意力预算，许多低频使用的指令预加载进来纯属浪费。

“技能”（Skills）机制巧妙地解决了这个问题：每个技能的YAML头部包含一段简短描述，会被预加载到上下文中，作为该技能内容的索引。只有当Claude判断当前任务真正需要某个技能时，才会通过读文件工具按需获取其完整内容。

图片

Claude可以利用技能机制，按需、渐进式地获取任务所需的具体上下文。

技能赋予了Claude按需组装上下文的能力，而“上下文编辑”（Context Editing）则提供了反向操作——允许Claude主动移除已过时或不再相关的内容，例如旧的工具调用结果或思考过程。

借助子智能体（Subagents）能力，Claude在判断何时需要创建新的上下文窗口以隔离特定任务方面也越发精准。Opus 4.6能够生成子智能体，在BrowseComp基准上的表现比最优的单智能体方案还要高出2.8%。

让Claude自主持久化关键上下文

长时间运行的智能体可能超出单个上下文窗口的长度限制。常见的假设是，记忆系统必须依赖模型外部的检索架构。但实际上，许多工作的重点在于为Claude提供简单的方法，让其自主决定哪些信息值得长期保存。

例如“压缩”（Compaction）机制，允许Claude对历史上下文进行总结，以便在长周期任务中维持连贯性。随着版本迭代，Claude在选择“记住什么”方面越来越有判断力。在以网页搜索为核心的BrowseComp智能体任务中，Sonnet 4.5无论分配多少压缩预算，准确率都稳定在43%；而Opus 4.5在相同设置下可提升至68%，Opus 4.6更是达到了84%。

“记忆文件夹”是另一种思路，让Claude将重要上下文写入文件，后续需要时再读取。在BrowseComp-Plus基准上，为Sonnet 4.5添加记忆文件夹功能后，其准确率从60.4%提升到了67.2%。

Claude可以将关键上下文持久化存储到指定的记忆文件夹中。

通过长周期游戏（例如《宝可梦》）观察这一能力的演进非常直观。Sonnet 3.5的记忆更像流水账，记录的是NPC说了什么，而非真正重要的战略信息。运行14000步后，它生成了31个文件（其中两个关于毛毛虫宝可梦的文件内容几乎重复），角色仍停留在第二个城镇：

caterpie_weedle_info:
- Caterpie and Weedle are both caterpillar Pokémon.
- Caterpie is a caterpillar Pokémon that does not ha ve poison.
- Weedle is a caterpillar Pokémon that does ha ve poison.
- This information is crucial for future encounters and battles.
- If our Pokémon get poisoned, we should seek healing at a Pokémon  Center as soon as possible.

而后续版本的模型则开始撰写战术笔记。Opus 4.6在相同步数时，仅生成10个文件，并按目录整理，已经获得了三个道馆徽章，甚至还有一个从自身失败经历中总结出的心得文件：

/gameplay/learnings.md:
- Bellsprout Sleep+Wrap combo: KO FAST with BITE before Sleep  Powder lands. Don't let it set up!
- Gen 1 Bag Limit: 20 items max. Toss unneeded TMs before dungeons.
- Spin tile mazes: Different entry y-positions lead to DIFFERENT  destinations. Try ALL entries and chain through multiple pockets.
- B1F y=16 wall CONFIRMED SOLID at ALL x=9-28 (step 14557)

一个学会了“从失败中总结教训”的智能体，与只会机械记录的版本，其能力差距是显而易见的。

3. 审慎地为Claude设定行动边界

智能体框架的另一核心作用，是在Claude外部建立必要的约束，以满足用户体验、成本控制或安全保障等需求。

优化上下文设计以提升缓存命中率

Messages API本质上是无状态的。Claude无法看到之前轮次的对话历史，这意味着框架每次都需要将新的上下文、所有历史动作、工具描述和指令打包发送给Claude。

提示词可以基于预设的断点进行缓存——即Claude API会将截止到某个断点的上下文写入缓存，并检查是否与之前的缓存条目匹配。由于缓存Token的费用仅为标准输入Token的10%，遵循以下原则有助于最大化缓存命中率，从而显著降低成本。

使用声明式工具处理UX、可观测性与安全边界

Claude可能并不清楚应用的安全边界或用户体验层具体在哪里。Claude输出工具调用请求，由框架负责执行。Bash工具赋予了Claude极高的编程灵活性，但对框架而言，每次调用都呈现为相同的形态——仅仅是一串命令字符串。将某些关键动作提升为专属的声明式工具，就能为框架提供一个带有类型化参数的、针对特定动作的钩子，可用于拦截、权限控制、界面渲染或审计。

需要安全边界的动作天然适合封装为专属工具。“可逆性”是一个有效的判断标准——难以撤销的动作，例如调用外部付费API，可以设置需要用户二次确认的门控。写文件这类工具可以加入版本陈旧性检查，避免Claude覆盖掉自上次读取后已被其他进程修改的文件。

专属工具允许框架根据安全、用户体验或可观测性需求，对特定动作进行定制化处理。

当一个动作需要明确展示给用户时，工具同样非常有用——可以将其渲染为清晰的弹窗，向用户展示问题并提供多个选项，或者暂停智能体循环直至获得用户反馈。

在可观测性层面，类型化的工具调用让框架能够获取结构化的参数，极大方便了日志记录、分布式链路追踪和操作回放。

当然，是否将某个动作提升为专属工具，需要持续评估。例如，Claude Code的auto-mode在bash工具外层包裹了一层安全边界：让第二个Claude实例审查命令字符串，判断其安全性。这种模式在一定程度上减少了对专属工具的需求，但仅适用于用户信任智能体整体行动方向的场景。对于某些高风险操作，专属工具仍然具有不可替代的价值。

展望未来

Claude的能力边界始终在动态扩展。每一次显著的能力跃升之后，那些关于“Claude无法处理什么”的旧有假设都需要被重新测试与验证。

这一模式不断重演。在某个为长周期任务构建的智能体中，Sonnet 4.5版本会在感知到上下文即将填满时提前终止任务，表现出“上下文焦虑”。为此，我们引入了上下文重置机制来清空窗口。然而，当Opus 4.5发布后，这一行为消失了。当初为应对旧版本问题而加入的重置机制，反而变成了框架中不必要的负担。