Agent X-Ray

构建 Claude Code 的经验教训：像 Agent 一样思考

构建 Claude Code 的经验教训：像 Agent 一样思考

来源 原文作者：Thariq (@trq212)，发布于 X/Twitter，2026-02-28。 原文链接：https://x.com/trq212/status/2027463795355095314

引言

构建 Agent 框架最困难的部分之一是设计其动作空间（Action Space）。Claude 通过工具调用（Tool Calling）来执行操作，但在 Claude API 中有多种构建工具的方式。你如何决定给 Agent 哪些工具？应该创建一个强大的工具，还是五十个专用的工具？

一个有用的类比：想象你自己需要解决一个复杂任务，你会想要什么工具？这取决于你自身的技能！为 AI Agent 设计工具也是同理 -- 你必须让工具与模型的实际能力相匹配。

随着时间的推移，Claude Code 的构建者们开始像 Agent 一样思考 -- 他们学会了像 Agent 一样看待问题。以下是这段旅程中的关键经验。

经验一：设计 AskUserQuestion 工具

在构建 AskUserQuestion 工具时，目标是提升 Claude 的提问能力（通常称为引导能力/Elicitation）。虽然 Claude 可以用纯文本提问，但回答这些问题总让人觉得花费了不必要的时间，因此团队希望降低摩擦，提高用户与 Claude 之间的沟通带宽。

团队经历了三种方案的迭代：

1. 在其他工具中嵌入提问 -- 这种方式不太稳定，模型无法可靠地使用这种机制。
2. 通过输出格式调整 -- 试图让 Claude 在常规输出中以结构化格式提问，效果也不理想。
3. 专用的 AskUserQuestion 工具 -- 这是最终的胜出方案。

他们最终创建了一个 Claude 可以在任何时刻调用的工具，尤其会在**计划模式（Plan Mode）**中被引导使用。当工具被触发时，会弹出一个对话框展示问题，并阻塞 Agent 的执行循环，直到用户回答。

这个工具让他们能够引导 Claude 生成结构化输出，并确保 Claude 为用户提供多个选项。最重要的是，Claude 似乎很喜欢调用这个工具，输出效果也很好。

经验二：从 TodoWrite 到 Task Tool 的演进

Claude Code 刚发布时，团队意识到模型需要一个待办事项列表来保持方向。待办事项可以在开始时写好，然后在模型完成工作时逐项勾选。为此，他们给 Claude 提供了 TodoWrite 工具，用于编写或更新待办事项并展示给用户。

但他们经常发现 Claude 忘记自己要做什么。

随着模型能力的提升，它们不仅不需要被提醒待办列表，反而觉得这是一种限制。发送提醒会让 Claude 认为它必须严格遵循列表而不是修改它。原本用于帮助的系统指令，实际上限制了 Agent 的规划灵活性。

团队用 Task Tool 替代了 TodoWrite。待办事项的目的是让模型保持方向，而 Task 更多的是帮助 Agent 之间相互通信。Task 可以包含依赖关系、在子 Agent 之间共享更新，模型也可以修改和删除它们。

核心洞见 随着模型能力的提升，模型曾经需要的工具可能反而会限制它们。不断重新审视关于工具需求的旧假设非常重要。

经验三：让 Agent 自主构建上下文

与其预先加载所有可能有用的信息（传统的 RAG 模式 -- 在第一个提示之前检索文档），生产级 Agent 应该通过工具调用按需发现信息。

Claude Code 就是这种理念的典范 -- 它不会在启动时将目录中的所有文件加载到上下文中。取而代之的是，它告诉模型当前所在的目录，并提供文件列表工具，让 Claude 只在需要时才读取文件。给 Claude 搜索工具使其能够主动收集信息，这种方法随着模型能力的提升而更好地扩展。

经验四：渐进式披露

当团队想扩展 Claude 的能力时，他们往往根本不添加新工具。取而代之的是使用渐进式披露（Progressive Disclosure）：技能文件引用其他文件，让 Agent 在多个层次中递归地发现自己的上下文。更多能力，零新工具。

Guide 子 Agent 是这种模式的具体案例。与其在系统提示中塞满每个功能的文档，他们创建了一个专门的子 Agent -- 一种渐进式披露的形式 -- Claude 可以在需要回答文档相关问题时调用它。这保持了主上下文的精简，同时仍然让所有信息可访问。

经验五：工具设计既是艺术也是科学

核心结论 为你的模型设计工具，既是一门艺术，也是一门科学。

文章强调了六项设计原则：

1. 让工具匹配能力 -- 工具应与模型实际能力对齐，而非你期望它能做到的。
2. 优先选择专用工具而非通用工具 -- 专用的 AskUserQuestion 工具比在其他工具中嵌入提问效果更好。
3. 使用渐进式披露 -- 让 Agent 逐步发现上下文，而非一次性预加载所有内容。
4. 赋予主动构建上下文的能力 -- 给 Agent 搜索和探索的能力，而非预先加载信息。
5. 持续观察输出 -- 可靠的路径是检查模型输出并通过观察识别性能差距。
6. 保持工具集精简 -- Claude Code 使用大约 20 个工具，而非数百个。更简洁、更通用的工具始终优于大量狭窄工具的集合。

Apple 的 CodeAct 研究独立证实了这一发现：在复杂任务上，单一代码执行原语的表现比专用工具套件高出多达 20%。

结论

Agent 的工具设计必须随着模型能力的增长而成熟，有时是通过删减而非添加。传统的 Agent 开发在问题出现时添加工具。Claude Code 的轨迹表明了相反的方法 -- 有时移除或简化工具反而能带来更好的结果。

关键在于关注什么对模型有效。随着时间推移，你会开始像 Agent 一样思考，学会像 Agent 一样看待问题。

---

核心观点总结

一句话总结 Agent 工具应随模型能力增长而演进，有时"删减"比"添加"更有效。

五大经验速览

对产品/开发工作的启发

1. 少即是多 -- Claude Code 仅用约 20 个工具就实现了强大的 Agent 能力，说明精心设计的少量工具优于大量粗糙工具
2. 随能力迭代工具 -- 不要把工具设计当成一次性工作；模型在进步，工具也要跟着进化（甚至退化）
3. 让 Agent 主动探索 -- 与其试图预判 Agent 需要什么信息，不如给它探索的能力，让它自己找到答案
4. 观察先于设计 -- 好的工具设计来自对模型行为的持续观察，而非纯粹的理论推演
5. 渐进式披露是通用模式 -- 不仅适用于 Agent 工具设计，也适用于产品 UX、文档组织、API 设计等场景

---

相关文档

• 英文原文
• 参考：Anup.io 分析文章
• 参考：Efficient Coder 分析文章

---