《从构建 Claude Code 中学到的经验：像 Agent 一样看世界》

本文作者Thariq 在 Anthropic工作，具体负责 Claude Code项目。他是 Claude Code 团队的核心成员之一，经常在 X（Twitter）上分享 Claude Code 的开发经验、工具设计思路、Agent 构建心得等内容。 很多用户把他的帖子视为 Claude Code 的“非官方但很权威”的内部视角。

从构建 Claude Code 中学到的经验：像 Agent 一样“看”世界

构建一个 Agent 系统最难的部分之一，就是设计它的行动空间（action space）。

Claude 是通过 Tool Calling 来行动的，而 Claude API 提供了各种工具原语：bash、skills、最近新增的代码执行等等（可以参考 Lance Martin 最近那篇关于程序化工具调用的文章）。

面对这么多选项，到底该如何设计 Agent 的工具？

是只给一个万能工具比如代码执行或 bash 就够了？

还是应该做 50 个工具，每个场景一个专用工具？

我喜欢用一个比喻来思考这个问题：

假如现在给你一道很难的数学题，你最想要什么工具来解题？这其实取决于你自己的能力水平。

• 最基础：一张纸 → 只能手算，效率很低

• 好一点：一台计算器 → 快很多，但高级功能你得会用

• 最强：一台电脑 → 可以写代码跑，但前提是你得会编程

这个比喻其实很适合用来设计 Agent 的工具：

你应该给模型提供“契合它自身能力”的工具，而不是你人类觉得好用的工具。

那怎么知道模型真正擅长什么、需要什么呢？

答案是：持续观察它的输出、做实验、和它对话 —— 学会像 Agent 一样去看问题。

下面分享我们在打造 Claude Code 过程中，真正踩过的一些坑和学到的经验。

1. 怎么让 Claude 更好地“问问题”？ —AskUserQuestion 工具的演化

我们一开始就想提升 Claude 的主动澄清能力（elicitation）。

尝试1： 在 ExitPlanTool 里加一个问题数组

最简单粗暴，但效果很差。

因为同时让它输出“计划 + 一堆问题”，Claude 自己都懵了：万一用户回答和计划冲突怎么办？要不要调用两次工具？逻辑混乱。

尝试2： 修改输出格式（比如要求用特定 markdown 列出问题 + 备选答案）

理论上最通用，但实际非常不稳定。

Claude 要么多写几句废话，要么漏掉选项，要么直接用完全不同的格式，完全不可靠。

尝试3： 专门做一个 AskUserQuestion 工具

允许 Claude 在任何时候调用，尤其在“规划模式”里强烈鼓励调用。

调用后弹出 modal 展示问题，用户回答前 Agent 暂停循环。这个工具的好处：

• 可以严格约束输出结构（比如强制提供多个选项）

• 用户和开发者都能方便组合使用（Agent SDK、Skill 里都可以调用）

• 最重要的是：Claude 很喜欢用这个工具，而且用得很好

但我们也清楚，这未必是终极形态。不同模型对 elicitation 的偏好差异很大，后面的例子会再次证明这一点。

2. 模型变强后，工具反而会变成枷锁， 从 Todo 到 Task 的转变

Claude Code 刚上线时，模型很容易跑偏，所以我们给了它 TodoWrite 工具，让它写/勾选任务清单。

甚至每 5 轮还插入系统提示，硬提醒它别忘了目标。

但随着模型（尤其是 Opus 4.5 之后）能力飞跃，出现了反效果：

• 频繁提醒反而让它觉得“必须严格按清单走”，不敢灵活调整

• 它开始擅长用 subagent，但多个 subagent 怎么共享一个 Todo 列表？根本协调不了

后来我们把 TodoWrite 彻底替换成了 Task 工具：

• 不再是“提醒自己别跑偏”

• 而是变成“多 Agent 之间协调、依赖、进度同步”的通信工具

• 支持依赖关系、更新、删除、跨 Agent 共享

结论非常清晰：

模型能力提升后，曾经救命的工具，很可能变成限制它的枷锁。

必须持续迭代、砍掉过时的工具，尤其要聚焦支持能力相近的少数几个模型版本。

3. 搜索界面的演进：

从被动 RAG 到主动构建上下文

早期我们用 RAG 向量库给 Claude 喂上下文，速度快，但有几个致命问题：

• 需要提前索引，很麻烦

• 上下文是被“塞给”它的，而不是它自己找的

后来我们给了它 Grep 工具，让它自己去搜索代码库、自己决定读哪些文件。

再往后引入 Agent Skills，正式把渐进式揭示（progressive disclosure）变成核心玩法：

• Claude 先读一个 Skill 文件

• Skill 文件里又引用其他文件

• 它可以递归地一层一层探索下去

这一年里，Claude 从“几乎不会自己找上下文”，进化到“能多层嵌套搜索、精确定位所需代码”。

渐进式揭示现在是我们添加新功能时最常用的手法，而且不增加工具数量。

4. 用子 Agent + 渐进揭示，

解决“自我认知”问题

Claude Code 大概有 20 个工具，我们一直在问自己：真的都需要这么多吗？

新增工具的门槛非常高，因为每多一个选项，模型就要多思考一次。

有个典型例子：用户问“怎么加 MCP？”“/命令是什么意思？”

早期 Claude 完全不会回答。

方案1：全塞系统提示 → 太浪费 token，而且大部分时间用不到，造成上下文腐败。

方案2：给它文档链接，让它自己加载搜索 → 结果它经常一次拉几千行进来，上下文爆炸。

最终方案：做了个专门的 Claude Code Guide 子 Agent

• 主 Agent 看到“关于 Claude Code 自身用法”的问题，就调用这个子 Agent

• 子 Agent 有非常精细的指令，知道怎么高效搜索文档、怎么精简回答

虽然还不完美（偶尔还是会答偏），但比以前好太多了。

我们用子 Agent + 渐进揭示的方式，扩展了能力，却没有增加主工具的数量。

总结：这是一门艺术，而非科学

如果你期待一套“放之四海而皆准”的工具设计公式，很遗憾，没有。

设计 Agent 的工具系统，高度依赖：

• 你用的具体模型

• Agent 的核心目标

• 运行环境

只能不停实验、阅读输出、试错、再试错。

最终要学会的，就是像 Agent 一样去看问题。

---

原文链接：https://mp.weixin.qq.com/s/XeuTbYBRqZjF6kdMYd0w5A

来源：Thariq