vault: add Claude Code official multi-agent orchestration best practices (2026)

2026-06-18 08:01:31 +02:00
parent 040b94f898
commit 1c817a7cb1
1 changed files with 127 additions and 0 deletions
--- a/Resources/Claude-Code/Claude
+++ b/Resources/Claude-Code/Claude
@@ -0,0 +1,127 @@
+---
+created: "2026-06-18"
+type: resource
+tags: [resource, claude-code, multi-agent, orchestration, subagents, agent-teams, dynamic-workflows, best-practices, anthropic]
+source: "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 省去手搭。
+
+---
+
+## 来源
+
+- [How we built our multi-agent research system — Anthropic Engineering](https://www.anthropic.com/engineering/multi-agent-research-system)(90.2% / 4x·15x token / context grounding / eval / 生产经验)
+- [Orchestrate teams of Claude Code sessions — Claude Code Docs](https://code.claude.com/docs/en/agent-teams)(teams vs subagents 对比表、3-5 规模、plan 审批、hooks 门、限制)
+- [Orchestrate subagents at scale with dynamic workflows — Claude Code Docs](https://code.claude.com/docs/en/workflows)(四原语对比、16/1000 上限、`/deep-research`、`ultracode`)
+- 社区补充:[hidekazu-konishi 编排指南](https://hidekazu-konishi.com/entry/claude_code_subagents_and_orchestration_guide.html)、[addyosmani — The Code Agent Orchestra](https://addyosmani.com/blog/code-agent-orchestra/)
+
+---
+
+## Related
+
+### Resources
+- [[ECC orch- 编排家族与 v2.0 团队编排]]
+- [[ECC 编排实战手册]]
+- [[ECC 编排替代方案 (orchestrate 迁移)]]
+- [[Autonomous Loops 自主循环模式]]
+- [[Ralphinho RFC-DAG 编排模式]]
+- [[Everything Claude Code 完整指南]]
+
+### Zettelkasten
+- [[20260618073140 编排即排序门控与委派]]
+- [[Everything Claude Code Agent 编排模式]]
+- [[MCP数量与上下文窗口的反比关系]]