工具数量是一道权衡题

Thariq 用了一个数学题的类比来建立框架。纸笔、计算器、电脑——三种工具对应三种能力水平。给不会编程的人一台电脑，不会比给他一张纸更快。Agent 工具设计的逻辑完全相同。

工具太多，模型每一步决策都要在过多的分支中权衡，选择困难。工具太少，比如只给一个万能 bash，理论上什么都能做，但没有语义信号告诉它"现在该问用户"还是"该写文件"，就像只给你一把螺丝刀让你装修整套房子。

怎么找到平衡点？方法很朴素：观察模型的输出，读它写的东西，反复实验。Thariq 把这叫做"See like an agent"——用 agent 的视角看问题。这不是玄学，而是工程方法论。

三次失败才做对的 AskUserQuestion

这是整篇文章中工程质感最强的一段。Claude Code 需要一个让 AI 主动向用户提问的功能，看似简单，做了三版。

第一版：改造现有工具。 在已有的 ExitPlanTool 上加一个参数，让它在输出计划的同时附带一组问题。结果模型被搞糊涂了——同时做两件事，如果用户回答和计划矛盾怎么办？一个工具承担两个职责，模型就会在角色冲突中犯迷糊。

第二版：改变输出格式。 不加新工具，让 Claude 用特定的 markdown 格式来提问，前端负责解析渲染。结果不稳定，有时多追加几句话，有时漏掉选项，有时干脆换了一种格式。让模型用自由文本模拟结构化输出，大概率不可靠。

第三版：做独立工具。 专门的 AskUserQuestion 工具，触发后弹出模态框，阻塞 agent 循环直到用户回答。结构化 schema 保证输出格式，模态框保证用户必须回答，工具接口保证可组合性。

最终版能成功，有一个容易被忽略的信号——Thariq 说"Claude 似乎很喜欢调用这个工具"。模型是否愿意调用某个工具，本身就是设计好坏最真实的反馈。再精巧的工具，模型不理解怎么调用，也是白搭。这个判断标准对所有在搭 Agent 的人都适用：当模型输出不稳定时，别让它自己凑格式，把自由文本收成结构化工具调用。

做对的工具也会过时

如果说 AskUserQuestion 讲的是怎么把工具从"不对"做到"对"，TodoWrite 到 Task Tool 的演进讲的是更扎心的事——做对了的东西，怎么变成错的。

早期模型经常做着做着就忘了自己要干什么，团队做了 TodoWrite，一个待办列表工具，开头写好计划，每做完一项勾掉。甚至还不够，他们在对话中每隔 5 轮插入一条系统提醒。在早期模型上效果不错。

到了 Opus 4.5 这一代，问题反转了。反复提醒待办列表，Claude 开始觉得它必须严格按列表执行，而不是根据实际情况灵活调整——提醒变成了束缚。同时新模型在子智能体协作方面进步很大，多个子智能体怎么在一个共享 Todo List 上协调，成了新问题。

于是 Task Tool 替换了 TodoWrite。区别不只是名字：TodoWrite 解决的是模型注意力不足的问题，Task Tool 解决的是多 agent 协作的问题，支持依赖关系、跨子智能体共享状态、自由修改和删除。

曾经的救星，后来的枷锁。这对搭建 Agent 工作流的人是一个重要提醒：模型能力大约半年一个台阶，你的工具假设跟不跟得上？Thariq 还补了一条实操建议——尽量只支持少量能力相近的模型，这样工具设计的假设才能保持一致。

给地图，别给百科全书

最后一个案例不是关于某个具体工具，而是一种设计模式：渐进式披露。

Claude Code 最早用 RAG 向量数据库给模型提供上下文，快是快，但模型是在被动接收上下文，而不是主动找到它。后来换成 Grep 工具让它自己搜索代码库，效果立竿见影。再后来 Agent Skills 让渐进式披露成为正式范式——模型读取一个 skill 文件，文件引用其他文件，其他文件又引用更深层的文件，递归逐层探索。一年时间，从"几乎不能自己构建上下文"到"在多层文件之间嵌套搜索"。

同样的思路还体现在另一个细节上。用户会问 Claude 关于 Claude Code 自身的问题，比如怎么配置 MCP、某个 slash command 是干什么的。最粗暴的做法是把所有文档塞进 system prompt，但用户很少问这类问题，塞进去只会占用上下文、干扰主业。Thariq 把这叫"上下文腐烂"——20 页产品文档全塞给模型，结果它连第一条需求都答不准。

他们的做法是做了一个 Claude Code Guide 子智能体，透明运行，按需唤起，查完文档再把答案返回。不增加工具数量，通过子智能体扩展 agent 的行动空间。

三条可以直接拿走的原则

Thariq 没有给出一套严格的工具设计规则，他说"为模型设计工具，既是科学，也是艺术"。但四个案例里藏着三条硬原则：

  • 观察，不要猜。 AskUserQuestion 迭代三次，每次都是看模型实际表现后才改，不是从理论推导。模型"喜不喜欢"调用某个工具，就是最真实的设计反馈。
  • 定期复盘工具假设。 TodoWrite 在旧模型上救命，在新模型上添堵。你上个月搭的 Agent 工作流，这个月的模型可能已经不需要那些辅助轮了。
  • 给地图，别给百科全书。 从 RAG 到 Grep 到 Skills 到子智能体，方向只有一个——让模型自己决定要什么信息，而不是你替它决定。

对于正在搭建 Agent 或设计自动化工作流的人来说，这篇文章最大的价值不在于具体的技术方案，而在于思维方式的转变：工具设计的核心不是"我能给模型什么能力"，而是"模型当前能消化什么能力"。这个判断，只能靠持续观察模型的实际行为来校准，没有捷径。