Anthropic 给 Claude Code 设计工具的最佳实践
公众号名称：方圆AI分享
作者名称：方圆yo
发布时间：2026-04-23 20:26
Anthropic 官方博客发了一篇文章 Seeing like an agent: how we design tools in Claude Code(像 Agent 一样思考，如何设计 Claude Code 的工具)[1]，作者 Thariq Shihipar 是 Anthropic 的技术人员，专门负责 Claude Code 的开发。
文章详细讲述了他们在构建 Claude Code 过程中，如何设计和迭代 AI Agent 工具的实践经验，包括走过的弯路和最终的解法，对于任何在做 Agent 开发的人来说都有很强的参考价值。
工具设计的核心思维：学会像 Agent 一样思考
构建一个 Agent harness，最难的部分之一就是设计它的工具。Claude 完全通过 tool calling 来执行操作，但工具可以有很多种构建方式，比如 bash、skills、代码执行等等。
那到底应该怎么设计工具？是给 Agent 一个通用的工具（比如 bash），还是给它五十个专用工具，每个对应一个场景？
文章里用了一个很形象的类比：想象你面前有一道很难的数学题，你希望用什么工具来解决？这取决于你自身的能力。
纸和笔是最基本的，但你只能做手算。计算器更好，但你得知道怎么用那些高级功能。最快最强的选择是电脑，但前提是你会写代码来执行计算。
这个类比揭示了工具设计的一个核心原则：你需要给 Agent 配备与它能力匹配的工具。
但你怎么知道它的能力边界在哪里？答案是持续观察、阅读它的输出、反复实验。用 Anthropic 的话说，就是学会「像 Agent 一样看世界」。
如果你正在构建自己的 Agent，你会面对和 Anthropic 同样的问题：什么时候该加一个工具？什么时候该移除一个工具？怎么判断两者的边界？
AskUserQuestion 工具的三次迭代
为了提升 Claude 向用户提问的能力（也就是所谓的 elicitation），Anthropic 团队经历了三次尝试，过程很有意思。
第一次尝试是在已有的 ExitPlanTool 上做修改，给它加一个参数，让它在输出计划的同时带上一组问题。
这是最省事的做法，但结果发现 Claude 被搞混了。因为你同时要求它做两件事：输出计划，以及对计划提出问题。
如果用户的回答和计划本身有冲突怎么办？Claude 是不是需要调用两次 ExitPlanTool？这条路很快就被否定了。
第二次尝试是修改输出格式。他们让 Claude 按照一种特殊的 Markdown 格式来输出问题，比如用带括号的备选项列出问题，然后在前端解析并渲染成 UI。
Claude 大多数时候能按照这个格式输出，但做不到稳定。它会在后面追加多余的句子，丢掉选项，或者干脆放弃整个格式。这条路也走不通。
第三次尝试终于成功了，他们创建了一个独立的 AskUserQuestion 工具。
Claude 可以在任何时候调用这个工具，但在 plan mode 下会被特别引导去调用它。当工具被触发时，前端会弹出一个模态框展示问题，并阻塞 Agent 的循环直到用户回答。
这个方案之所以成功，有几个关键点。首先，它让 Claude 产出结构化输出 变得可靠了。其次，它确保 Claude 会给用户提供多个选项。
再者，用户可以在不同场景下灵活组合使用这个工具，比如在 Agent SDK 中调用，或者在 skills 里引用。
但最重要的一点是，Claude 看起来很愿意调用这个工具，而且输出效果很好。毕竟，哪怕设计再精良的工具，如果模型不理解怎么调用它，一切也是白搭。
文章也坦诚地说，这不一定是 elicitation 的最终形态。随着 Claude 能力的增强，服务于它的工具也必须跟着演进。
从 TodoWrite 到 Task：工具必须跟着模型能力迭代
这一段讲的是另一个很有代表性的工具演进故事。
Claude Code 刚上线时，团队意识到模型需要一个待办事项列表来保持工作节奏。待办可以在任务开始时写好，然后边做边勾选。
为此他们设计了 TodoWrite 工具，让 Claude 可以创建和更新待办，同时展示给用户看。
但即便有了待办列表，Claude 还是经常忘记自己该做什么。为了适应这个问题，他们每隔 5 轮对话就插入一个系统提醒，提醒 Claude 当前的目标是什么。
随着模型越来越强，待办列表反而变成了一种限制。系统提醒让 Claude 觉得它必须严格遵循现有列表，而不是在发现新情况时灵活调整方向。
到了 Opus 4.5 这一代模型，子 Agent 的使用能力有了大幅提升，但多个子 Agent 之间怎么共享和协调一个待办列表？这又成了新的问题。
于是他们用 Task 工具 替换了 TodoWrite。
两者的区别在于，待办列表的核心是让模型不跑偏，而 Task 的核心是让多个 Agent 之间能够通信和协作。Task 可以包含依赖关系，可以在子 Agent 之间共享更新，模型还可以修改和删除任务。
这个案例揭示了一个重要的规律：随着模型能力的提升，曾经必要的工具可能会变成瓶颈。
持续重新审视之前的假设非常重要。这也是为什么 Anthropic 建议只支持少数几个能力水平相近的模型，这样工具设计的复杂度才可控。
搜索接口的演进：从 RAG 到让 Agent 自己找上下文
Anthropic 认为，他们构建的最重要的工具是那些让 Claude 能自己寻找上下文的工具。
Claude Code 刚在内部发布时，用的是 RAG 方案。一个向量数据库会预先索引整个代码库，在每次回复之前把相关代码片段检索出来交给 Claude。
RAG 确实强大且快速，但它需要索引和配置，而且在不同环境下容易出问题。最关键的是，这种方式下 Claude 是被动地接收上下文，而不是主动地寻找上下文。
后来他们换了一种思路：既然 Claude 可以在网上搜索，为什么不能让它搜索代码库呢？于是他们给 Claude 一个 Grep 工具，让它自己搜索文件、构建上下文。
随着 Claude 越来越聪明，只要给它合适的工具，它构建上下文的能力也越来越强。
当 Anthropic 推出 Agent Skills 之后，他们把这种理念正式化了，叫做 progressive disclosure（渐进式发现）。Agent 可以通过探索来逐步发现相关的上下文。
具体来说，Claude 可以读取 skill 文件，而这些 skill 文件又可以引用其他文件，模型可以递归地去读取。
实际上，skill 的一个常见用法就是给 Claude 增加更多的搜索能力，比如告诉它怎么使用某个 API 或查询某个数据库。
经过一年的演进，Claude 从基本不会自己构建上下文，发展到可以进行多层嵌套搜索，在好几层文件之间穿梭来找到它需要的精确上下文。
Progressive Disclosure：不加工具也能扩展能力
Claude Code 目前有大约 20 个工具，团队经常审视是否真的每个都需要。添加新工具的门槛很高，因为每多一个工具就意味着模型多一个需要考虑的选项。
一个具体的例子是，Claude 对 Claude Code 自身的使用方法了解不够。如果你问它怎么添加 MCP，或者某个 slash command 是干什么的，它答不上来。
一种方案是把所有这些信息都塞进 system prompt 里。但考虑到用户很少问这类问题，这样做会增加上下文噪音，干扰 Claude Code 的核心工作：写代码。
他们尝试了 progressive disclosure 的方案：给 Claude 一个文档链接，让它在需要时自己去加载和搜索。
这个方法有效，但有个问题。Claude 会把大段大段的文档拉进上下文里，只为了回答一个用户本来一句话就能得到答案的问题。
最终的解决方案是构建了一个叫 Claude Code Guide 的子 Agent。
当用户问关于 Claude Code 本身的问题时，主 Agent 会调用这个子 Agent。子 Agent 在自己独立的上下文中执行文档搜索，按照详细的指令去检索和提取信息，最后只把答案返回给主 Agent。这样主 Agent 的上下文就保持了干净。
虽然这个方案还不完美（Claude 在被问到如何配置自身时偶尔还是会困惑），但他们成功地扩展了 Claude 的行动空间，而没有增加新的工具。这就是 progressive disclosure 的价值所在。
工具设计是一门手艺
文章最后总结说，为模型设计工具，与其说是科学，不如说更接近手艺。它高度依赖于你使用的模型、Agent 的目标，以及它运行的环境。
Anthropic 给出的建议很简洁：频繁实验，认真阅读输出，勇于尝试新东西。最重要的是，试着用 Agent 的眼光来看问题。
从这篇文章里可以看到几个值得反复琢磨的点。
第一，工具设计要匹配模型能力。给太强的工具模型不会用，给太弱的工具模型会受限。
第二，工具需要持续迭代。模型能力在进步，以前好用的工具可能变成包袱。TodoWrite 到 Task 的演变就是典型例子。
第三，不是所有问题都需要新工具来解决。Progressive disclosure 提供了一种不增加工具数量就能扩展能力的思路。
第四，结构化比自由文本更可靠。AskUserQuestion 的三次迭代证明了这一点。让模型输出特定格式的文本很脆弱，不如给它一个结构化的工具调用接口。
第五，让 Agent 主动寻找上下文，比被动喂给它上下文要好得多。从 RAG 到 Grep 再到 skill 的渐进式发现，这条路径的演进方向非常清晰。
这些经验不仅适用于 Claude Code，对于任何正在构建 AI Agent 的团队来说，都是非常实在的参考。
(完)
我是方圆，持续分享AI干货，下期再见～
往期推********荐
我给 Claude Code 源码加了宠物成长系统，人人都能拥有金色传说
五位大佬聊了两小时，终于把 Harness Engineering 讲明白了
添加微信，加入AI交流群，获取AI干货分享👇
如果这篇文章对你有帮助，欢迎顺手点个赞、点个在看，再转发给更多需要的人
也欢迎给公众号加个星标⭐，这样以后更新就能第一时间看到
你的每一次支持，都是我持续输出的动力，谢谢你～
引用链接
[1] Seeing like an agent: how we design tools in Claude Code(像 Agent 一样思考，如何设计 Claude Code 的工具): https://claude.com/blog/seeing-like-an-agent
原创 方圆yo 方圆AI分享