大家好，今天分享一篇AI圈近期很火的实战干货——来自Anthropic核心工程师Thariq Shihipar（@trq212）的深度复盘，主题是《Lessons from Building Claude Code: Seeing like an Agent》（《构建Claude Code的经验：像Agent一样看世界》）。

作为Claude Code的核心开发者，Thariq没有讲空泛的理论，而是把团队在搭建Agent工具过程中踩过的坑、迭代的思路，拆成了4个真实案例，每一个都能直接复用在我们自己的Agent设计中。

0 核心前提：Agent设计，最难的不是“加工具”，而是“选对工具”

在开始分享案例前，先明确一个核心观点——构建Agent框架，最关键的不是“工具越多越好”，而是“工具要匹配模型的能力”。

Thariq用一个很形象的比喻，帮我们理解这个逻辑：

假设你被困在一道复杂数学题里，需要什么工具？答案完全取决于你自身的能力：

• 纸笔是最低配，但会被手动计算限制效率；

• 计算器更高效，但你得会用它的高级功能；

• 电脑最快最强，但你必须懂代码、会执行。

Agent的工具设计也是如此：给模型的工具，既不能太简单（限制能力），也不能太复杂（模型不会用）。而要找到这个平衡点，唯一的方法就是——仔细观察模型的行为，学会“像Agent一样思考”。

下面，就是Thariq团队在打造Claude Code时，通过真实实践总结的4个核心经验，每一个都带着具体的迭代过程，干货拉满。

1 案例1：从“混乱提问”到“高效交互”，AskUserQuestion工具的3次迭代

核心目标：让Claude能更自然、更低成本地向用户提问（比如确认需求、补充信息），提升双方的沟通效率。

一开始，团队走了不少弯路，最终才找到最优解，整个过程分为3个阶段：

尝试1：在现有工具里“凑数”，语义混乱

最开始图省事，直接给现有工具ExitPlanTool加了一个参数，让模型在提交计划时，顺便带上要问用户的问题。

结果很糟糕：模型一边要做计划，一边要提问，逻辑混乱；如果用户的回答和计划冲突，系统不知道该优先信哪一个；甚至会出现模型反复调用工具、陷入循环的情况。

结论：工程上最简单，但语义不清晰，完全不可行。

尝试2：修改输出格式，稳定性差

接着，团队尝试让Claude用固定的Markdown格式提问（比如带选项的项目符号），再由前端解析成可视化UI。

这个思路没问题，但实际用起来发现，模型根本“不听话”：有时会多写无关内容，有时会漏了选项，有时直接自己换了格式。

这里藏着一个关键教训：让模型“模仿结构化输出”，和让模型“真正调用结构化接口”，可靠性完全不是一个等级。

尝试3：专门做工具，完美适配

最终，团队开发了专门的AskUserQuestion工具：Claude可以在任何需要的时候调用它，工具触发后，UI会弹出规范的问题列表，并且暂停Agent的运行，直到用户完成回答。

这个工具的优势很明显：输出结构稳定、可以强制包含选项、交互顺滑，还能在不同场景下复用。

最关键的是——Claude喜欢用，而且能用对。毕竟，一个再强大的工具，如果模型不会用、不知道什么时候用，也是白费功夫。

2 案例2：随模型进化而迭代，从Todo到Task的升级

这个案例告诉我们：工具不是一成不变的，随着模型能力的提升，曾经的“帮手”可能会变成“枷锁”。

早期：Todo工具，只为“不跑偏”

Claude Code刚推出时，模型的能力还不够强，很容易忘记自己的目标。于是团队给了它一个TodoWrite工具，让它创建待办列表，并且在工作中逐项勾选。

即便如此，模型还是经常忘事，团队只能每5轮就插入一次系统提醒，反复强调目标。

后期：Task工具，适配更强模型

随着模型不断升级，副作用出现了：模型不再需要频繁提醒，固定的Todo列表反而限制了它的灵活调整；而且不同子代理之间，也无法共享和协同Todo状态。

于是，团队用Task工具替换了TodoWrite工具——两者的核心区别的是：

• Todo：只是简单的待办列表，目的是“让模型别跑偏”；

• Task：更像一个可共享的任务载体，支持子任务、依赖关系，还能跨代理同步更新、修改、重组。

关键教训：做Agent工具设计，一定要不断重新审视“我们需要什么工具”，跟着模型的能力一起迭代，不能一成不变。

3 案例3：范式转变，让模型“自己找上下文”

对Claude来说，“找到正确的上下文”（比如代码库、文档）是很重要的能力。早期，团队用的是大家熟悉的RAG向量数据库，帮模型提前找好上下文再喂进去。

RAG很快，但有三个致命问题：需要预先索引和维护，在不同环境下容易出问题，更重要的是——上下文是系统“替”模型找的，不是模型自己找到的，剥夺了模型的主动性。

既然Claude能自己上网搜索，为什么不能让它自己搜索代码库？于是，团队给了Claude一个Grep工具，让它自己搜索文件、自己探索、自己构建上下文。

这是一个核心的范式转变：

• 过去：系统替模型准备好所有上下文；

• 现在：给模型探索上下文的能力，让它自己找。

后来，团队又引入了“渐进式披露”的思路：让Agent通过探索，逐步发现相关的上下文——比如，Claude可以读取技能文件，这些文件又能引用其他文件，模型可以递归读取，慢慢找到自己需要的信息。

经过一年多的优化，Claude已经从“几乎无法自己构建上下文”，进化到能在多层文件中嵌套搜索，精准找到需要的内容。

4 案例4：少即是多，不新增工具也能扩展能力

目前，Claude Code只保留了约20个核心工具，团队对新增工具的门槛要求很高——因为每多一个工具，模型就多一个决策点，反而会降低效率。

举个例子：团队发现，Claude对“如何使用Claude Code本身”了解不够，比如用户问“怎么配置MCP”“斜杠命令是什么”，它经常答不好。

如果把所有相关文档都塞进系统提示，会让上下文变得臃肿，还会干扰Claude的主任务——写代码。

于是，团队又用了“渐进式披露”的思路，没有新增工具，而是做了一个“Claude Code指南子代理”：当用户问的是关于Claude Code自身的问题时，提示Claude调用这个子代理，而这个子代理专门负责搜索相关文档、返回精准答案。

虽然不是完美解决方案，但比之前好太多——关键是，在不新增工具、不增加模型决策负担的前提下，成功扩展了Claude的能力。

最后：Agent工具设计，是艺术也是科学

Thariq在文章结尾强调：如果你想找一套“构建Agent工具”的严格规则，很遗憾，没有这样的规则。

为模型设计工具，既是一门科学（需要遵循技术逻辑），也是一门艺术（需要结合模型能力、Agent目标、运行环境灵活调整）。

而最核心的方法论，只有一句话：多实验、读输出、尝新方法。像Agent一样看世界。