claude code core developer lessons action space design¶

Ch01.396 claude code core developer lessons action space design¶

📊 Level ⭐⭐ | 8.9KB | entities/claude-code-core-developer-lessons-action-space-design.md

Lessons from Building Claude Code: Seeing like an Agent¶

作者：Thariq（Claude Code 团队）| 来源：X (@trq212) | 时间：2026年2月28日

一、Action Space 才是你的产品¶

很多人做 Agent，第一反应是堆能力：接网页、接数据库、接浏览器、接10个模型，再加一堆花哨工具。真正上线后你会发现，最先出问题的往往是两件事：

深度分析¶

Action Space 设计的本质是接口契约，而非功能堆砌。Thariq 在总结 Claude Code 开发经验时指出，很多人在构建 Agent 时第一反应是不断叠加工具和能力，但真正上线后暴露的核心问题往往不是"能力不够"，而是"模型不知道什么时候该用哪个工具"以及"出了问题无法回放和定位"。这揭示了一个重要的工程认知：Agent 的 Action Space 本质上是一个接口契约系统，而不是功能清单。每一个新增工具都是对模型认知负载的增加，同时也是对系统风险面的扩展。工具的数量并不是优势，反而是复杂度的直接来源。

工具三档模型为 Agent 能力分级提供了可操作的框架。文章提出的"低风险低能力—中风险可组合—高风险高上限"三档模型，本质上是在为工具设计提供一种风险收益比的分析框架。低风险工具（如只读检索）虽然能力有限，但失败影响可控；高风险工具（如 bash、代码执行）虽然能真正"干活"，但同时带来了权限管理、状态一致性、副作用控制、可恢复性等一系列挑战。这个框架的价值在于，它帮助开发者在设计阶段就明确每个工具的风险收益特征，而不是在问题爆发后才被动应对。

渐进式披露是应对上下文腐化的核心策略。从 RAG 到 Grep 再到 Skills 的演进路径，体现了对"知识常驻上下文"这一做法的系统性反思。RAG 的问题不在于检索能力不足，而在于"上下文是你喂给模型的，而不是它自己找到的"——这意味着知识的时效性、相关性和用量都难以精确控制。渐进式披露的核心思想是：不要试图一次性把全部信息塞进 System Prompt，而是提供分层索引，让模型按需逐层展开。这种方式在保持上下文精炼的同时，还能通过文件层的更新来维护知识时效性，避免了长期运行中的上下文腐化问题。

Todo 到 Tasks 的升级反映了单 Agent 到多 Agent 协作的范式转变。Claude Code 团队早期用 Todo 列表防止模型跑偏，这在单 Agent 场景下是有效的。但随着模型能力增强和并行执行需求的引入，Todo 的副作用开始显现：模型把 todo 当作不可违背的剧本，不敢根据实际情况调整路线；多 Agent 场景下共享 todo 变成了协作瓶颈。Tasks 的核心升级在于从线性列表转向带依赖关系的 DAG（有向无环图），能够表达任务间的依赖链、状态同步机制和产物归档方案。这标志着 Agent 系统从"单线程执行"向"多线程协作"的范式转变，对应的工具设计也需要相应升级。

工具设计迭代的 7 步法体现了一种数据驱动的开发哲学。文章提出的迭代循环强调"从真实输出里找摩擦"而非"凭猜测设计"：用日志观察模型卡点和错误，先用 prompt 解决的问题就不用上工具，能用一个工具解决的就不堆 10 个。这个方法论的核心洞察是：Agent 系统的复杂之处往往不在于设计阶段难以预见，而在于上线后真实使用中暴露的细节摩擦。因此，建立快速的反馈循环和可观测性，比追求完美的预先设计更重要。

实践启示¶

优先为 Agent 设计"结构化提问"接口，而非不断堆砌工具。当模型需要用户输入时，应该设计专用的提问工具（如 AskUserQuestion），确保问题简短、选项互斥、有默认值、允许自由补充。这比让用户在自由文本中描述需求要高效得多，能显著提升交互带宽并减少模型理解错误。

用 Tasks（DAG）替代静态 Todos，尤其在有并行执行或多 Agent 场景时。Tasks 需要具备的能力包括：依赖表达（Task C 需要 Task A 和 B 完成）、状态同步（谁做了什么、做到哪了）、产物归档（每个 Task 的输出落到哪里）、失败回滚（某个 Task 失败的影响范围）。如果你的 Agent 系统还在用线性 todo 列表，应该考虑升级到支持依赖图的任务管理系统。

知识分层加载而非全量塞入 System Prompt。建议采用三层结构：第零层是 200-500 字的索引（回答"有哪些能力、入口在哪"），第一层是 500-1500 字的模式卡片（可执行的 checklist 和示例），第二层是完整手册（只在需要时加载）。同时控制递归深度，当增加搜索深度但答案质量没有提升时就应停止。

工具数量要克制，每个工具职责要单一。每新增一个工具就是增加一个分叉和一个潜在失败点。优先通过 prompt 优化可以解决的问题，不轻易上工具；必须上工具时，确保一个工具只干一件事，契约清晰，把结构化数据（schema、枚举、默认值）交给机器而不是让模型猜测。

每次模型能力升级时都要复盘现有工具，防止"拐杖"变"枷锁"。工具会过期——当模型变强后，早期为防止跑偏而设计的约束机制可能反而限制新能力。Claude Code 团队的经历表明，Todo 从防跑偏的有效工具有时反而变成了限制模型自主调整能力的枷锁。定期回顾和重构工具集，是保持 Agent 系统持续进化的关键。

重要动作必须可回放、可观测。在生产环境中，模型执行的动作需要有完整的日志和 trace 记录，包括工具参数、执行结果、时间戳等。这不仅便于问题排查和修复，也是持续优化 Agent 行为数据的基础。建议把交付物写成文件而不是只存在于聊天气泡中，便于后续审查和复用。

优先优化可恢复性而非一味扩大能力上限。便宜的重试机制、明确的前置条件、可观察的状态变化，这些可恢复性设计往往比单纯增加"能做的事"更重要。当 Agent 系统能在错误后快速恢复，比它能做更多事情但一出错就卡死要有价值得多。

建立工具设计的决策表，避免"加工具"冲动。文章提供了一个决策参考：措辞不稳优先改 prompt；需要稳定结构化输出上工具；知识量大但不常用用文件分层；需要专门查资料用子 Agent。遵循这个决策框架可以避免工具数量膨胀，同时确保每新增一个工具都有明确的必要性。