Seeing Like an Agent: How We Design Tools in Claude Code — 精读笔记
核心命题
给 Agent 设计工具，关键不是”做最强的工具”，而是做匹配模型当前能力的工具。能力变了，工具也要跟着变。设计方法论不是一次性正确，而是持续观察模型输出、持续迭代。
“You learn to see like an agent.” — 你学会像 Agent 一样看。
四个案例
1. AskUserQuestion — 同一需求的三次迭代
需求：提升 Claude 向用户提问的能力（elicitation），降低用户回答摩擦。
| 迭代 | 方案 | 结果 | 失败原因 |
|---|---|---|---|
| v1 | 给 ExitPlanTool 加 questions 参数 | 失败 | 一个工具承载两个语义（“已决定” + “有疑问”），模型困惑 |
| v2 | 特殊 Markdown 格式输出问题 | 失败 | 自由文本格式不稳定，模型经常漂移 |
| v3 | 独立工具 + 模态框阻塞 | 成功 | 语义清晰，模型”喜欢”调用 |
关键洞察： - 一个工具不应承载语义矛盾的两个功能 - 结构化输出的责任放在 tool schema 上，不要放在 prompt engineering 上 - 模型对工具有”偏好”——设计得好的工具模型会自然倾向调用；模型不理解怎么调用的工具，设计再好也白搭
2. Todos → Tasks — 工具也有保质期
- 早期模型需要 TodoWrite + 每 5 轮系统提醒来保持方向
- 模型能力提升后，Todo 列表反而限制了模型（不敢偏离清单、子 Agent 无法协作）
- 替换为 Task 工具：支持依赖、跨子 Agent 共享、可修改删除
核心教训：“As model capabilities increase, the tools that your models once needed might now be constraining them.”
实用建议：只支持少量能力相近的模型，工具设计可以聚焦。
3. 搜索界面 — 从”喂上下文”到”自己找上下文”
演化路径：RAG 预索引 → Grep 工具自搜 → Skills 渐进式披露（progressive disclosure）
关键转变：上下文应该是模型自己找的，不是被塞给它的。模型越聪明，给它搜索工具的 ROI 越高。Skills 引入了递归文件引用机制，让模型沿引用链逐层发现上下文。
4. Claude Code Guide 子 Agent — 不加工具也能扩能力
Claude Code 约 20 个工具，团队经常审视每个是否必要。加新工具的门槛高，因为每多一个选项就多一份模型的认知负担。
解决”Claude 不了解自身功能”的问题： - 塞 system prompt → 上下文腐蚀 ✗ - 给文档链接自查 → 大段文档涌入主上下文 ✗ - 子 Agent 代查，只传答案回来 → 主上下文干净 ✓
设计原则提炼
- 工具要匹配模型能力形状：不是做最强的工具，是做模型用得顺的工具
- 模型偏好是验证标准：模型”喜欢”调用 = 设计成功；模型不理解怎么调用 = 设计失败
- 工具有保质期：定期审视，模型变强后曾经有用的工具可能变成约束
- 认知负担最小化：能不加工具就不加，用渐进式披露（子 Agent / Skills）代替
- 让模型主动构建上下文：给搜索工具比塞上下文更好
- 一个工具一个语义：不要让一个工具承载矛盾的功能
亮点
- 四个案例全是失败→迭代→成功的真实路径，不是事后合理化
- “模型喜不喜欢调用”作为验证标准，是 craft 层面的重要经验
- 工具保质期概念——今天帮你的工具，明天可能限制你
缺失
- 没有讨论工具之间的交互效应（20 个工具的组合爆炸问题）
- 没有量化数据（如 AskUserQuestion 上线前后的 elicitation 成功率）
- “看模型输出来判断工具好不好”偏 craft，缺少系统化评估框架
关联
- → 另见
Learning/Agent Building/07-writing-tools-for-agents.md（通用工具设计方法论） - → 另见
Learning/Agent Building/02-context-engineering.md（上下文工程与工具设计的交叉）