Claude Code Agent 工具设计：为什么一个提问工具要迭代三版？

Claude Code 团队成员 Thariq 最近公开了 Agent 工具设计的内部经验。核心观点反直觉：工具好不好，不是开发者说了算，是模型说了算。一个 AskUserQuestion 工具迭代了三版才稳定，TodoWrite 随模型进化被整个替换，RAG 被砍掉换成了 Grep。这些决策背后的设计哲学，值得每个做 AI Agent 的开发者认真理解。

发生了什么

Thariq 提出了一个框架：Seeing like an Agent——像 Agent 一样看世界。工具要匹配使用者的能力，给 Agent 设计工具不是看功能完不完善，而是看模型能不能理解、愿不愿意调用。

具体案例是 AskUserQuestion 工具的三次迭代。第一版在 ExitPlanTool 上加问题参数，Claude 直接搞混了计划和问题，输出互相冲突。第二版让 Claude 输出特殊格式的 Markdown，模型能输出但格式不稳定——多加总结、漏掉选项、随意换写法。第三版做成独立工具，Claude 随时调用，触发后弹出模态框让用户回答。结果 Claude 不仅输出稳定，而且"喜欢"调用这个工具。

差别在哪？填表格和自由写报告的区别。表格格式统一，自由发挥千奇百怪。结构化工具调用天然比非结构化输出更可控。

为什么重要

这套经验揭示了 Agent 工具设计的两个关键原则。

第一，工具必须随模型进化。 TodoWrite 的故事最能说明问题。早期模型做着做着就忘了目标，团队给了 TodoWrite 工具并每隔 5 轮对话插入系统提醒。但 Opus 不仅不需要提醒，反而被提醒搞得更死板——系统每 5 轮催一句"看看你的 Todo List"，Claude 就死守清单不敢灵活调整。加上 Opus 的子 Agent 能力变强，单机版待办无法跨 Agent 共享，团队最终用 Task Tool 替换了 TodoWrite。小孩骑车先装辅助轮，骑熟了辅助轮反而碍事。

第二，工具不是越多越好。 Claude Code 功能持续增加，但工具数量一直维持在约 20 个。每多一个工具，模型就多一个选择，决策越慢，出错概率越高。就像餐厅菜单 10 道菜你很快能选，200 道菜反而不知道点什么。

技术细节

Claude Code 团队用三种策略在不加工具的情况下扩展能力。

从 RAG 到自主搜索。 Claude Code 最早用 RAG 向量数据库提供代码上下文，后来整个砍掉，换成 Grep 工具让模型自己搜。原因是 RAG 需要提前索引和配置，换环境容易出问题，更关键的是模型没有选择权。团队发现模型自己搜到的上下文，比精心筛选后喂给它的反而更准确。

渐进式信息发现（Progressive Disclosure）。 Claude Code 的 Skills 系统让模型读到一个文件后，按需展开引用的下一层文件，层层递进精准定位。类似维基百科的蓝色链接——你不需要一次性看完所有内容。一年前 Claude 完全不会自己构建上下文，现在已经能嵌套搜索好几层文件。

子 Agent 路由。 用户问"怎么添加 MCP"时，团队没有把说明塞进系统 prompt，也没有加文档搜索工具，而是做了一个 Claude Code Guide 子 Agent。通过 Prompt 指令让模型在遇到特定问题时启动子 Agent。能力增加了，工具数量没变。

你现在该做什么

给你的 Agent 加新功能前，先问三个问题：这个功能能否让模型自己搜索解决？信息能否写成文件让模型按需读取？任务能否交给子 Agent？

一个马上能用的方法：给 Agent 加新工具之前，先让模型跑 10 次，观察它愿不愿意调用、输出格式对不对，再决定是否上线。另外，在你的 Agent 项目里创建一个 skills 目录，把常用操作的说明文档放进去，文档之间互相引用，让模型通过阅读文件获取新能力，而不是调用新工具。

相关阅读：AI Agent 术语表 · Prompt Engineering 指南

---

觉得有用？订阅 AI 简报，每天 5 分钟掌握 AI 动态。