Claude Code 学到的多 Agent 工具设计经验，以及 Shannon 已经做对了什么

最近，一位 Anthropic 工程师在 X 上的一条帖子里讲了 Claude Code 内部工具设计的演进：从简单 todo list，演进到带依赖关系、能跨 subagent 共享状态的任务图。读起来很像在读 Shannon 自己的架构文档。

Shannon 不是第一个走到这里的系统。但当彼此独立的团队收敛到同一组答案时，这些答案大概率就是底层真相。对新读者来说：Shannon 是一个用 Rust、Go、Python 构建的生产级多 Agent 平台。Shan 是它的 CLI 版本。下面我会把 Claude Code 演进中的五条经验映射到 Shannon 的架构上：三条被验证，两条暴露了真实缺口。

Todos → Tasks：多 Agent 里最难的问题

Claude Code 一开始有的是 TodoWrite：一个线性 checklist，还需要每 5 轮靠 system reminder 拉回计划，避免执行漂移。模型变强以后，Claude 能在执行中途识别出更好的路径，却又觉得自己必须遵守原来的 checklist。等 subagent 加进来，共享的线性列表就无法表达依赖关系和责任归属了。于是解决方案变成了 Tasks：有依赖、共享、且能在执行中途修改的任务系统。

Shannon 独立走到了同一个设计。Redis-backed TaskList，通过 taskHasUnmetDeps() 强制检查 depends_on。Lead 负责规划和分配，worker 负责执行和汇报；Lead 可以调用 revise_plan 动态重构计划。共享 workspace 让 Agent 可以发布所有队友都看得到的发现。几乎是 1:1 的匹配，也是最强的收敛点。

不要过度约束更聪明的模型

帮助弱模型的工具，可能会伤害强模型。Claude Code 发现，反复提醒模型 todo list，会让它僵硬地执行旧计划，而不是适应新信息。修复方式是：让系统变成可选、可修改的。

Shannon 通过收敛检测处理这个问题：consecutiveNonToolActions >= 3 时，Agent 自己判断是否完成，而不是死守固定步数。revise_plan 是逃生口；认知模式自动选择（CoT、ToT、ReAct、Debate）会根据问题调整推理方式。结论是：模型升级以后，要重新审计你的 agent prompt。曾经指导 GPT-4 的东西，到了 Opus 4 可能已经变成束缚。

结构化询问 > 自由文本问题

Claude Code 试过把问题嵌进 plan 输出里（模型会混淆），试过修改 markdown（解析不可靠），最后做成了一个专门的 AskUserQuestion 工具，提供结构化多选项。第三种成功了：结构化选项显著提高了沟通带宽。

这是 Shannon 最大的缺口。Human-in-the-loop 目前只有自由文本。它真正需要的是一个 ask_user action，通过 SSE 发送结构化选项。“我该怎么做？”和“这里有三个具体选项及其取舍”之间的差别，会把 human-in-the-loop 从瓶颈变成放大器。

Agent 上下文的渐进披露

不要把所有东西塞进 system prompt。让 Agent 通过搜索和 skill 文件发现上下文。保持 action space 小（约 20 个工具），用 subagent 承载专门知识。

Shannon 验证了这个方向。Skills 按需加载知识。MEMORY.md 索引主题文件，形成渐进式发现。每个 Agent 的角色 prompt 独立加载，而不是一个巨型 prompt。但 Shannon 在工具数量上还有缺口：注册工具约 40 个，而 Claude Code 约 20 个。即便有基于角色的过滤，有些角色仍会看到 8-9 个工具。Shannon 需要动态工具发现：一个按需列出可用工具的 meta-tool。

工具设计必须匹配模型能力

每新增一个工具，模型每一轮就多一个需要评估的选项。优先扩展现有工具，而不是新增工具。

Shannon 的浏览器架构很好地说明了这一点：cloud 里有 9 个独立工具，CLI 里是 1 个带 action 参数的工具，后者更接近 Claude Code 的单一 computer 工具设计。Cloud 也需要同样的整合。Shannon 的优势在于可扩展而不必工具爆炸：OpenAPI adapter 可以从 spec URL 自动生成工具，vendor adapter 处理 API 差异，而不扩大模型的决策空间。

这意味着什么

三条独立收敛：带依赖的任务、适应模型能力的设计、渐进披露。两个清晰缺口：结构化询问（3/10）和工具数量纪律（5/10）。

当独立团队解决同一组难题，并走到同一组模式时，这些模式大概率就是多 Agent 设计的底层真相。最可执行的结论是：模型变聪明以后，定期审计你的工具是不是过度规定了模型该怎么做。