题记：本文编译自 Anthropic 工程师 @trq212 发表的技术长文《Lessons from Building Claude Code: Seeing like an Agent》，文章总结了构建 Claude Code 过程中积累的工具设计方法论，从 AskUserQuestion 工具的三次迭代、Todo 演化为 Task 的背后逻辑，到渐进式披露这个设计模式，信息密度很高。原文链接：https://x.com/trq212/status/2027463795355095314。

正在构建 AI Agent 的人，大都会卡在同一个问题上：该给模型什么工具？

工具太少，Agent 能做的事受限；工具太多，模型反而不知道用哪个，甚至会在不该用的时候乱用。Claude Code 的工程师 Thariq 把这个问题研究了将近一年，陆续更换和迭代了多个工具，最近整理出了一篇总结。我觉得值得认真读，不只是因为这篇文章谈的是 Claude Code，更是因为里面的思路对任何人构建 Agent 都有参考价值。

工具设计的起点：以模型能力为锚

原文里有个简单但容易理解的类比：如果让你解一道难的数学题，你想要什么工具？

纸笔是起点，能手算，但速度慢。计算器快，但要知道怎么使用它的高级功能。最强大的自然是计算机，可以写代码来解，但前提是你会编程。工具的档次不同，能解决的问题就不一样，而且工具必须匹配使用者的能力。

给 Agent 设计工具，逻辑一样。原文的核心观点是：你需要给模型能力匹配的工具，而匹配的标准，来自你对模型能力的观察和理解。这需要持续关注它的输出，看它在哪里卡壳、哪里游刃有余，然后针对性地调整工具设计。

说起来简单，实践里很难。下面这几个案例能说明具体是怎么做的。

AskUserQuestion：三次迭代才找到正解

Claude Code 本来可以直接在对话里问用户问题，但这种自由格式的问答摩擦感很强。Anthropic 想降低这个成本，提升模型和用户之间的信息传递效率。

第一次尝试是在ExitPlanTool 里加一个问题数组，让模型同时输出计划和问题。实现最简单，但逻辑上有个矛盾：如果用户的回答和计划冲突了，模型要不要重新调用ExitPlanTool？这个方案废了。

第二次改输出格式，让 Claude Code 用特定的 Markdown 格式来提问，比如带选项的 bullet list，前端解析后展示成 UI 组件。思路挺好，执行不稳定。Claude Code 会在末尾多写几句话、换一种格式、或者漏掉选项。靠模型自律输出结构化内容，在复杂上下文里根本靠不住。

第三次，单独做了一个工具。Claude Code 可以在任何时候调用，但尤其适合在 Plan Mode 阶段。工具触发时弹出 Modal，展示问题和选项，阻塞 Agent 执行循环，等用户回答完再继续。

这个方案的关键在于把格式约束放进了工具 Schema，而不是寄希望于模型自觉。Claude Code 也更愿意调用这个工具，因为调用动作本身就是结构化的，不需要它猜格式。

这个迭代过程挺有代表性的。很多人以为提示词写清楚，模型就会乖乖按格式输出。真实情况是，这种稳定性在复杂场景下很脆弱。把格式约束建进工具才是根本解法。

Todo 变成 Task：工具要跟着模型一起进化

Claude Code 刚上线时，模型跑着跑着就会忘记自己在做什么。早期的解决方案是TodoWrite 工具，让 Claude Code 开始时列出待办，边做边打勾。为了防止它还是遗忘，每五轮对话插一条系统提醒。

这套机制在当时有效。但在模型能力变强后，新问题来了。

Opus 4.5 不需要频繁提醒，但系统提示的存在让它以为必须严格按 Todo 执行，不能灵活调整计划。模型被工具套住了，而工具反而限制 Claude Code 的能力。同时，子 Agent 协作的场景越来越多，几个 Agent 怎么共享一个 Todo 列表？TodoWrite 完全没考虑这个场景。

于是换成了 Task 工具。Task 支持依赖关系，子 Agent 可以互相通知状态，模型可以修改和删除任务，也可以主动新建。它更像是 Agent 之间的协调机制，而不是单纯的备忘录。

原文里说的这句话我觉得值得记住：“随着模型能力提升，那些原本帮助模型的工具，可能反而开始限制它。定期重新审视之前的假设很重要。”

这不只是 Claude Code 的问题。任何长期运行的 Agent 系统都会面临这个问题，因为你依赖的基座模型在变，但工具往往不会跟着变。

搜索工具：从被动接收到主动探索

最早，Claude Code 用 RAG 向量数据库来给 Claude Code 提供上下文。RAG 快、能处理大量文件，但它需要额外的索引和配置，并且也不够稳定。更重要的是，上下文是你喂给 Claude Code 的，而不是它自己找的。

后来加了Grep 工具，这个变化看起来很小，背后的设计理念转变挺大的。RAG 是外部系统决定 Claude Code 应该看什么，Grep 是让 Claude 自己决定自己需要看什么。模型越来越强，后者效果越来越好。Claude Code 逐渐学会了按需构建自己的上下文。

在 Agent Skills 上，这个思路被正式化为渐进式披露（Progressive Disclosure）。Skill 文件可以引用其他文件，模型可以递归地读取，层层展开。不是一次性把所有信息都摆在模型面前，而是让它按需探索。

一年下来，Claude Code 从基本不会自主构建上下文，进化到能在多层文件里精确找到自己需要的信息。

渐进式披露：不用加工具也能扩展能力

Claude Code 现在大约有 20 个工具，团队经常在自问：它们真的都需要吗？每加一个工具，模型就多一个要考虑的选项，决策负担上升。

比如，用户问 Claude Code 怎么添加 MCP、Slash Command 是什么，Claude Code 可能就答不上来，因为这些信息没在系统提示里。要不要把所有文档塞进系统提示？空间浪费，而且用户很少问这类问题，不值得一直放那儿。

他们的最终解法是做了一个专门的 Claude Code 指南 子 Agent，当你问 Claude Code 关于自身使用的问题时，它会调用这个子 Agent。子 Agent 有详细的搜索策略，知道去哪里找什么，只返回真正需要的答案。

这是渐进式披露的另一个形态：不加工具，而是加子 Agent，把专业问题交给专业的执行者。需要时才激活，不需要时不占用主 Agent 的注意力。

写在最后

给模型设计工具，不只是技术，更是一种艺术，没有一套通用规则，要看用的是什么模型、Agent 的目标是什么、运行环境是什么。

从最简单的方案开始，观察模型在哪里用得好、哪里卡壳，然后针对性地改。工具是模型能力的放大器，模型能力变了，放大器也得跟着换。

有意思的是，这篇文章本身就用了渐进式披露的写法。没有一上来就给结论，而是通过三个迭代案例，让读者自己摸出规律来。作者确实做到了“像 Agent 一样思考”。

欢迎长按下面的二维码关注Feisky 公众号，了解更多云原生和 AI 知识。