像 Agent 一样思考：从 Claude Code 架构演进看 AI Agent 工具设计
本文基于 Anthropic 架构师 Tharip 的文章《Lessons from Building Claude Code: Seeing like an Agent》，结合技术背景解析其中的核心设计思想。🤩
一、引言：行动空间的设计难题
构建 AI Agent 最难的部分之一，是设计它的行动空间（Action Space）。
Claude 通过 Tool Calling 与外部世界交互，工具原语包括 bash、skills、code execution 等。但面对这些选项，一个核心问题摆在面前：
你应该给 Agent 多少工具？一个通用的 bash？还是 50 个各司其职的专用工具？
Tharip 用了一个精妙的类比来回答这个问题------
想象你面前有一道复杂的数学题：
纸笔 → 计算器 → 电脑
（最简单） （适中） （最强大，但需要会用）给模型选择工具，就像给人选择解题工具一样------工具必须匹配其真实能力。工具不是越多越好，而是要贴合模型的认知方式和能力边界。
这就是 Claude Code 团队花了一年时间反复实验、不断调整的核心命题：像 Agent 一样思考（See like an Agent）。
二、工具设计的三个演进案例
案例一：AskUserQuestion 工具
问题： 如何让 Claude 更高效地向用户提问？
这看似简单，实则经历了三次失败：
| 尝试 | 方案 | 失败原因 |
|---|---|---|
| 第一次 | 在 ExitPlanTool 中加入问题数组 | 计划与问题混淆，逻辑自相矛盾 |
| 第二次 | 让 Claude 输出特定 Markdown 格式 | Claude 输出不稳定，格式难以保证 |
| 第三次 ✅ | 独立的 AskUserQuestion 工具 | 结构化输出，Claude 自然调用，效果好 |
最终方案的核心不只是技术实现，而是一个重要洞察：
再精妙的工具设计，如果 Claude 不理解如何调用，就毫无价值。
工具设计要符合模型的"直觉"，让它感到自然，而不是被迫执行。
案例二：TodoWrite → Task Tool 的升级
背景： Claude Code 最初给模型提供了 TodoWrite 工具，用于维护待办列表，防止模型"忘事"。系统还每隔 5 轮插入提醒，强制让 Claude 回顾目标。
这在早期模型上运行良好。但随着模型能力提升，问题出现了：
- Claude 不再需要被反复提醒
- 强制提醒反而让 Claude 误以为必须严格遵守列表，失去灵活性
- Opus 4.5 的 subagent 能力大幅提升，多个子 Agent 如何共享同一个待办列表？
于是 TodoWrite 被替换为 Task Tool：
| TodoWrite | Task Tool | |
|---|---|---|
| 核心目标 | 防止模型忘事 | Agent 间协作通信 |
| 适用场景 | 单 Agent | 多 Agent 协作 |
| 灵活性 | 低（容易变成约束） | 高（支持修改、删除、依赖关系） |
| 跨 Agent 共享 | 不支持 | 支持 |
这个案例揭示了一条关键原则：
随着模型能力提升，曾经必要的工具可能变成新的枷锁。要持续重新审视每一个工具存在的假设。
案例三：搜索接口的演进
这是整篇文章技术密度最高的部分，也是理解 Claude Code 架构哲学的核心。
搜索能力的演进经历了四个阶段：
css
RAG 向量数据库（被动接收）
↓
Grep 工具（主动搜索）
↓
Agent Skills + 渐进式披露（递归嵌套探索）
↓
Subagent 专业分工（claude-code-guide）这条演进线索，贯穿了下面两个最重要的技术概念。
三、传统 RAG 与 Agent Skills 的对比
传统 RAG 是什么？
RAG（Retrieval-Augmented Generation，检索增强生成）是早期 Claude Code 采用的上下文构建方案：
- 将整个代码库转化为向量嵌入，存入数据库
- 用户提问时，语义检索最相关的代码片段
- 将检索结果"喂给"模型作为上下文
传统 RAG 的问题
| 问题 | 说明 |
|---|---|
| 需要预索引 | 使用前必须建立向量索引，成本高 |
| 环境依赖脆弱 | 跨机器、跨环境容易出错 |
| 检索质量不稳定 | 语义相似 ≠ 逻辑相关，容易检索到"看起来像但没用"的内容 |
| 无法推理式探索 | 不能根据第一步结果决定下一步找什么 |
| 被动接收 | Claude 拿到的是系统决定给它的内容，而不是它自己找到的 |
最后一点是最根本的问题：Claude 没有参与信息获取的过程，无法主动判断"我还需要什么"。
Agent Skills 是什么？
本质上就是一个提示词管理工具。
Agent Skills 是 Anthropic 引入的一种新机制，本质上是给 Claude 看的"说明书文件"。
skill 文件
├── 描述某项能力的使用方式（如：如何查询数据库）
├── 引用其他相关文件（可递归）
└── 包含搜索指令、API 使用规范等Claude 读取 skill 文件后，可以按照其中的指引主动探索更多上下文：
css
skill 文件 A
└─ 引用 → 文件 B（API 文档）
└─ 引用 → 文件 C（鉴权说明）
└─ 引用 → 文件 D（示例代码）这种递归式文件引用，让 Claude 能够像真正的工程师一样"顺藤摸瓜"，逐层深入找到精确的上下文。
也许skills模式是ai时代开发者的"松耦合"
引用一句名言： 传统开发是讲松耦合的 ------------马保国
skills模式实现了ai时代的功能即插即用，在传统开发里只需要设计一个优雅高效的接口，就能将若干相同类型的功能函数封装，将函数调用层与代码执行层隔离。skiils模式也实现了类似的功能，大模型对skills的管理也是松耦合的，具有隔离性，避免大模型被喂入过多上下问而牛头不对马嘴。
同时用渐披漏式架构，让agent更好得处理上下文
RAG vs Agent Skills 核心对比
| 维度 | 传统 RAG | Agent Skills |
|---|---|---|
| 信息获取方式 | 被动接收 | 主动探索 |
| 探索深度 | 一次性检索 | 递归多层嵌套 |
| 推理能力 | 无（只会检索） | 有（根据结果决定下一步） |
| 环境依赖 | 需要预索引 | 零配置，读文件即可 |
| 扩展方式 | 改索引/改代码 | 写 skill 文件即可 |
| 适应性 | 依赖索引新鲜度 | 动态适配任何代码库 |
两者并非对立
值得注意的是，RAG 并没有被淘汰------它仍然适合超大规模知识库、实时性要求高的场景。在很多生产系统中（如 Cursor、GitHub Copilot），RAG 与 Agent 模式共存：
用 RAG 做粗筛，用 Agent 做精读和推理。 RAG 从"主角"变成了 Agent 工具箱里的一个工具。
四、渐进式披露：不加工具的能力扩展
什么是渐进式披露？
渐进式披露（Progressive Disclosure）借鉴自 UI 设计领域------只在需要时展示复杂信息。应用到 AI Agent 的含义是：
不在一开始就把所有信息塞给模型，而是让模型像人类工程师一样，边探索边按需获取信息。
这与人类读陌生代码库的方式完全一致------没有人会先把整个仓库背下来，而是边查边理解。
为什么需要渐进式披露？
核心问题是上下文腐烂（Context Rot）：
当 system prompt 中塞入过多不相关信息时，模型的注意力被稀释，核心任务的表现反而下降。
以 Claude Code 的自身文档为例：
- 用户偶尔会问"如何添加 MCP？"、"斜杠命令是什么？"
- 这类问题发生频率极低
- 如果把所有文档塞进 system prompt：99% 的时间都是噪音，写代码的性能下降
渐进式披露的实现
Claude Code 最终的解决方案是构建 claude-code-guide subagent：
arduino
用户问："如何添加 MCP？"
│
▼ 主 Claude 识别意图
│
▼ 触发 claude-code-guide subagent
│
┌────┴──────────────────────┐
│ subagent 内部 │
│ ├─ 按指令搜索文档 │
│ ├─ 递归读取相关文件 │
│ └─ 精准整理并返回答案 │
└───────────────────────────┘
│
▼ 主 Claude 回答用户
（此过程不污染主上下文）渐进式披露的三层价值
1. 工程价值：零工具扩展能力
| 传统方式 | 渐进式披露 |
|---|---|
| 新功能 → 新增工具 | 新功能 → 写 skill 文件或 subagent |
| 修改代码部署 | 只需增加文档/说明文件 |
| 硬编码进系统 | 动态可插拔 |
Claude Code 目前约有 20 个工具，新增门槛极高。渐进式披露让团队可以在不触碰工具数量的前提下持续扩展 Claude 的能力边界。
2. 认知价值：减少干扰，聚焦核心
主 Agent 的上下文保持干净，专注于写代码。知识型内容按需加载，互不干扰。
3. 架构价值：专业分工
每个 subagent 有专属的搜索指令和返回格式，比通用 Agent 精准得多。这是将"能力"从代码层转移到知识层的体现。
五、一年的演进轨迹
yaml
2023 早期
└─ RAG 喂给 Claude 上下文（被动）
│
▼
中期
└─ Grep 工具：Claude 主动搜索文件（一层）
│
▼
引入 Agent Skills
└─ skill 文件递归引用，多层嵌套探索
│
▼
2024
└─ subagent 专业分工，渐进式披露成为标准范式在一年时间里，Claude 从几乎无法自主构建上下文，发展到能够跨多层文件递归嵌套搜索，精准定位所需信息。
六、核心原则总结
| 原则 | 说明 |
|---|---|
| 工具匹配能力 | 工具要贴合模型的真实能力，不是越多越好 |
| Claude 要"喜欢"调用 | 工具设计要符合模型直觉，强迫调用效果差 |
| 持续重新审视 | 模型变强后，旧工具可能成为新枷锁 |
| 渐进式披露优先 | 新功能先考虑 skill/subagent，而非新增工具 |
| 避免上下文腐烂 | system prompt 只放高频必要信息 |
| 主动探索优于被动接收 | 让模型自己找上下文，而非系统代劳 |
七、结语
Tharip 在文章结尾说：
"如果你希望得到一套关于如何构建工具的刚性规则，很遗憾这篇文章给不了你。为模型设计工具，是艺术与科学的结合。它高度依赖于你使用的模型、Agent 的目标以及它运行的环境。多实验，读输出，尝试新事物。像 Agent 一样思考。"
这句话既是方法论，也是哲学。RAG 到 Skills、TodoWrite 到 Task Tool、system prompt 到渐进式披露------每一次演进背后，都是团队真正站在模型视角，观察它的困惑、理解它的能力边界后做出的决策。
工具不是给人设计的，是给模型设计的。 这或许是构建 AI Agent 最重要的一课。
甚至你可以把这篇文章的内容也写成skills🤣🤣😘
参考原文：Tharip，《Lessons from Building Claude Code: Seeing like an Agent》，Anthropic，2025