claude.dev 解读
AgentsThariq Shihipar2026-04-10约 7 分钟阅读原文 ↗

Seeing like an agent: how we design tools in Claude Code

工具要贴合模型当下能力,能力一变就该删改;最值钱的是让模型自己找上下文

主张
6
审视
5
遗漏
2
  1. 01作者认为,agent 工具设计的核心是让工具形态贴合模型当前的能力。判断能力的办法只有一个:读它的输出,反复做实验,也就是文中说的「像 agent 一样看」。
  2. 02三个案例给出了三条规律。需要结构化交互时,应该交给专门的工具来承载,靠格式指令不稳定(AskUserQuestion)。模型能力提升后,原先帮它不跑偏的工具会反过来束缚它(TodoWrite 换成 Task)。让模型自己检索上下文,比由 harness 预先喂给它更好(RAG 换成 Grep)。
  3. 03新增工具的门槛很高,因为每多一个工具,模型就多一个要权衡的选项。所以 Claude Code 优先用渐进披露和子代理来扩展能力范围,同时保持主上下文干净。
怎么读这篇
作者主张 · Thariq Shihipar我们的审视
01

能力边界只能靠读输出摸清

工具要按模型能力来设计。能力边界只能靠观察输出、做实验去摸清,没法事先推导出来。

机制拆解

作者拿解数学题打比方:纸、计算器、电脑三种工具,哪个最好,取决于用的人会不会用。同样,给 agent 的工具也要和它的技能匹配:工具太原始,模型被手工操作拖慢;工具太强但模型不会用,也白搭。所以工具设计是围绕「这个模型」的经验工程,而不是通用的接口设计。

“You want to give it tools that are shaped to its own abilities.” ¶6

厂商视角

全文只有定性判断(如 Claude seemed to like calling this tool、outputs worked well),没有成功率、轮次、token 成本等量化证据。作者是 Anthropic 员工,文章本身也在推广 Claude Code,结尾还有产品引导。

自己验证在自己的 Claude Code 会话里,对同一个需求澄清任务分别要求「用纯文本提问」和「用 AskUserQuestion 提问」,记录往返轮次、用户答题时间、选项遗漏次数,各做若干次比较。
02

结构化提问交给专用工具

需要结构化交互(例如向用户提问并给出选项)时,专门的工具比格式指令更可靠。

机制拆解

作者试过三种做法。第一种是在 ExitPlanTool 上加问题参数:模型要同时给出计划又对这个计划提问,语义自相矛盾。第二种是规定 markdown 输出格式再由程序解析:模型大多数时候能遵守,但会多写句子、漏掉选项,甚至整个放弃格式。第三种是独立的 AskUserQuestion 工具:模型随时可以调用,调用后弹出模态框,并阻塞 agent 循环直到用户作答。工具调用自带 schema 约束,还能在 Agent SDK 和 skills 里复用。作者特别强调,模型「愿意调用」这个工具,本身就是可用性的前提。

“Claude could usually produce this format, but not reliably.” ¶12

可复现性

「格式指令不可靠,专用工具更可靠」和「Grep 自检索优于 RAG 预注入」这两个结论可以低成本自己复现。

自己验证用真实模型(agent-harness-lab 的 fakeProvider 不算)跑同一组结构化提问任务,分别用 markdown 约定和工具 schema 两种方式,统计解析失败率。再在一个自有仓库上准备一组定位问题,对比 RAG 片段注入和只给 Grep 两种方式的命中率与 token 消耗。
03

能力升级后脚手架变枷锁

模型能力提升后,旧工具可能从脚手架变成枷锁,要持续回头检查工具集。

机制拆解

早期模型容易忘记目标,所以设计了 TodoWrite,并每五轮插一次系统提醒。模型变强后,这些提醒反而让它以为必须死守清单,发现需要改道时也不敢改。另外,Opus 4.5 更擅长用子代理,而多个子代理没法协调同一份 todo 清单。于是 TodoWrite 被换成 Task:Task 可以表达依赖关系,可以在子代理之间共享更新,模型也能修改和删除。作者由此建议,产品只支持少数几个能力剖面相近的模型。

“the tools that your models once needed might now be constraining them” ¶21

遗漏

「只支持少数能力剖面相近的模型」对产品方合理,但对第三方开发者等于默认模型锁定;文章也没有讨论多模型或降级场景下工具集该怎么处理。

自己验证在配置了降级模型的定时任务中(例如 AIM_MODEL_FALLBACK),人为触发降级,同输入对比主模型和降级模型的产物质量与格式遵守情况。
04

让模型自己找上下文

最关键的工具是让模型自己找上下文的工具。按需检索优于预先注入。

机制拆解

内部早期版本用 RAG:先用向量库建索引,每次回复前由 harness 检索片段喂给模型。这种做法要建索引、要配置,在不同环境下也容易出问题;更重要的是,上下文是模型被动收到的。换成 Grep 之后,模型自己决定搜什么。再加上 skills 文件可以递归引用其他文件,模型在一年里从基本不会自建上下文,进步到能穿过多层文件做嵌套检索。

“Claude was given this context instead of finding the context itself.” ¶23

遗漏

文章没有讨论自检索的代价。Grep 多轮搜索带来的延迟、token 成本,子代理的额外调用费用,都没有和 RAG 对比。也没有说明删除或替换工具之前用什么评测判断「旧工具已经成为束缚」,只说要多实验。

自己验证在自己的任务上同时记录墙钟时间和 token 用量,比较单次 RAG 注入和多轮 Grep 的总成本;查 Claude Code 的变更说明,看 TodoWrite 换成 Task 时是否公布过回归数据。
05

加工具门槛高,先用渐进披露

新增工具的门槛很高。默认先用渐进披露来扩展能力,而不是加工具,也不是往系统提示里塞内容。

机制拆解

每多一个工具,模型每一步都要多权衡一个选项。把低频知识(比如 Claude Code 怎么用)写进系统提示,会造成 context rot,干扰写代码这个主任务。渐进披露的做法是只给模型一个入口(文档链接或 skill 文件),等真正需要时再由模型自己加载。Claude Code 目前约有二十个工具,团队会经常复查这些工具是否都有必要。

“The bar to add a new tool is high” ¶30

数字口径

「约二十个工具」「每五轮提醒」「一年内从不会自建上下文到能多层嵌套检索」都是描述性说法,没有基线、没有测量口径。「Opus 4.5 更擅长用子代理」也没有给出评测依据。

自己验证在本机会话中导出当前实际暴露的工具清单和描述长度,自己核对工具数量;子代理能力的说法要找 Anthropic 官方模型卡或第三方评测对照,本文不能当证据。
06

子代理隔离检索保主上下文

渐进披露也有副作用,大块文档会被拉进主上下文。用子代理隔离检索过程,可以只把答案交回主代理。

机制拆解

给模型一个文档链接确实有效,但模型会把大段文档拉进主上下文,只为找一句话的答案。Claude Code Guide 子代理在自己的上下文里按详细指令搜索、抽取,只返回答案,主上下文保持干净。这样不新增工具也扩展了能力范围。作者也承认这不完美:问 Claude 怎么配置它自己时,它仍然会混淆。

“The main agent's context stays clean.” ¶34

这一点暂无对应的审视。

01

机制聚焦

RAG 预注入 vs Grep 自检索

早期 Claude Code 用 RAG 把片段喂给模型,后来改为给 Grep 让模型自己找上下文。

RAG 预注入
Grep 自检索
上下文从哪来
harness 检索片段后交给模型
模型自己搜索文件、构建上下文
前期准备
需向量库预索引代码库并配置
给模型一个 Grep 工具
长处与短板
强大且快,但跨环境容易脆弱
模型越聪明,越会自建上下文
可延伸性
模型只能被动接收给定内容
可延伸到渐进披露与多层嵌套检索
依据原文 ¶23 ↗
02

核心观点

01

能力边界只能靠读输出摸清

工具要按模型能力来设计。能力边界只能靠观察输出、做实验去摸清,没法事先推导出来。

机制拆解

作者拿解数学题打比方:纸、计算器、电脑三种工具,哪个最好,取决于用的人会不会用。同样,给 agent 的工具也要和它的技能匹配:工具太原始,模型被手工操作拖慢;工具太强但模型不会用,也白搭。所以工具设计是围绕「这个模型」的经验工程,而不是通用的接口设计。

You want to give it tools that are shaped to its own abilities.¶6 ↗

02

结构化提问交给专用工具

需要结构化交互(例如向用户提问并给出选项)时,专门的工具比格式指令更可靠。

机制拆解

作者试过三种做法。第一种是在 ExitPlanTool 上加问题参数:模型要同时给出计划又对这个计划提问,语义自相矛盾。第二种是规定 markdown 输出格式再由程序解析:模型大多数时候能遵守,但会多写句子、漏掉选项,甚至整个放弃格式。第三种是独立的 AskUserQuestion 工具:模型随时可以调用,调用后弹出模态框,并阻塞 agent 循环直到用户作答。工具调用自带 schema 约束,还能在 Agent SDK 和 skills 里复用。作者特别强调,模型「愿意调用」这个工具,本身就是可用性的前提。

Claude could usually produce this format, but not reliably.¶12 ↗

03

能力升级后脚手架变枷锁

模型能力提升后,旧工具可能从脚手架变成枷锁,要持续回头检查工具集。

机制拆解

早期模型容易忘记目标,所以设计了 TodoWrite,并每五轮插一次系统提醒。模型变强后,这些提醒反而让它以为必须死守清单,发现需要改道时也不敢改。另外,Opus 4.5 更擅长用子代理,而多个子代理没法协调同一份 todo 清单。于是 TodoWrite 被换成 Task:Task 可以表达依赖关系,可以在子代理之间共享更新,模型也能修改和删除。作者由此建议,产品只支持少数几个能力剖面相近的模型。

the tools that your models once needed might now be constraining them¶21 ↗

04

让模型自己找上下文

最关键的工具是让模型自己找上下文的工具。按需检索优于预先注入。

机制拆解

内部早期版本用 RAG:先用向量库建索引,每次回复前由 harness 检索片段喂给模型。这种做法要建索引、要配置,在不同环境下也容易出问题;更重要的是,上下文是模型被动收到的。换成 Grep 之后,模型自己决定搜什么。再加上 skills 文件可以递归引用其他文件,模型在一年里从基本不会自建上下文,进步到能穿过多层文件做嵌套检索。

Claude was given this context instead of finding the context itself.¶23 ↗

05

加工具门槛高,先用渐进披露

新增工具的门槛很高。默认先用渐进披露来扩展能力,而不是加工具,也不是往系统提示里塞内容。

机制拆解

每多一个工具,模型每一步都要多权衡一个选项。把低频知识(比如 Claude Code 怎么用)写进系统提示,会造成 context rot,干扰写代码这个主任务。渐进披露的做法是只给模型一个入口(文档链接或 skill 文件),等真正需要时再由模型自己加载。Claude Code 目前约有二十个工具,团队会经常复查这些工具是否都有必要。

The bar to add a new tool is high¶30 ↗

06

子代理隔离检索保主上下文

渐进披露也有副作用,大块文档会被拉进主上下文。用子代理隔离检索过程,可以只把答案交回主代理。

机制拆解

给模型一个文档链接确实有效,但模型会把大段文档拉进主上下文,只为找一句话的答案。Claude Code Guide 子代理在自己的上下文里按详细指令搜索、抽取,只返回答案,主上下文保持干净。这样不新增工具也扩展了能力范围。作者也承认这不完美:问 Claude 怎么配置它自己时,它仍然会混淆。

The main agent's context stays clean.¶34 ↗

03

批判性审视

厂商视角

全文只有定性判断(如 Claude seemed to like calling this tool、outputs worked well),没有成功率、轮次、token 成本等量化证据。作者是 Anthropic 员工,文章本身也在推广 Claude Code,结尾还有产品引导。

自己验证在自己的 Claude Code 会话里,对同一个需求澄清任务分别要求「用纯文本提问」和「用 AskUserQuestion 提问」,记录往返轮次、用户答题时间、选项遗漏次数,各做若干次比较。
数字口径

「约二十个工具」「每五轮提醒」「一年内从不会自建上下文到能多层嵌套检索」都是描述性说法,没有基线、没有测量口径。「Opus 4.5 更擅长用子代理」也没有给出评测依据。

自己验证在本机会话中导出当前实际暴露的工具清单和描述长度,自己核对工具数量;子代理能力的说法要找 Anthropic 官方模型卡或第三方评测对照,本文不能当证据。
可复现性

「格式指令不可靠,专用工具更可靠」和「Grep 自检索优于 RAG 预注入」这两个结论可以低成本自己复现。

自己验证用真实模型(agent-harness-lab 的 fakeProvider 不算)跑同一组结构化提问任务,分别用 markdown 约定和工具 schema 两种方式,统计解析失败率。再在一个自有仓库上准备一组定位问题,对比 RAG 片段注入和只给 Grep 两种方式的命中率与 token 消耗。
遗漏

文章没有讨论自检索的代价。Grep 多轮搜索带来的延迟、token 成本,子代理的额外调用费用,都没有和 RAG 对比。也没有说明删除或替换工具之前用什么评测判断「旧工具已经成为束缚」,只说要多实验。

自己验证在自己的任务上同时记录墙钟时间和 token 用量,比较单次 RAG 注入和多轮 Grep 的总成本;查 Claude Code 的变更说明,看 TodoWrite 换成 Task 时是否公布过回归数据。
遗漏

「只支持少数能力剖面相近的模型」对产品方合理,但对第三方开发者等于默认模型锁定;文章也没有讨论多模型或降级场景下工具集该怎么处理。

自己验证在配置了降级模型的定时任务中(例如 AIM_MODEL_FALLBACK),人为触发降级,同输入对比主模型和降级模型的产物质量与格式遵守情况。
本篇未覆盖(2)
风格