Claude Code 的工具是怎么设计的：什么时候加工具，什么时候删工具

这是“Claude Code 开发系列”的第一篇。这个系列按发布的先后顺序，整理 Claude Code 团队在 claude.dev 上写的工程文章。

这一篇解决的问题是：做一个智能体时，该给模型哪些工具？ 给一个万能的工具（比如 bash），还是给五十个专门的工具？原文作者是 Claude Code 团队的 Thariq Shihipar，他用 Claude Code 自己走过的几段弯路来回答。

对只是使用 Claude Code 的人，这篇也有用：它解释了 Claude Code 为什么会弹出选择题来问你、为什么没有代码索引、为什么它的工具一共只有二十个左右。

一个判断框架：工具要配得上模型的能力

作者打了个比方。给你一道很难的数学题，你想要什么工具，取决于你自己会什么：

• 纸笔是最低限度，但只能手算；
• 计算器更好，但你得会用它的高级功能；
• 电脑最快最强，但你得会写代码。

给智能体的工具也是这样：要和它自身的能力相称。 而模型的能力是什么样的，没有捷径，只能靠观察：读它的输出，做实验。作者把这叫作“像智能体一样去看”。

下面是四个具体的例子。

例子一：让 Claude 向你提问，试了三次

目标是让 Claude 更会提问。Claude 本来可以直接用文字问，但团队发现，用户回答这些问题花的时间比应该的多。

尝试	做法	结果
第一次	给“退出计划模式”的工具加一个参数，让它在交计划的同时带上一组问题	Claude 被搞糊涂了：一边要交计划，一边要对计划提问。用户的回答和计划冲突怎么办？
第二次	改输出格式，让 Claude 按一种特殊的 Markdown 写问题，再由程序解析成界面	Claude 通常能写对，但不稳定：会多写几句、漏掉选项，或者干脆不按格式来
第三次	做一个单独的工具 AskUserQuestion，Claude 随时可以调用；调用时弹出一个对话框显示问题，并暂停，直到用户回答	成功了

第三种做法好在哪里：工具的参数本身就要求结构化的内容，能保证 Claude 给出几个选项；别人也能在 Agent SDK 和 skills 里复用它。

作者特别强调的一点是：Claude 看起来喜欢调用这个工具，输出也好用。 设计得再好的工具，模型不会用也白搭。

例子二：待办清单从帮手变成了束缚

Claude Code 刚发布时，模型需要一份待办清单来保持方向。团队给了它 TodoWrite 工具，还每隔 5 轮插入一条系统提醒，重复它的目标，因为它还是会忘。

模型变强之后，情况反过来了：

• 反复提醒清单，让 Claude 觉得必须照着清单做，即使它已经意识到应该改变方向；
• Opus 4.5 用子代理的能力强了很多，但几个子代理没法在一份共享的清单上协作。

于是团队把 TodoWrite 换成了 Task 工具。待办是为了让一个模型不跑偏；任务是为了让多个智能体互相沟通，可以有依赖关系，可以在子代理之间共享进展，模型也可以修改和删除它们。

这一节的结论值得记住：模型能力提升之后，它曾经需要的工具可能正在限制它。 要不断回头检查“需要哪些工具”这个假设。作者顺带给了一条建议：只支持少数几个能力相近的模型，会省很多事。

例子三：检索从“喂给它”变成“让它自己找”

作者认为，他们做过的最重要的工具，是让 Claude 自己找上下文的那些。

Claude Code 最早在内部用的是 RAG：先用向量数据库给代码库建索引，每次回答之前由程序检索出相关片段交给 Claude。它快，也有效，但要建索引、要配置，在各种环境里容易出问题。更关键的是：上下文是别人给 Claude 的，不是它自己找的。

转变的想法很简单：Claude 既然能搜索网页，为什么不能搜索你的代码库？给它一个 Grep 工具，让它自己搜文件、自己攒上下文。

之后引入的 Agent Skills 把这个思路正式化了，叫作“渐进式披露”：智能体通过探索，一步步发现相关的内容。Claude 读一个 skill 文件，文件里再指向别的文件，它可以一层层读下去。

作者的总结是：一年时间里，Claude 从基本不会自己攒上下文，变成了能跨好几层文件做嵌套搜索，找到恰好需要的那一段。

这就是 Claude Code 不需要你先建索引的原因。

例子四：不加工具也能加功能

Claude Code 目前有大约 20 个工具，团队经常回头检查是不是每一个都还需要。加一个新工具的门槛很高，因为它让模型多了一个要考虑的选项。

遇到的问题是：Claude 不够了解 Claude Code 自己。问它怎么加一个 MCP、某个斜杠命令是干什么的，它答不上来。

方案	问题
把这些信息全写进系统提示词	用户很少问这类问题，白白占上下文，还会干扰 Claude Code 的主业：写代码
给 Claude 一个文档链接，需要时自己去读	能用，但 Claude 会把大段文档拉进上下文，就为了找一句话的答案
做一个专门的子代理（Claude Code Guide），用户问到 Claude Code 本身时由它来查	采用了

最后这种做法里，查文档这件事在子代理自己的上下文里完成，它按详细的说明去搜、去提取，只把答案交回来。主对话的上下文保持干净。

作者承认这不是完美的方案，问 Claude 怎么配置它自己时它仍然可能搞混。但它说明了一件事：可以往 Claude 的能力范围里加东西，而不必加一个新工具。

对你有什么用

如果你在做自己的智能体

• 先想清楚模型自己会什么，再决定给什么工具。不要默认“工具越多越好”，每个工具都是模型要多考虑的一个选项。
• 想让模型输出结构化的内容，做成一个工具，比要求它按某种格式写更可靠。
• 让模型自己去找上下文，通常比替它检索好之后塞给它更好。
• 很少用到的知识，不要放进系统提示词。放进可以按需读取的文件，或者交给一个子代理。
• 模型升级之后，回头看看哪些工具和提醒已经成了多余的约束。

如果你只是用 Claude Code

• 写 skill 时用同样的思路：SKILL.md 只放概要，细节放进它指向的文件里，Claude 需要时才读。写法见 Claude Code skills 怎么写。
• CLAUDE.md 每一轮都会加载，所以它应该短。不常用的内容拆出去。

作者最后的建议很朴素：多做实验，读模型的输出，试新的做法。设计工具既是科学也是手艺，取决于你用的模型、智能体的目标和它运行的环境。