kai/knowledge-base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
60155ec1cc84e54ad026423c63ed270c607c9c63
knowledge-base/4 - Resources/Claude-Code/Claude Code 官方多Agent编排最佳实践 (2026).md

9.7 KiB
Raw Blame History

created, type, tags, source
created type tags source
2026-06-18 resource
resource
claude-code
multi-agent
orchestration
subagents
agent-teams
dynamic-workflows
best-practices
anthropic
https://www.anthropic.com/engineering/multi-agent-research-system

Claude Code 官方多Agent编排最佳实践 (2026)

一手来源:Anthropic 工程博客《How we built our multi-agent research system》+ Claude Code 官方文档(agent-teams / workflows / sub-agents)。这篇讲的是 Claude Code/Anthropic 官方的通用编排原语与原则,和 ECC 仓库自带的 ECC orch- 编排家族与 v2.0 团队编排、ECC 编排实战手册 互补(ECC 是这些原则在单仓库编码上的落地)。

一、先选对原语:三种原生编排方式

2026 年 Claude Code 把"多 agent"拆成三个层次分明的原语,核心区别是计划掌握在谁手里:

Subagents Agent Teams(实验性) Dynamic Workflows
是什么 主 agent spawn 的工人 一个 lead 督导多个对等 session 运行时执行的 JS 脚本
谁决定下一步 Claude,逐轮 lead,逐轮 脚本本身
中间结果存哪 Claude 上下文窗口 共享任务列表 脚本变量(不进上下文)
agent 间通信 ❌ 只能向主 agent 汇报 ✅ 队友互相发消息 脚本协调
规模 每轮几个 一把(3-5)长跑对等体 几十到几百 / 次
中断 重启该轮 队友继续跑 同会话内可恢复
Token 成本 较低(结果摘要回传) 高(每队友独立实例) 高(可几百 agent)

选择规则:

  • Subagents —— 要快、聚焦、只关心结果的工人(研究、验证、并行审查)。先用内置的 Explore/Plan/general-purpose,反复 spawn 同一个再定制 YAML(锁定 model + system prompt,成本可预测)。
  • Agent Teams —— 工人需要互相分享发现、互相挑战、自协调时(竞争性假设 debug、跨前后端协作)。需开 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1(实验性,默认关闭)。
  • Dynamic Workflows —— 一个会话协调不过来、或想把编排固化成可复用、可重跑的脚本时(全库 bug 扫描、500 文件迁移、需交叉验证的研究)。/deep-research 是内置范例;ultracode 关键词或 /effort ultracode 触发。

把"计划"搬进代码的额外好处:workflow 能施加可重复的质量模式——让独立 agent 对抗式互审彼此的发现、或从多个角度起草方案再相互权衡,比单遍更可信。

二、Anthropic 官方 orchestrator-worker 核心原则

来自他们生产研究系统的实战教训:

  1. 多 agent 不是万能,看任务形态

    • 赢:广度优先、可并行、信息超单上下文、要接很多复杂工具。Opus 领队 + Sonnet 工人比单 Opus 高 90.2%(内部研究评测)。
    • 输 / 别用:需要所有 agent 共享上下文、或 agent 间强依赖的任务——大多数编码任务属于此类。顺序、紧耦合的工作并行没收益。

  2. 成本要算账:agent 比 chat 用 ~4 倍 token,多 agent 系统 ~15 倍。只有任务价值撑得起才用。Token 用量本身解释了 80% 的成功率差异;"升级到更强模型,比把 token 预算翻倍更划算"。

  3. 显式教会编排者怎么委派:别只说"研究一下 X"。给每个子 agent:目标、输出格式、工具指引、清晰边界。模糊委派导致重复和遗漏。把努力随复杂度缩放写进 prompt(简单查证 1 agent / 3-10 工具调用;对比类 2-4 agent / 各 10-15 次)。

  4. 上下文接地(context grounding):给每个子 agent 精确、相关的最小上下文,而不是把整个领队对话史全塞过去——既浪费又常常适得其反。构造精瘦、定向的上下文包。

  5. 并行两层:领队一次起 3-5 个子 agent(而非串行)+ 每个子 agent 同时用 3+ 工具 → 复杂查询提速最多 90%。

    • 当前限制:领队同步等每批子 agent 完成才推进,是瓶颈;异步执行仍是未解难题。

  6. 评估从小做起:~20 条代表真实用法的查询即可起步(prompt 一调可能 30%→80%,效应大到几个用例就看得出)。用 LLM-as-judge(单次调用,0.0-1.0 打分 + pass/fail)最稳、最贴人判断。别跳过人测——人能发现 eval 漏掉的边缘案例(幻觉、系统故障、偏好 SEO 内容而非权威源)。对会改状态的 agent,评估最终状态而非中间步骤。

  7. 生产可靠性:能从出错处断点续跑而非从头重来;加全链路 tracing 诊断失败;用 rainbow deployment(新旧版本并存、渐进切流)避免打断在跑的 agent;让 Claude 自己当 prompt 工程师诊断失败模式(工具描述自优化曾带来后续 agent 完成时间降 40%)。

  8. 安全三件套:最小必要权限、优先可逆操作而非破坏性操作、高风险决策保留人类审批检查点。

三、可直接照做的数字化实践(官方文档)

  • 团队/并行规模 3-5 个起步,每个工人 5-6 个任务。"三个专注的队友常胜过五个分散的。"15 个独立任务→3 个工人是好起点。
  • 任务粒度:太小→协调开销盖过收益;太大→工人跑太久不回检、浪费风险高。自包含、能产出清晰交付物(一个函数 / 一个测试文件 / 一次审查)为佳。
  • 避免文件冲突:让每个工人拥有不同的文件集,否则互相覆盖。
  • 从研究/审查类入手:边界清晰、不写代码的任务(审 PR、调研库、查 bug)最能体现并行价值,又没有并行写代码的协调坑。
  • 风险任务上 plan 审批门:队友先在只读 plan 模式出方案,lead 批准后才动手(可用 prompt 给 lead 判据,如 "only approve plans that include test coverage")。
  • 用 hooks 做质量门(agent teams):TeammateIdle / TaskCreated / TaskCompleted 退出码 2 可拦截并反馈、保持工人继续干。
  • 角色复用:同一个 subagent 定义(如 security-reviewer)既能当委派子 agent,也能当团队队友(队友会继承其 tools 白名单和 model,定义体追加进 system prompt;但 skills/mcpServers 字段当队友时不生效)。
  • 给足上下文:队友自动加载 CLAUDE.md / MCP / skills,但不继承 lead 的对话史——任务细节要写进 spawn prompt。
  • Workflow 硬上限:并发 ≤16 agent,单次总计 ≤1000 agent;workflow 脚本本身不能直接读写文件或跑 shell(由它编排的 agent 来做);先在小切片(一个目录 / 一个窄问题)上跑估成本。

两个最高频的质量组合(跨三种原语通用)

  • 多镜头并行审查:同一份改动让 security / performance / test-coverage 三个不同视角 agent 并行看,领队综合。多样性能抓到单一审查者漏掉的失败模式。
  • 对抗式假设收敛:多个独立调查者各执一个假设、被明确要求互相证伪(像科学辩论),存活下来的理论才更可能是真因——对抗顺序调查的 anchoring bias。

四、反模式

  • 把紧耦合编码任务硬塞多 agent —— 共享上下文需求会让它比单 agent 更差更贵。
  • 把整个领队上下文复制给每个子 agent(违反 context grounding)。
  • 无退出条件的循环;任务状态不回写导致依赖卡死(agent teams 已知限制)。
  • 让团队长时间无人值守 —— 要盯进度、纠偏、随时综合。
  • 默认就上最重的方案 —— 把编排模式匹配到任务,而非一律 agent teams。

五、与 ECC / 自建编排的关系

维度 官方原语 ECC 落地
单仓库编码全流程 subagents + 两道审批 ECC orch- 编排家族与 v2.0 团队编排 的 orch-pipeline
团队看板 / 合并门 agent teams 共享任务列表 team-agent-orchestration(Kanban + merge gate)
脚本化大规模 fan-out dynamic workflows ECC 的 dmux / orchestrate-worktrees.js(tmux 路线,见 ECC 编排实战手册)
评审者≠作者 多镜头 / 对抗审查 Santa Loop 双评审、Ralphinho(Ralphinho RFC-DAG 编排模式)
自治长跑 续跑 + 检查点 Autonomous Loops 自主循环模式

一句话:官方给的是原语和原则(subagents / teams / workflows + orchestrator-worker 七条);ECC 给的是把这些原则固化成可装的 skill/命令。两者读法:先用官方原则判断"该不该并行、怎么委派",再用 ECC 的现成 skill 省去手搭。

来源

Related

Resources

Zettelkasten