在 Agent 工程化落地过程中，动作空间（Action Space）设计是最具挑战性的环节之一。动作空间决定了智能体能够调用哪些能力、以何种方式与环境交互、如何完成复杂任务，直接影响 Agent 的可靠性、执行效率与适用范围。Claude 体系通过 Tool Calling 机制实现智能体交互，并提供了 bash、skills、code execution 等一系列底层原语，为开发者构建工具链提供了丰富选择，但也带来了新的问题：面对多样化的工具选项，如何为特定模型、特定场景设计最优的工具集合？是仅保留代码执行等通用工具，还是构建数十个细粒度工具覆盖所有潜在场景？工具数量、粒度、组合方式与模型能力之间应保持怎样的匹配关系？
1、以模型能力为中心的适配思想
1.1 工具选择的类比框架
工具与模型能力的匹配关系，如下面的类比框架：将复杂任务比作高难度数学问题，不同工具对应不同的辅助手段。
纸张是最低限度工具，可记录思路，但完全依赖人工计算，效率与精度受限；
计算器提升计算效率，但需要使用者掌握高级功能操作；
计算机是最强大的选择，支持编写与执行代码，实现自动化与复杂运算，但要求使用者具备编程能力。
这一类比揭示了工具设计的核心原则：不存在绝对最优的工具，只有最适配模型当前能力的工具。工具过于简单会限制模型发挥，工具过于复杂则会导致模型无法正确理解与调用，最终造成执行失败。因此，设计 Agent 工具不能从开发者主观需求出发，而必须深入理解模型的理解能力、规划能力、记忆能力与纠错能力。
1.2 以模型视角驱动设计迭代
工具设计的有效路径是：站在模型的角度思考问题，持续观察模型输出、分析失败案例、开展对比实验，逐步建立对模型能力边界的认知。在 Claude Code 开发过程中，始终坚持对模型行为进行精细化观测，记录工具调用成功率、输出格式合规性、任务理解准确度、上下文利用效率等关键指标，以此作为工具迭代的核心依据。这种以观测为基础、以实验为手段的开发模式，避免了过度工程化与盲目加工具的误区，确保每一次工具优化都能真正提升模型表现。
2、Claude 工具设计的四大实践案例与迭代教训
2.1 用户提问机制优化：从格式约束到专用工具
提升智能体与用户的信息交互效率是 Claude Code 的重要目标。传统纯文本提问方式虽然可行，但用户回答成本高、信息密度低、沟通摩擦大，为此团队开展了三轮迭代。
第一次尝试：在 ExitPlanTool 中增加参数，让模型在输出执行计划的同时附带一组问题。该方案实现成本最低，但导致模型严重困惑：计划与提问同时生成，用户回答可能与计划冲突，模型无法判断是否需要二次调用工具，任务流程出现逻辑断裂。
第二次尝试：修改输出指令，要求模型以特定 Markdown 格式列出问题，例如带括号选项的列表，便于前端解析为 UI 交互界面。该方案通用性最强，模型也能基本遵循，但输出不稳定，常出现额外语句、选项缺失、格式错乱等问题，无法工程化落地。
第三次尝试：构建独立的 AskUserQuestion 工具，允许模型在任意阶段主动调用，尤其在规划阶段显式触发。工具触发后弹出交互窗口阻塞智能体循环，等待用户输入，并强制模型输出结构化、多选项内容。该方案大幅提升沟通带宽与交互体验，模型也表现出较高的调用意愿。实践证明：即使设计再精良的工具，若模型无法理解与正确使用，也无法产生价值。
2.2 任务管理体系升级：从 Todo 清单到协同任务
Claude Code 初期采用 TodoWrite 工具实现任务管理，通过写入、更新、勾选待办事项确保模型不偏离目标。为解决模型遗忘问题，团队每 5 轮对话插入一次系统提醒，强化任务约束。但随着模型能力提升，固定待办清单从辅助工具变成能力约束：模型被提醒绑定在原有计划上，难以灵活调整；子智能体之间也无法共享与协同修改清单。
为此，团队将 TodoWrite 替换为 Task Tool。与待办清单聚焦约束行为不同，Task 面向多智能体协同，支持任务依赖定义、跨子 Agent 状态同步、动态修改与删除，完全适配高阶模型的规划与协作能力。这一迭代证明：模型能力持续进化，曾经必要的工具可能变为限制因素，开发者必须不断反思原有设计假设，避免工具落后于模型迭代。
2.3 上下文构建方式演进：从外部注入到自主搜索
早期 Claude Code 依赖 RAG 向量数据库为模型注入上下文，虽然速度快、效果稳定，但需要提前索引与环境配置，跨环境兼容性差，且上下文由系统被动提供，而非模型主动获取。随着模型能力增强，团队逐步转向自主搜索架构：通过 Grep 等工具让模型直接搜索代码库、文件系统，自主定位所需信息，构建专属上下文。
在 Agent Skill 体系中，这一思路被正式化为渐进式披露（Progressive Disclosure）：智能体通过读取技能文件，递归发现关联资源与深层信息，逐步扩展上下文，而非一次性加载全部内容。这种方式大幅降低了上下文膨胀与信息干扰，使模型能够在复杂代码库、文档库中完成多层级嵌套检索，精准获取所需信息。从被动接收上下文到主动构建上下文，标志着 Claude 从响应式助手向自主式智能体的转变。
2.4 功能扩展新模式：渐进式披露替代新增工具
Claude Code 当前内置约 20 个工具，团队坚持高门槛新增工具原则：每增加一个工具，都会提升模型决策复杂度，增加调用失败概率。因此，在需要扩展能力时，优先使用渐进式披露而非新增工具。
典型场景是用户询问 Claude Code 自身使用方法（如 MCP 配置、斜命令含义）。若将全部说明写入系统提示，会造成上下文污染，影响核心代码编写任务；若直接提供文档链接，模型会加载大量冗余信息检索答案。最终方案是构建 Claude Code Guide 子智能体：当用户询问配置与使用问题时，主模型自动调用该子智能体，由其专业化完成文档检索与答案生成。该方案在不增加工具数量的前提下，扩展了动作空间与知识覆盖范围，平衡了功能丰富度与系统简洁性，成为低干扰扩展能力的标准范式。
3、工程原则与方法论
3.1 核心设计原则
能力对齐原则：工具的粒度、复杂度、交互方式必须与底层大模型的理解能力、规划能力、工具使用能力严格匹配，不超前、不滞后，避免工具过弱限制模型或过强导致模型无法使用。
最小够用原则：优先保留少量通用核心工具（如代码执行、搜索、文件操作），避免细粒度工具爆炸导致决策困难。能用格式规范、渐进式披露、子智能体解决的问题，不新增工具。
可观测迭代原则：建立完整的工具调用监控体系，持续分析输出日志、失败案例、格式合规率，以数据驱动工具迭代，拒绝主观经验式优化。
动态适配原则：模型版本迭代后，必须重新评估现有工具集：曾经必要的约束型工具可能需要移除，协同型、规划型工具需要升级，保持动作空间与模型能力同步演进。
低干扰原则：避免无关信息占用上下文，非高频通用能力通过延迟加载、子智能体、外部文档等方式提供，采用渐进式披露减少上下文损耗。
3.2 标准化实施流程
明确场景目标与任务边界，梳理核心交互链路；
观测基线模型在无额外工具下的表现，定位能力缺口；
设计最小工具集，优先复用 bash、code execution、skills 等原生工具；
构建观测指标，开展小样本实验，评估工具调用成功率与任务完成度；
迭代优化工具接口、参数、提示与触发条件；
模型升级后，重新评估工具必要性，精简冗余工具。
4、工具设计是艺术而非科学
Agent 动作空间与工具设计不存在放之四海而皆准的固定规则，其效果高度依赖底层模型特性、任务目标与运行环境。Claude 系列开发实践表明：成功的工具设计，是工程经验、模型观测、实验迭代与场景理解的综合产物，是艺术与科学的结合。
开发者必须放弃一套工具包通吃所有场景的幻想，转向以模型为中心、以观测为基础、以实验为手段的精益开发模式：
学会像模型一样思考，理解其长处与短板；
坚持最小够用与动态适配，避免工具膨胀；
善用渐进式披露与子智能体，在不增加复杂度的前提下扩展能力；
持续跟踪模型迭代，及时淘汰过时约束。
未来，随着多智能体协同、模型原生工具调用、跨环境动作空间等技术成熟，工具设计将更加轻量化、自适应、系统化。而以模型能力为中心、持续观测与实验迭代的核心思想，将长期作为 Agent 工程化落地的关键指导原则，支撑智能体从简单任务执行走向复杂场景自主协作。
