像智能体一样观察：Anthropic 团队谈 Claude Code 工具设计的演进与艺术
Thariq约 7 分钟导读：本文由 Claude Code 团队成员 Thariq 分享一篇长文，探讨 AI 智能体设计技巧，强调其更像艺术，需要平衡提示缓存、工具调用与上下文管理。
文章核心包括渐进式披露机制，从 JSON 配置到完整 Markdown 逐步加载上下文，避免 token 浪费，并建议使用文件系统作为 agent 的“自然界面”。
Thariq @trq212 , Claude Code 核心成员，专注 AI agent 与开发者工具设计。曾参与 YC W20 创业项目，并于 MIT Media Lab 深耕研究。目前致力于让 Claude 成为更强大、可控的编码伙伴，分享实用工程洞见，追求“loving grace”的智能未来。
构建智能体框架（Agent Harness）最困难的部分之一，就是构筑其动作空间（Action Space）。
Claude 通过“工具调用（Tool Calling）”来采取行动，但在 Claude API 中，构建工具的方式多种多样，包括 Bash 脚本、预设技能（Skills）以及最近推出的代码执行功能（关于 API 上的程序化工具调用，可以参阅 @RLanceMartin 的新文章）
参阅：https://x.com/RLanceMartin/status/2027450018513490419
面对这么多选项，你该如何设计智能体的工具？是只需要“代码执行”或“Bash”这一个万能工具就够了，还是针对每种可能遇到的场景设计 50 个专门的工具？
为了让自己进入模型的思维状态，我喜欢想象自己正在解一道复杂的数学题。你会想要什么样的工具来解决它？这取决于你自己的能力。
纸笔是底线，但你会受限于手动计算；计算器更好，但你需要知道如何操作那些高级功能；最快、最强大的选择是电脑，但你必须懂得如何编写和执行代码。
这是一个设计智能体的有用框架：你希望赋予它的工具，应当是根据其自身能力量身定制的。 但你怎么知道它的能力边界在哪里？你需要仔细观察、阅读它的输出、不断实验。简而言之，你要学会像智能体一样观察。
以下是我们在构建 Claude Code 过程中，通过观察 Claude 总结出的一些经验。
提升引导能力与 AskUserQuestion 工具
在构建 AskUserQuestion 工具时，我们的目标是提升 Claude 的提问能力（通常称为“引导/需求采集”，Elicitation）。
虽然 Claude 可以直接用纯文本提问，但我们发现回复这些问题往往会消耗不必要的时间。我们如何才能降低这种摩擦，增加用户与 Claude 之间的沟通带宽？
尝试 #1：修改 ExitPlanTool
我们最初尝试在 ExitPlanTool（退出计划工具）中增加一个参数，使其在输出计划的同时附带一系列问题。这是最容易实现的方案，但它让 Claude 感到困惑，因为它需要同时制定计划并针对该计划提出问题。如果用户的回答与计划冲突怎么办？Claude 是否需要调用两次该工具？我们需要另寻他法。（你可以在我们关于提示词缓存的文章中了解更多关于 ExitPlanTool 的设计初衷）
尝试 #2：更改输出格式
接着，我们尝试修改 Claude 的输出指令，让它使用一种略微修改过的 Markdown 格式来提问。例如，要求它输出一个带括号选项的列表。然后我们可以解析这种格式，并为用户渲染 UI。
虽然这是改动最小的方案，Claude 似乎也能胜任，但稳定性无法保证。Claude 经常会附带额外的句子、漏掉选项，或者干脆使用了完全不同的格式。
尝试 #3：AskUserQuestion 工具
最终，我们决定创建一个 Claude 可以在任何时候调用的专用工具，并特别提示它在“计划模式（Plan Mode）”下使用。当该工具被触发时，我们会弹出一个模态框显示问题，并阻塞智能体的循环，直到用户给出回答。
这个工具允许我们要求 Claude 提供结构化输出，确保它能给用户提供多个选项。它还允许用户灵活组合功能，例如在 Agent SDK 中调用它，或在自定义技能中引用它。
最重要的是，Claude 似乎很喜欢调用这个工具，其输出效果也非常好。即使设计得再精妙的工具，如果 Claude 不理解如何调用它，也是徒劳。
这是 Claude Code 中“引导提问”的最终形态吗？我们不确定。正如接下来的例子所示，对一个模型有效的方案，对另一个模型未必是最佳的。
随能力演进：任务（Tasks）与待办（Todos）
当 Claude Code 最初发布时，我们意识到模型需要一个“待办事项清单（Todo list）”来保持专注。Todo 可以在开始时写入，并在工作进行中逐步勾选。为此，我们给 Claude 配备了 TodoWrite 工具，该工具可以编写或更新 Todo 并将其展示给用户。
但即便如此，我们仍经常发现 Claude 会忘记自己要做什么。为了适应这一点，我们曾每隔 5 轮对话就插入一次系统提醒，告知 Claude 它的当前目标。
然而，随着模型的进步（如 Opus 4.5），它们不仅不再需要 Todo 提醒，甚至会觉得这是一种限制。不断发送的 Todo 提醒让 Claude 认为它必须死板地遵守清单，而不是根据实际情况修改它。我们还发现，新模型在调用“子智能体（Subagents）”方面表现更出色，但多个子智能体如何在一个共享的 Todo 清单上协作？
看到这些变化后，我们用 Task 工具 取代了 TodoWrite（在此阅读更多关于 Task 的信息）。Todo 的核心是“保持专注”，而 Task 的核心则是“辅助智能体间的协作”。Task 可以包含依赖关系、在子智能体间共享进度，且模型可以自由修改或删除它们。
当模型能力提升时，曾经需要的工具反而可能成为束缚。 不断审视先前的假设至关重要。这也是为什么在开发时，最好专注于支持一组能力曲线相似的模型。
设计搜索界面
对 Claude 而言，一套至关重要的工具是用于构建自身上下文的搜索工具。
Claude Code 刚面世时，我们使用 RAG（检索增强生成）向量数据库来寻找上下文。虽然 RAG 强大且快速，但它需要索引和配置，且在不同环境下可能显得脆弱。更重要的是，上下文是“喂”给 Claude 的，而不是它自己“找”到的。
如果 Claude 能搜索网页，为什么不能搜索你的本地代码库？通过赋予 Claude 一个 Grep 工具，我们让它能够自行搜索文件并构建上下文。
我们观察到一个规律：随着 Claude 变得越来越聪明，只要给它合适的工具，它就越来越擅长自主构建上下文。
当我们引入“智能体技能（Agent Skills）”时，我们将 “渐进式披露（Progressive Disclosure）” 的理念正式化了——这允许智能体通过探索逐步发现相关的上下文。
Claude 可以阅读“技能文件”，这些文件可以递归地引用模型可以读取的其他文件。事实上，技能的一个常见用法是为 Claude 增加更多搜索能力，比如教它如何使用某个 API 或查询某个数据库。
在一年时间里，Claude 从不太会构建上下文，演进到了能够跨多层文件进行嵌套搜索，从而精准找到所需的上下文。渐进式披露现在已成为我们增加新功能而不增加新工具的常用技巧。
渐进式披露：Claude Code 指南智能体
目前 Claude Code 拥有约 20 个工具，我们一直在反思是否真的需要这么多。添加新工具的门槛很高，因为这会增加模型的思考负担。
例如，我们注意到 Claude 不太了解如何使用 Claude Code 本身。如果你问它如何添加 MCP 或某个斜杠命令的作用，它无法回答。
我们可以把这些信息全塞进系统提示词（System Prompt）里，但考虑到用户很少问这些，这会造成“上下文腐化（Context Rot）”，干扰 Claude Code 的核心任务：写代码。
相反，我们尝试了渐进式披露。我们给了 Claude 一个指向其文档的链接，它可以在需要时加载并搜索。这可行，但我们发现 Claude 为了找一个简单的答案，会把大量搜索结果加载到上下文中，其实你只需要那个答案本身。
于是我们构建了 Claude Code Guide 子智能体。当用户询问有关 Claude Code 自身的问题时，Claude 会被提示调用这个子智能体。这个子智能体拥有关于如何精准搜索文档并返回答案的详尽指令。
虽然这并不完美（Claude 在处理安装配置类问题时偶尔仍会困惑），但比以前好得多！我们成功地在不增加工具的前提下，扩展了 Claude 的动作空间。
是一门艺术，而非科学
如果你期待一套关于如何构建工具的死板规则，那么这篇文章恐怕无法提供。为模型设计工具既是科学，更是艺术。它高度依赖于你使用的模型、智能体的目标以及它运行的环境。
多实验，多阅读输出，多尝试新事物。像智能体一样去观察。
https://x.com/trq212/status/2027463795355095314[1]
后记
有一位网友马上根据这篇文章设计了一个 skill，将文章粘贴到 Claude code 自动生成以下 skill。
太棒了！我已经根据文章创建了 agent-design 技能。以下是我的操作内容：
已创建的技能结构
~/.claude/skills/agent-design/└── SKILL.md
技能包含的内容
该技能涵盖了文章中的核心经验：
- 核心哲学：根据模型能力定制工具
- 经验 1：提升引导提问能力（AskUserQuestion 工具的演进）
- 经验 2：适应不断进化的能力（Tasks 与 Todos 的对比）
- 经验 3：让智能体自行构建上下文（渐进式披露）
- 经验 4：优先使用渐进式披露而非新工具（子智能体应用）
- 设计指南：何时添加工具、何时不添加，以及值得考虑的模式
- 框架：工具设计的循序渐进方法
- 反模式：应当避免的常见错误
如何使用
在开发智能体系统时调用该技能：
/agent-design