Harnessing

Claude’s

intelligence

One of Anthropic’s co-founders, Chris Olah, says that generative AI systems like Claude are grown more than they are built. Researchers set the conditions to direct growth, but the exact structure or capabilities that emerge aren’t always predictable.Anthropic 的联合创始人之一 Chris Olah 表示，像 Claude 这样的生成式 AI 系统更像是被“培育”出来的，而非被“构建”出来的。研究人员设定条件来引导其成长，但最终涌现出的具体结构或能力并不总是可预测的。

This creates a challenge for building with Claude: agent harnesses encode assumptions about what Claude can’t do on its own, but those assumptions grow stale as Claude gets more capable. Even lessons shared in articles like this deserve frequent revisiting. 这给基于 Claude 构建应用带来了挑战：代理框架（agent harness）编码了对 Claude 自身无法完成之事的假设，但随着 Claude 能力的提升，这些假设会逐渐过时。即使是本文分享的经验教训，也值得经常重新审视。

In this article, we share three patterns that teams should use when building applications that keep pace with Claude’s evolving intelligence while balancing latency and cost: use what it already knows, ask what you can stop doing, and carefully set boundaries with the agent harness.在本文中，我们分享了团队在构建能够跟上 Claude 不断进化的智能、同时平衡延迟和成本的应用时应采用的三种模式：利用它已知的知识、询问可以停止做什么、以及谨慎设置代理框架的边界。

1. Use what Claude knows1. 利用 Claude 已知的知识

We suggest building applications using tools that Claude understands well. 我们建议使用 Claude 熟悉且理解良好的工具来构建应用。

In late 2024, Claude 3.5 Sonnet reached 49% on SWE-bench Verified—then state of the art—with only a bash tool and a text editor tool for viewing, creating, and editing files. Claude Code is grounded in these same tools. Bash wasn’t designed for building agents, but it's a tool that Claude knows how to use and gets better at using over time. 2024 年底，Claude 3.5 Sonnet 在 SWE-bench Verified 上达到了 49%——当时的最优水平——仅使用了 bash 工具和一个用于查看、创建和编辑文件的文本编辑器工具。Claude Code 正是基于这些相同的工具。Bash 并非为构建代理而设计，但它是 Claude 知道如何使用且会随时间推移越来越擅长的工具。

We've seen Claude compose these general tools into patterns that solve different problems. For instance, Agent Skills, programmatic tool calling, and the memory tool are all built from the bash and text editor tools.我们观察到 Claude 将这些通用工具组合成解决不同问题的模式。例如，Agent Skills、程序化工具调用和记忆工具都是基于 bash 和文本编辑器工具构建的。

2. Ask ‘what can I stop doing?’2. 询问“我可以停止做什么？”

Agent harnesses encode assumptions about what Claude can’t do on its own. As Claude gets more capable, those assumptions should be tested.代理框架编码了对 Claude 自身无法完成之事的假设。随着 Claude 能力的提升，这些假设应该被重新检验。

Let Claude orchestrate its own actions 让 Claude 自主编排其行动

A common assumption is that every tool result should flow back through Claude’s context window to inform the next action. Processing tool results in tokens can be slow, costly, and unnecessary if it only needs to be passed to the next tool or if Claude only cares about a small slice of the output. 一个常见的假设是，每个工具的结果都应流回 Claude 的上下文窗口，以指导下一步行动。将工具结果处理为 token 可能既慢又昂贵，而且如果结果只需传递给下一个工具，或者 Claude 只关心输出的一小部分，那么这样做是不必要的。

Consider reading a large table to reason about a single column: the whole table lands in context and Claude pays the token cost for every row it doesn't need. It’s possible to tackle this in tool design, using hard-coded filters. But this does not address the fact that the agent harness is making an orchestration decision that Claude is better positioned to make.考虑读取一个大表格以分析某一列：整个表格进入上下文，Claude 为每一行不需要的数据支付 token 成本。这可以通过工具设计来解决，例如使用硬编码过滤器。但这并未解决代理框架正在做出一个 Claude 更适合做出的编排决策这一事实。

Giving Claude a code execution tool (e.g., bash tool or language-specific REPL) addresses this: it allows Claude to write code to express tool calls and the logic between them. Rather than the harness deciding that every tool call result is processed as tokens, Claude decides what results to pass through, filter, or pipe into the next call without touching the context window. Only the output of code execution reaches Claude’s context window.给 Claude 一个代码执行工具（例如 bash 工具或特定语言的 REPL）可以解决这个问题：它允许 Claude 编写代码来表达工具调用及其之间的逻辑。框架不再决定每个工具调用结果都作为 token 处理，而是由 Claude 决定哪些结果需要传递、过滤或通过管道传递给下一个调用，而无需触及上下文窗口。只有代码执行的输出才会到达 Claude 的上下文窗口。

The orchestration decision moves from the harness to the model. Since code is a general way for Claude to orchestrate actions, a strong coding model is also a strong general agent. Claude shows strong performance on non-coding evals using this pattern: on BrowseComp, a benchmark that tests the ability of agents to browse the web, giving Opus 4.6 the ability to filter its own tool outputs brought accuracy from 45.3% to 61.6%. 编排决策从框架转移到了模型。由于代码是 Claude 编排行动的一种通用方式，一个强大的编码模型也是一个强大的通用代理。Claude 在使用这种模式的非编码评估中表现出色：在 BrowseComp（一个测试代理浏览网页能力的基准测试）上，赋予 Opus 4.6 过滤自身工具输出的能力后，准确率从 45.3% 提升到了 61.6%。

Let Claude manage its own context 让 Claude 管理自己的上下文

Task-specific context steers Claude’s use of general tools like bash and the text editor tool. A common assumption is that system prompts should be hand-crafted with task-specific instructions. The problem is that pre-loading prompts with instructions does not scale across many tasks: every token added depletes Claude’s attention budget and it is wasteful to pre-load context with rarely used instructions.任务特定的上下文引导 Claude 使用 bash 和文本编辑器等通用工具。一个常见的假设是，系统提示应手工制作并包含任务特定的指令。问题在于，预加载指令的提示无法跨多个任务扩展：每增加一个 token 都会消耗 Claude 的注意力预算，而且预加载很少使用的指令是浪费的。

Giving Claude the ability to access skills addresses this: the YAML frontmatter of each skill is a short description pre-loaded into the context window, providing an overview of the skill contents. The full skill can be progressively disclosed by Claude calling a read file tool if a task calls for it.给 Claude 访问技能的能力可以解决这个问题：每个技能的 YAML 前置元数据是一个简短描述，预加载到上下文窗口中，提供技能内容的概览。如果任务需要，Claude 可以通过调用读取文件工具逐步披露完整的技能内容。

While skills give Claude the freedom to assemble its own context window, context editing is the inverse, providing a way to selectively remove context that’s become stale or irrelevant, such as old tool results or thinking blocks. 技能赋予 Claude 自由组合自身上下文窗口的能力，而上下文编辑则是其反面，提供了一种选择性移除已过时或不相关上下文的方法，例如旧的工具结果或思考块。

With subagents, Claude is getting better at knowing when to fork into a fresh context window to isolate work on a specific task. With Opus 4.6, the ability to spawn subagents improved results on BrowseComp by 2.8% over the best single-agent runs. 通过子代理，Claude 越来越擅长在需要时分支到一个新的上下文窗口，以隔离特定任务的工作。对于 Opus 4.6，生成子代理的能力使 BrowseComp 的结果比最佳单代理运行提升了 2.8%。

Let Claude persist its own context 让 Claude 持久化自己的上下文

Long-running agents can exceed the limit of a single context window. A common assumption is that memory systems should rely on retrieval infrastructure around the model. Much of our work has focused on giving Claude simple ways to choose for itself what content to persist.长时间运行的代理可能会超出单个上下文窗口的限制。一个常见的假设是，记忆系统应依赖模型周围的检索基础设施。我们的许多工作都集中在给 Claude 提供简单的方式，让它自己选择要持久化的内容。

For example, compaction lets Claude summarize its past context in order to maintain continuity on long-horizon tasks. Over several releases, Claude has gotten better at choosing what to remember. On BrowseComp, for example, an agentic search task, Sonnet 4.5 stayed flat at 43% regardless of the compaction budget we gave it. Yet Opus 4.5 scaled to 68% and Opus 4.6 reached 84% with the same setup. 例如，压缩（compaction）允许 Claude 总结其过去的上下文，以在长周期任务中保持连续性。经过几个版本的发布，Claude 在选择记住什么方面变得更好。例如，在 BrowseComp（一个代理搜索任务）上，无论我们给 Sonnet 4.5 多少压缩预算，其表现都持平在 43%。然而，Opus 4.5 在相同设置下提升到了 68%，而 Opus 4.6 达到了 84%。

A memory folder is another approach, allowing Claude to write context to files and later read them as needed. We’ve seen Claude use this for agentic search. On BrowseComp-Plus, giving Sonnet 4.5 a memory folder lifted accuracy from 60.4% to 67.2%.记忆文件夹是另一种方法，允许 Claude 将上下文写入文件，并在需要时读取。我们观察到 Claude 将其用于代理搜索。在 BrowseComp-Plus 上，给 Sonnet 4.5 一个记忆文件夹后，准确率从 60.4% 提升到了 67.2%。

Long-horizon games, such as Pokémon, are an example of Claude’s improved ability to use a memory folder. Sonnet 3.5 treated memory as a transcript, writing down what non-player characters (NPCs) said rather than what mattered. After 14,000 steps it had 31 files—including two near-duplicates about caterpillar Pokémon—and was still in the second town:长周期游戏，例如《宝可梦》，是 Claude 使用记忆文件夹能力提升的一个例子。Sonnet 3.5 将记忆视为转录本，记录非玩家角色（NPC）说了什么，而不是什么重要。在 14,000 步后，它有了 31 个文件——包括两个关于毛毛虫宝可梦的近乎重复的文件——并且仍然在第二个城镇：

caterpie_weedle_info:
- Caterpie and Weedle are both caterpillar Pokémon.
- Caterpie is a caterpillar Pokémon that does not have poison.
- Weedle is a caterpillar Pokémon that does have 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.

Later models wrote tactical notes. Opus 4.6, at the same step count, had 10 files organized into directories, three gym badges, and a learnings file distilled from its own failures:后来的模型则写下了战术笔记。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. Set boundaries carefully3. 谨慎设置边界

Agent harnesses provide structure around Claude to enforce UX, cost, or security.代理框架为 Claude 提供结构，以强制执行用户体验、成本或安全性。

Design context to maximize cache hits设计上下文以最大化缓存命中率

The Messages API is stateless. Claude cannot see the conversation history of prior turns. This means that the agent harness needs to package new context alongside all past actions, tool descriptions, and instructions for Claude at each turn.Messages API 是无状态的。Claude 无法看到之前轮次的对话历史。这意味着代理框架需要在每一轮将新上下文与所有过去的行动、工具描述和指令打包在一起提供给 Claude。

Prompts can be cached based on set breakpoints. In other words, the Claude API writes context up until a breakpoint to the cache and checks whether the context matches any prior cache entries. 提示可以根据设置的断点进行缓存。换句话说，Claude API 将上下文写入缓存直到一个断点，并检查上下文是否与任何先前的缓存条目匹配。

Since cached tokens are 10% the cost of base input tokens, here are a few principles in the agent harness help maximize cache hits: 由于缓存 token 的成本仅为基础输入 token 的 10%，以下代理框架中的一些原则有助于最大化缓存命中率：

Use declarative tools for UX, observability, or security boundaries 使用声明式工具处理用户体验、可观测性或安全边界

Claude doesn't necessarily know an application's security boundary or UX surface. Claude emits tool calls, which are handled by the harness. A bash tool gives Claude broad programmatic leverage to perform actions, but it gives the harness only a command string—the same shape for every action. Promoting actions to dedicated tools gives the harness an action-specific hook with typed arguments it can intercept, gate, render, or audit.Claude 不一定了解应用的安全边界或用户体验界面。Claude 发出工具调用，由框架处理。bash 工具为 Claude 提供了广泛的程序化杠杆来执行操作，但它只给框架一个命令字符串——所有操作都是相同的形式。将操作提升为专用工具，可以为框架提供一个带有类型参数的操作特定钩子，它可以拦截、门控、渲染或审计这些参数。

Actions that require a security boundary are natural candidates for dedicated tools. Reversibility is often a good criterion, and hard-to-reverse actions such as external API calls can be gated by user confirmation. Write tools like edit can include a staleness check so Claude doesn't overwrite a file that changed since it was last read.需要安全边界的操作是专用工具的自然候选。可逆性通常是一个好的标准，而难以逆转的操作（如外部 API 调用）可以通过用户确认来门控。写入工具（如编辑）可以包含一个过时检查，这样 Claude 就不会覆盖自上次读取以来已更改的文件。

Tools are also useful when an action needs to be presented to a user. For example, they can be rendered as a modal to display a question clearly to the user, give the user multiple options, or block the agent loop until a user provides feedback.当操作需要呈现给用户时，工具也很有用。例如，它们可以渲染为模态框，以清晰地向用户显示问题，给用户多个选项，或阻止代理循环直到用户提供反馈。

Finally, tools are useful for observability. When the action is a typed tool, the harness gets structured arguments it can log, trace, and replay.最后，工具对于可观测性很有用。当操作是一个类型化工具时，框架会获得结构化的参数，可以记录、追踪和重放。

The decision to promote actions to tools should be continually re-evaluated. For example, Claude Code's auto-mode (in research mode at the time of publication) provides a security boundary around the bash tool: it has a second Claude read the command string and judge whether it's safe. This pattern can limit the need for dedicated tools, and should only be used for tasks where users trust the general direction. Dedicated tools can still earn their place for certain high-stakes actions. 将操作提升为工具的决定应持续重新评估。例如，Claude Code 的自动模式（在发布时处于研究模式）为 bash 工具提供了一个安全边界：它让另一个 Claude 读取命令字符串并判断其是否安全。这种模式可以减少对专用工具的需求，并且只应用于用户信任总体方向的任务。对于某些高风险操作，专用工具仍然有其价值。

Looking forward展望未来

The frontier of Claude’s intelligence is always changing. Assumptions about what Claude can’t do need to be re-tested with each step change in its capability. Claude 智能的前沿总是在变化。关于 Claude 不能做什么的假设需要随着其能力的每一步变化而重新检验。

We see this pattern repeat itself. In an agent we built for long-horizon tasks, Sonnet 4.5 would wrap up prematurely as it sensed the context limit approaching. We added resets to clear the context window in order to address this "context anxiety." With Opus 4.5, the behavior was gone. The context resets we built to compensate had become dead weight in the agent harness.我们看到这种模式反复出现。在我们为长周期任务构建的一个代理中，Sonnet 4.5 会在感知到上下文限制接近时过早结束。我们添加了重置来清除上下文窗口，以解决这种“上下文焦虑”。到了 Opus 4.5，这种行为消失了。我们为补偿而构建的上下文重置变成了代理框架中的死重。

Removing this dead weight is important because it can bottleneck Claude’s performance. Over time, the structure or boundaries in our applications should be pruned based the question: what can I stop doing?移除这些死重很重要，因为它们可能成为 Claude 性能的瓶颈。随着时间的推移，我们应用中的结构或边界应该根据以下问题来修剪：我可以停止做什么？

To use all tools and patterns discussed here, check out our claude-api skill.要使用这里讨论的所有工具和模式，请查看我们的 claude-api 技能。

Acknowledgements致谢

Written by Lance Martin, member of technical staff on the Claude Platform team. Special thanks to Thariq Shihipar, Barry Zhang, Mike Lambert, David Hershey, and Daliang Li for helpful discussion on the topics covered. Thanks to Lydia Hallie, Lexi Ross, Katelyn Lesse, Andy Schumeister, Rebecca Hiscott, Jake Eaton, Pedram Navid, and Molly Vorwerck for their editorial review and feedback. 本文由 Claude 平台团队的技术成员 Lance Martin 撰写。特别感谢 Thariq Shihipar、Barry Zhang、Mike Lambert、David Hershey 和 Daliang Li 对相关主题的有益讨论。感谢 Lydia Hallie、Lexi Ross、Katelyn Lesse、Andy Schumeister、Rebecca Hiscott、Jake Eaton、Pedram Navid 和 Molly Vorwerck 的编辑审阅和反馈。