本讲摘要本讲是 SubAgent 系列的第 4 个实战、聚焦多子代理协同——前 3 讲只读 / 可执行 / 可写都是单兵作战启动 1 个、跑完、返回。本讲讲团队作战怎么用 N 个子代理同时跑并行模式或 A→B→C 顺序跑流水线模式、让 Claude Code 从单人 AI 助手升级为小型 AI 团队。本讲的三条主线:第一、什么时候需要多子代理?——3 类高价值场景并行探索省 2-3 倍时间 / 流水线分而治之各段最合适角色 / 错误恢复降级子代理接手、反过来说 3 类不需要任务简单 / 强耦合共享上下文 / 频繁来回追问。第二、两种协同模式怎么选?——并行模式主对话一句话调起 N 个子代理、各自独立工作、主对话综合适合互不依赖的探索;流水线模式Explore→Reviewer→Debugger→Test-runner适合链式依赖的修复。第三、子代理之间怎么通信?——3 种方式:文件中间结果写 .claude/pipeline/、状态state.json 记录当前阶段、队列tasks.json 待办清单;子代理间不共享上下文是设计约束也是工程优势、迫使通信显式化、可持久化、可调试。学完本讲、你应该能判断该用并行还是流水线、能设计 4 段流水线修复链、能用 3 种通信方式协调多子代理、能用主对话是项目经理的思路拆任务、派子代理、收结果、综合报告。 详细内容从单兵到团队什么时候需要多个子代理?前 3 讲我们讲了 3 类单兵子代理观察者只读、可执行、可写。每类都假设启动 1 个、跑完、返回。但现实中很多任务用 1 个子代理扛不动——要么是工作量太大1 个子代理跑 10 分钟、要么是任务需要多角色1 个子代理身兼数职 角色漂移。多子代理协同解决的正是这两个问题。但多个不等于更好——下面 3 类场景用多子代理价值最高、3 类用了反而是负优化该用多子代理的 3 类场景类型 1并行探索3 路独立、省 2-3 倍时间任务特征多个互不依赖的探索目标。比如同时摸清 auth / db / api 三个模块的代码结构、“同时比较 3 个候选方案”、“同时给 3 套实现路径打优缺点”。这些任务的特点是每个子目标独立、完全可以并行、串行做会浪费 2-3 倍时间。类型 2流水线修复链式 4 段、各段最合适的角色任务特征一个任务可以拆成 4 段、每段用最合适的子代理。比如找一个 bug 修掉:Explore找位置→ Reviewer找问题→ Debugger修→ Test-runner验。如果只用一个万能子代理、它可能找不到位置、“找不到问题”、“修错地方”、“修完没测”拆成 4 段、每段用最专的角色、效果和效率都更好。类型 3错误恢复主代理失败、降级子代理接手任务特征主代理比如 Sonnet跑某个任务超时 / 失败、降级到子代理比如 Haiku兜底重试、或者切换到另一个范式“Sonnet 写代码失败、降级到 Sonnet 写测试让 Claude 写代码”。这种代理间降级是高可用系统的常见模式。千万别用多子代理的 3 类场景类型 1任务简单——1 个子代理 5 秒能搞定的事、不需要拆成 N 个。判断标准这件事1 个子代理 1 次启动能搞定就别拆。类型 2强耦合共享上下文——多阶段共享同一上下文的需求、子代理间不共享上下文、会陷入序列化传递摘要 → 摘要丢失关键细节 → 反复重传的死循环。类型 3频繁来回追问——用户得反复先这样?好、再那样?嗯、改一下……、子代理每次启动都是新上下文、追问成本极高。并行模式3 个 explorer 同时跑并行模式是多子代理协同最简单的一类主对话说用 3 个子代理同时探索 X / Y / Z,3 个 explorer 各自独立工作、主对话拿到 3 份报告后综合成总览。并行模式的关键设计点有 4 个明确分工——3 个子代理不能探索同一件事重复劳动、也不能探索无关的事浪费算力。主对话的 prompt 要明确explorer-1 探索 auth 模块的入口和中间件、“explorer-2 探索 db 模块的 ORM 和迁移文件”、“explorer-3 探索 api 模块的路由和 schema”。统一输出格式——3 个子代理的报告格式必须一致都用 Markdown 模板 / 都用 JSON)、主对话才好综合。否则就是3 份格式不一的报告拼成一份 痛苦。独立上下文——3 个子代理之间不共享任何上下文这是 Claude Code 的设计约束、也是优势避免互相污染。主对话要确保 3 个子代理各自有完整的必要信息比如都拿到项目的 CLAUDE.md。速度对比——串行 3 分钟 vs 并行 1 分钟假设每个子代理跑 1 分钟。这 2-3 倍速度提升是并行模式的核心价值。并行模式适合探索 / 调研 / 选型类任务——这些任务的特点是没有对错、只有全面,3 个独立视角拼起来比 1 个深度视角更全面。流水线模式Explore→Reviewer→Debugger→Test-runner流水线模式是多子代理协同的进阶类把一个任务拆成 4 段、每段用最合适的子代理、段间用文件传递中间结果。这是软件工程流水线思想在 AI 协同里的应用。典型 4 段流水线Explore找位置→ Reviewer找问题→ Debugger修→ Test-runner验。4 段链式、每段用自己的 system prompt 工具白名单 输出格式。每段的输出都是下一段的输入——段间用文件显式传递、避免子代理间共享上下文。错误传播任一段失败、流水线暂停、人介入流水线有 3 个失败模式Explore 找不到项目结构不熟/ Reviewer 找不到代码复杂/ Debugger 修错权限失控/ Test-runner 跑挂回归测试失败。每段失败、流水线不应该自动继续否则会把错误传到下一段、放大问题。正确做法在每段之间加门控、读 .claude/pipeline/-*.md 看上一段输出、如果不通过、主对话弹窗让人决定继续 / 跳过 / 终止。维度并行模式流水线模式适用场景互不依赖的探索/调研/选型链式依赖的修复/构建/分析速度2-3 倍N 个子代理同时跑各段依次跑、总时间各段之和通信方式子代理间不通信各自回主对话段间用文件/state.json 显式传递失败恢复单子代理失败不影响其他任一段失败、流水线暂停、人介入典型场景“同时摸清 3 个模块”“修一个 bug 链式 4 段”子代理间的通信机制文件 vs 状态 vs 队列子代理间不共享上下文是 Claude Code 的设计约束——这看起来是限制、实际是优势迫使通信显式化、可持久化、可调试。3 种通信方式各有适用场景方式 1文件传递最常用机制每段子代理把输出写到 .claude/pipeline/-.md、下一段子代理读这个文件作为输入。优点简单、可读、可版本管理git diff 看每段输出变化、可调试出问题时直接看哪段输出错了。缺点文件多时混乱需要命名规范、不适合动态任务队列场景。适用流水线模式固定段数、固定文件路径。方式 2:state.json 状态机中级机制用 .claude/state.json 记录整个协同的当前状态——{current\_stage: 2, completed\_tasks: [01-explore], pending\_tasks: [02-review, 03-debug, 04-test], errors: []}。每段子代理读 state.json 知道自己处于哪一段、完成后更新 state.json。优点可动态调整任务列表根据前一段结果决定下一段做啥、支持跳过 / 重试 / 回退、可序列化和恢复重启流水线不丢状态。缺点比文件复杂要维护 state.json 的读写一致性、需要原子性保证多子代理同时写会冲突。适用动态流水线根据前一段结果决定下一段、长时任务可能跨多次会话。方式 3:tasks.json 任务队列高级机制用 .claude/tasks.json 当作待办任务队列——[{id: task-1, status: in\_progress, agent: explorer, input: ...}, ...]。主对话往队列里加任务、空闲的子代理从队列里取任务跑。适合任务不确定什么时候来、需要排队处理的场景。优点支持异步任务、可负载均衡多个子代理并发取任务、可暂停/恢复队列状态保存。缺点复杂度高需要调度器概念、Claude Code 本身不提供、需要主对话扮演、调试困难任务在队列里卡住不知道为啥。适用多任务并行队列里 10 个任务、3 个子代理并发跑、异步场景用户提交任务后、后台慢慢跑。3 种方式的选择心法流水线用文件、动态任务用 state.json、异步队列用 tasks.json。新手从文件开始、熟练了再升级到 state.json,tasks.json 是高级模式第 32 讲性能优化会再讲。通信方式机制优点适用场景文件传递每段写 .claude/pipeline/-.md、下段读简单、可读、可版本管理流水线模式固定段数state.json记录 current_stage / completed / pending / errors动态调整、跳过/重试/回退、可序列化动态流水线、长时任务tasks.json待办任务队列、子代理从队列取任务异步、负载均衡、暂停/恢复多任务并行、异步场景协调模式主对话是天然的协调者多子代理协同里、主对话不是被服务对象、而是项目经理。它的核心职责是 4 件拆任务——把用户的复杂需求拆成 N 个可独立执行的子任务。派子代理——为每个子任务选最合适的子代理探索用 explorer、审查用 reviewer、修用 debugger、验用 test-runner。收结果——收集各子代理的报告、统一格式主对话 prompt 里规定子代理的输出格式。综合报告——把多份报告综合成一份人类可读 机器可处理的总览、反馈给用户。主对话的协调 prompt模板实战代码里有完整版有 4 个标准段“我有一个复杂任务[用户需求]。我打算拆成 N 个子任务。”“对每个子任务、我会派一个 [子代理名] 去跑。它会输出 [格式] 的报告。”“我需要你[主对话的工作]拆任务 / 派子代理 / 收结果 / 综合报告。”“综合报告的格式[用户最终想看到的格式]”这种协调 prompt让主对话有清晰的项目经理身份、而不是被服务对象——多子代理协同能否成功、80% 取决于主对话的协调质量。3 类多子代理失败模式及应对多子代理协同有 3 类典型失败模式、需要提前设计应对失败 1结果冲突N 个子代理给出矛盾建议场景explorer-1 说auth 用 JWT,explorer-2 说auth 用 session,explorer-3 说auth 用 OAuth。3 个矛盾的答案、主对话做仲裁。应对主对话 prompt 里加如果子代理报告冲突、列出冲突点 各自的依据 我的建议——把仲裁显式化、而不是忽略冲突或随机选一个。失败 2重复劳动N 个子代理做了同一件事场景explorer-1 和 explorer-2 都探索了 auth 模块、浪费了一半算力。应对主对话 prompt 里给每个子代理明确你的边界是 X、不要探索 Y——边界明确、重复劳动就被设计层面堵死。失败 3上下文丢失关键信息在子代理间传递时丢失场景explorer 找到 3 个相关文件、Reviewer 只读了 1 个、Debugger 修了 1 个错位的文件。应对用文件显式传递不靠主对话的对话历史、文件里包含完整必要信息——文件名、行号、上下文段、问题描述。每段子代理读文件时检查信息够不够、不够就回退到上一段重跑。3 类失败模式都对应一个工程原则“把协调逻辑显式化、不靠模型概率”——子代理可能漏、可能错、可能冲突、但主对话的协调 prompt 文件传递 边界设计能让协同的失败率降到可接受范围。️ 实战代码 第 8 讲配套并行模式实战 —— 3 个 explorer 同时探索# .claude/agents/explorer-auth.md --- name: explorer-auth description: Explore the auth module (login, session, JWT, OAuth). Run when user says explore auth / 摸清认证模块. tools: Read, Grep, Glob model: haiku --- You are an auth module explorer. Find all auth-related code in the project. Output file: .claude/pipeline/01-auth.md Output format (strict): markdown # Auth Module Map ## Entry Points - file:line — function — purpose ## Middleware - ... ## Token / Session Logic - ... ## Dependencies - ... ## Notes - any unusual patterns, deprecated code, TODOs Constraints: - Only the auth module. Do NOT explore other modules. - Use Grep for auth|login|jwt|session|oauth patterns. # 主对话中一句话调起 3 个 explorer # 用 explorer-auth / explorer-db / explorer-api 同时探索三个模块, # 各自输出到 .claude/pipeline/01-{auth,db,api}.md, # 综合报告写到 .claude/pipeline/00-summary.md # 3 个 explorer 各自独立工作(并行): # explorer-auth ──── .claude/pipeline/01-auth.md # explorer-db ──── .claude/pipeline/01-db.md # explorer-api ─── .claude/pipeline/01-api.md # # 主对话收集 3 份报告,综合成总览: # summary.md 结构化整合(auth db api 三方视角,标出交集、差异、未覆盖) # 速度对比: # 串行 3 个 3 分钟 # 并行 3 个 1 分钟(2-3 倍速度提升) 第 8 讲配套流水线模式实战 —— 4 段链式修复# .claude/pipelines/fix-order-timeout.sh # 4 段流水线:Explore → Reviewer → Debugger → Test-runner # 中间结果用文件传递,每段失败流水线暂停 set -e PIPELINE_DIR.claude/pipeline/fix-order-timeout mkdir -p $PIPELINE_DIR # 段 1:Explore(找位置) echo [1/4] Explore: 找位置 claude --headless --agent explorer \ --task 找出订单超时相关的所有代码位置,写到 $PIPELINE_DIR/01-explore.md # 门控:检查输出 if [ ! -s $PIPELINE_DIR/01-explore.md ]; then echo ❌ 段 1 失败:explorer 没找到相关位置。流水线终止。 exit 1 fi echo ✅ 段 1 完成 # 段 2:Reviewer(找问题) echo [2/4] Reviewer: 找问题 claude --headless --agent code-reviewer \ --task 读 $PIPELINE_DIR/01-explore.md,审查列出的代码位置,找出超时相关的 bug,写到 $PIPELINE_DIR/02-review.md if [ ! -s $PIPELINE_DIR/02-review.md ]; then echo ❌ 段 2 失败:reviewer 没找到问题。流水线终止。 exit 1 fi echo ✅ 段 2 完成 # 段 3:Debugger(修) echo [3/4] Debugger: 修 claude --headless --agent debugger \ --task 读 $PIPELINE_DIR/02-review.md,修里面的 bug,实际修改代码,并把改动摘要写到 $PIPELINE_DIR/03-debug.md if [ ! -s $PIPELINE_DIR/03-debug.md ]; then echo ❌ 段 3 失败:debugger 没修任何东西。流水线终止。 exit 1 fi echo ✅ 段 3 完成 # 段 4:Test-runner(验) echo [4/4] Test-runner: 验 claude --headless --agent test-runner \ --task 跑测试,确认 $PIPELINE_DIR/03-debug.md 里描述的修改没破坏任何东西。报告写到 $PIPELINE_DIR/04-test.md if grep -q Failed $PIPELINE_DIR/04-test.md; then echo ❌ 段 4 失败:测试不通过。流水线终止,需要回退。 exit 1 fi echo ✅ 段 4 完成 echo echo 流水线全部完成。中间结果: ls -la $PIPELINE_DIR/ 第 8 讲配套3 种通信方式实战# 方式 1:文件传递(最简单) # 每段子代理写固定路径,下一段读固定路径 PIPELINE_DIR.claude/pipeline/$(date %s) mkdir -p $PIPELINE_DIR # 段 1 写:$PIPELINE_DIR/01-explore.md # 段 2 读:01-explore.md,写:$PIPELINE_DIR/02-review.md # 段 3 读:02-review.md,写:$PIPELINE_DIR/03-debug.md # 段 4 读:03-debug.md,写:$PIPELINE_DIR/04-test.md// 方式 2:state.json 状态机 // .claude/state.json { current_pipeline: fix-order-timeout, current_stage: 2, completed: [ {stage: 1, role: explorer, output: .claude/pipeline/.../01-explore.md, duration_s: 45} ], pending: [ {stage: 2, role: reviewer, input: 01-explore.md}, {stage: 3, role: debugger, input: 02-review.md}, {stage: 4, role: test-runner, input: 03-debug.md} ], errors: [], started_at: 2026-06-02T12:00:0008:00 } // 每段子代理启动时读 state.json,完成后更新它: { current_stage: 3, completed: [..., {stage: 2, role: reviewer, output: 02-review.md, duration_s: 30}], pending: [ {stage: 3, ...}, {stage: 4, ...} ], errors: [] }// 方式 3:tasks.json 任务队列(高级,异步场景) // .claude/tasks.json [ { id: task-001, status: in_progress, agent: explorer-auth, input: Explore the auth module, created_at: 2026-06-02T12:00:0008:00, assigned_to: agent-instance-1 }, { id: task-002, status: pending, agent: explorer-db, input: Explore the db module }, { id: task-003, status: pending, agent: test-runner, input: Run tests after fix } ] // 主对话往队列里加任务,空闲的子代理从队列里取任务跑: { id: task-001, status: completed, completed_at: 2026-06-02T12:01:3008:00, output: ... } 第 8 讲配套协调者主对话的 prompt 模板# 协调 prompt 模板(主对话用) ## 任务 [用户原始需求,比如摸清订单系统的代码结构] ## 拆任务 我打算拆成 N 个子任务: 1. [子任务 1] —— 用 [子代理 1] 2. [子任务 2] —— 用 [子代理 2] 3. [子任务 3] —— 用 [子代理 3] ## 通信 - 每段子代理输出到 [文件路径] - 下一段子代理读 [文件路径] 作为输入 - 失败处理:任一段失败,流水线暂停,弹窗让人决定 ## 综合报告 N 个子代理完成后,综合成一份总览: - 共同点(N 个子代理都同意的) - 差异点(子代理之间矛盾的) - 未覆盖(没有任何子代理探索到的) 格式:[Markdown / JSON / 表格 / 自由文本]⚠️ 常见坑⚠️ 启动了 N 个子代理但没明确分工重复劳动同一件事最常见的失败模式主对话说用 3 个 explorer 探索项目,3 个 explorer 都去探索 auth 模块——结果 3 份几乎相同的报告、1 份价值 3 份算力。原因是主对话没给边界。正确做法每个子代理的 prompt 都明确你的边界是 X、不要探索 Y——explorer-auth 只探索 auth,explorer-db 只探索 db,explorer-api 只探索 api。判断标准如果 3 个子代理的报告看起来很像、就是分工没做好。⚠️ 子代理输出格式不规范主对话拿到自然语言散文没法综合多子代理协同的常见痛点N 个子代理的报告格式不一有的用 Markdown 标题、有的用 JSON、有的用自由文本、主对话拿到 N 份格式不一致的报告、综合时无所适从。正确做法主对话的协调 prompt 里硬性规定所有子代理的输出格式用代码块模板、所有子代理的 system prompt 里也写明严格按这个格式输出。这样 N 份报告格式统一、主对话用 jq / grep / 模板就能批量处理。判断标准如果主对话综合时需要先看 N 份报告手动理解、就是格式没规范。⚠️ 流水线串行跑了本质是流水线、但写成了串行、失去并行优势新人最常犯的形式像但本质不像错误明明 4 段之间没有强依赖比如 Explore 找位置和 Reviewer 找问题可以并行、却写成了Explore 等结果 → Reviewer 等 Explore → Debugger 等 Reviewer——总时间4 段之和。正确做法画数据依赖图、能并行的段就用并行模式不能并行的必须有上游输出才用流水线。新手容易把逻辑顺序误认为执行顺序——“先找位置再找问题在逻辑上有顺序、但在执行上完全可以并行先并行跑 4 段 explorer 都找、再 reviewer 统一分析。⚠️ 没设计失败恢复A 失败 → B 等着 → 死锁多子代理协同里最阴险的失败流水线在段 2 失败了网络问题 / 子代理超时 / 输出格式不对、但段 3 还在等段 2 的输出”——死锁、流水线卡住。正确做法每段加超时和重试——段 2 跑了 5 分钟没输出、自动重试 1 次再失败就跳过 报告或终止 通知人。状态记录到 state.json、这样重启流水线能从失败点继续、不会从头跑。判断标准你的流水线有没有 timeout / retry / fallback 机制。如果没有、补上——生产环境的协同系统必须有失败恢复。 一句话备忘多子代理协同是 Claude Code 从单人 AI 助手升级为小型 AI 团队的入口——主对话当协调者、文件传递状态、流水线门控失败、9 层叠加才能让 N 个子代理既并行不悖、又失败可恢复。
本讲摘要本讲是 SubAgent 系列的第 4 个实战、聚焦多子代理协同——前 3 讲只读 / 可执行 / 可写都是单兵作战启动 1 个、跑完、返回。本讲讲团队作战怎么用 N 个子代理同时跑并行模式或 A→B→C 顺序跑流水线模式、让 Claude Code 从单人 AI 助手升级为小型 AI 团队。本讲的三条主线:第一、什么时候需要多子代理?——3 类高价值场景并行探索省 2-3 倍时间 / 流水线分而治之各段最合适角色 / 错误恢复降级子代理接手、反过来说 3 类不需要任务简单 / 强耦合共享上下文 / 频繁来回追问。第二、两种协同模式怎么选?——并行模式主对话一句话调起 N 个子代理、各自独立工作、主对话综合适合互不依赖的探索;流水线模式Explore→Reviewer→Debugger→Test-runner适合链式依赖的修复。第三、子代理之间怎么通信?——3 种方式:文件中间结果写 .claude/pipeline/、状态state.json 记录当前阶段、队列tasks.json 待办清单;子代理间不共享上下文是设计约束也是工程优势、迫使通信显式化、可持久化、可调试。学完本讲、你应该能判断该用并行还是流水线、能设计 4 段流水线修复链、能用 3 种通信方式协调多子代理、能用主对话是项目经理的思路拆任务、派子代理、收结果、综合报告。 详细内容从单兵到团队什么时候需要多个子代理?前 3 讲我们讲了 3 类单兵子代理观察者只读、可执行、可写。每类都假设启动 1 个、跑完、返回。但现实中很多任务用 1 个子代理扛不动——要么是工作量太大1 个子代理跑 10 分钟、要么是任务需要多角色1 个子代理身兼数职 角色漂移。多子代理协同解决的正是这两个问题。但多个不等于更好——下面 3 类场景用多子代理价值最高、3 类用了反而是负优化该用多子代理的 3 类场景类型 1并行探索3 路独立、省 2-3 倍时间任务特征多个互不依赖的探索目标。比如同时摸清 auth / db / api 三个模块的代码结构、“同时比较 3 个候选方案”、“同时给 3 套实现路径打优缺点”。这些任务的特点是每个子目标独立、完全可以并行、串行做会浪费 2-3 倍时间。类型 2流水线修复链式 4 段、各段最合适的角色任务特征一个任务可以拆成 4 段、每段用最合适的子代理。比如找一个 bug 修掉:Explore找位置→ Reviewer找问题→ Debugger修→ Test-runner验。如果只用一个万能子代理、它可能找不到位置、“找不到问题”、“修错地方”、“修完没测”拆成 4 段、每段用最专的角色、效果和效率都更好。类型 3错误恢复主代理失败、降级子代理接手任务特征主代理比如 Sonnet跑某个任务超时 / 失败、降级到子代理比如 Haiku兜底重试、或者切换到另一个范式“Sonnet 写代码失败、降级到 Sonnet 写测试让 Claude 写代码”。这种代理间降级是高可用系统的常见模式。千万别用多子代理的 3 类场景类型 1任务简单——1 个子代理 5 秒能搞定的事、不需要拆成 N 个。判断标准这件事1 个子代理 1 次启动能搞定就别拆。类型 2强耦合共享上下文——多阶段共享同一上下文的需求、子代理间不共享上下文、会陷入序列化传递摘要 → 摘要丢失关键细节 → 反复重传的死循环。类型 3频繁来回追问——用户得反复先这样?好、再那样?嗯、改一下……、子代理每次启动都是新上下文、追问成本极高。并行模式3 个 explorer 同时跑并行模式是多子代理协同最简单的一类主对话说用 3 个子代理同时探索 X / Y / Z,3 个 explorer 各自独立工作、主对话拿到 3 份报告后综合成总览。并行模式的关键设计点有 4 个明确分工——3 个子代理不能探索同一件事重复劳动、也不能探索无关的事浪费算力。主对话的 prompt 要明确explorer-1 探索 auth 模块的入口和中间件、“explorer-2 探索 db 模块的 ORM 和迁移文件”、“explorer-3 探索 api 模块的路由和 schema”。统一输出格式——3 个子代理的报告格式必须一致都用 Markdown 模板 / 都用 JSON)、主对话才好综合。否则就是3 份格式不一的报告拼成一份 痛苦。独立上下文——3 个子代理之间不共享任何上下文这是 Claude Code 的设计约束、也是优势避免互相污染。主对话要确保 3 个子代理各自有完整的必要信息比如都拿到项目的 CLAUDE.md。速度对比——串行 3 分钟 vs 并行 1 分钟假设每个子代理跑 1 分钟。这 2-3 倍速度提升是并行模式的核心价值。并行模式适合探索 / 调研 / 选型类任务——这些任务的特点是没有对错、只有全面,3 个独立视角拼起来比 1 个深度视角更全面。流水线模式Explore→Reviewer→Debugger→Test-runner流水线模式是多子代理协同的进阶类把一个任务拆成 4 段、每段用最合适的子代理、段间用文件传递中间结果。这是软件工程流水线思想在 AI 协同里的应用。典型 4 段流水线Explore找位置→ Reviewer找问题→ Debugger修→ Test-runner验。4 段链式、每段用自己的 system prompt 工具白名单 输出格式。每段的输出都是下一段的输入——段间用文件显式传递、避免子代理间共享上下文。错误传播任一段失败、流水线暂停、人介入流水线有 3 个失败模式Explore 找不到项目结构不熟/ Reviewer 找不到代码复杂/ Debugger 修错权限失控/ Test-runner 跑挂回归测试失败。每段失败、流水线不应该自动继续否则会把错误传到下一段、放大问题。正确做法在每段之间加门控、读 .claude/pipeline/-*.md 看上一段输出、如果不通过、主对话弹窗让人决定继续 / 跳过 / 终止。维度并行模式流水线模式适用场景互不依赖的探索/调研/选型链式依赖的修复/构建/分析速度2-3 倍N 个子代理同时跑各段依次跑、总时间各段之和通信方式子代理间不通信各自回主对话段间用文件/state.json 显式传递失败恢复单子代理失败不影响其他任一段失败、流水线暂停、人介入典型场景“同时摸清 3 个模块”“修一个 bug 链式 4 段”子代理间的通信机制文件 vs 状态 vs 队列子代理间不共享上下文是 Claude Code 的设计约束——这看起来是限制、实际是优势迫使通信显式化、可持久化、可调试。3 种通信方式各有适用场景方式 1文件传递最常用机制每段子代理把输出写到 .claude/pipeline/-.md、下一段子代理读这个文件作为输入。优点简单、可读、可版本管理git diff 看每段输出变化、可调试出问题时直接看哪段输出错了。缺点文件多时混乱需要命名规范、不适合动态任务队列场景。适用流水线模式固定段数、固定文件路径。方式 2:state.json 状态机中级机制用 .claude/state.json 记录整个协同的当前状态——{current\_stage: 2, completed\_tasks: [01-explore], pending\_tasks: [02-review, 03-debug, 04-test], errors: []}。每段子代理读 state.json 知道自己处于哪一段、完成后更新 state.json。优点可动态调整任务列表根据前一段结果决定下一段做啥、支持跳过 / 重试 / 回退、可序列化和恢复重启流水线不丢状态。缺点比文件复杂要维护 state.json 的读写一致性、需要原子性保证多子代理同时写会冲突。适用动态流水线根据前一段结果决定下一段、长时任务可能跨多次会话。方式 3:tasks.json 任务队列高级机制用 .claude/tasks.json 当作待办任务队列——[{id: task-1, status: in\_progress, agent: explorer, input: ...}, ...]。主对话往队列里加任务、空闲的子代理从队列里取任务跑。适合任务不确定什么时候来、需要排队处理的场景。优点支持异步任务、可负载均衡多个子代理并发取任务、可暂停/恢复队列状态保存。缺点复杂度高需要调度器概念、Claude Code 本身不提供、需要主对话扮演、调试困难任务在队列里卡住不知道为啥。适用多任务并行队列里 10 个任务、3 个子代理并发跑、异步场景用户提交任务后、后台慢慢跑。3 种方式的选择心法流水线用文件、动态任务用 state.json、异步队列用 tasks.json。新手从文件开始、熟练了再升级到 state.json,tasks.json 是高级模式第 32 讲性能优化会再讲。通信方式机制优点适用场景文件传递每段写 .claude/pipeline/-.md、下段读简单、可读、可版本管理流水线模式固定段数state.json记录 current_stage / completed / pending / errors动态调整、跳过/重试/回退、可序列化动态流水线、长时任务tasks.json待办任务队列、子代理从队列取任务异步、负载均衡、暂停/恢复多任务并行、异步场景协调模式主对话是天然的协调者多子代理协同里、主对话不是被服务对象、而是项目经理。它的核心职责是 4 件拆任务——把用户的复杂需求拆成 N 个可独立执行的子任务。派子代理——为每个子任务选最合适的子代理探索用 explorer、审查用 reviewer、修用 debugger、验用 test-runner。收结果——收集各子代理的报告、统一格式主对话 prompt 里规定子代理的输出格式。综合报告——把多份报告综合成一份人类可读 机器可处理的总览、反馈给用户。主对话的协调 prompt模板实战代码里有完整版有 4 个标准段“我有一个复杂任务[用户需求]。我打算拆成 N 个子任务。”“对每个子任务、我会派一个 [子代理名] 去跑。它会输出 [格式] 的报告。”“我需要你[主对话的工作]拆任务 / 派子代理 / 收结果 / 综合报告。”“综合报告的格式[用户最终想看到的格式]”这种协调 prompt让主对话有清晰的项目经理身份、而不是被服务对象——多子代理协同能否成功、80% 取决于主对话的协调质量。3 类多子代理失败模式及应对多子代理协同有 3 类典型失败模式、需要提前设计应对失败 1结果冲突N 个子代理给出矛盾建议场景explorer-1 说auth 用 JWT,explorer-2 说auth 用 session,explorer-3 说auth 用 OAuth。3 个矛盾的答案、主对话做仲裁。应对主对话 prompt 里加如果子代理报告冲突、列出冲突点 各自的依据 我的建议——把仲裁显式化、而不是忽略冲突或随机选一个。失败 2重复劳动N 个子代理做了同一件事场景explorer-1 和 explorer-2 都探索了 auth 模块、浪费了一半算力。应对主对话 prompt 里给每个子代理明确你的边界是 X、不要探索 Y——边界明确、重复劳动就被设计层面堵死。失败 3上下文丢失关键信息在子代理间传递时丢失场景explorer 找到 3 个相关文件、Reviewer 只读了 1 个、Debugger 修了 1 个错位的文件。应对用文件显式传递不靠主对话的对话历史、文件里包含完整必要信息——文件名、行号、上下文段、问题描述。每段子代理读文件时检查信息够不够、不够就回退到上一段重跑。3 类失败模式都对应一个工程原则“把协调逻辑显式化、不靠模型概率”——子代理可能漏、可能错、可能冲突、但主对话的协调 prompt 文件传递 边界设计能让协同的失败率降到可接受范围。️ 实战代码 第 8 讲配套并行模式实战 —— 3 个 explorer 同时探索# .claude/agents/explorer-auth.md --- name: explorer-auth description: Explore the auth module (login, session, JWT, OAuth). Run when user says explore auth / 摸清认证模块. tools: Read, Grep, Glob model: haiku --- You are an auth module explorer. Find all auth-related code in the project. Output file: .claude/pipeline/01-auth.md Output format (strict): markdown # Auth Module Map ## Entry Points - file:line — function — purpose ## Middleware - ... ## Token / Session Logic - ... ## Dependencies - ... ## Notes - any unusual patterns, deprecated code, TODOs Constraints: - Only the auth module. Do NOT explore other modules. - Use Grep for auth|login|jwt|session|oauth patterns. # 主对话中一句话调起 3 个 explorer # 用 explorer-auth / explorer-db / explorer-api 同时探索三个模块, # 各自输出到 .claude/pipeline/01-{auth,db,api}.md, # 综合报告写到 .claude/pipeline/00-summary.md # 3 个 explorer 各自独立工作(并行): # explorer-auth ──── .claude/pipeline/01-auth.md # explorer-db ──── .claude/pipeline/01-db.md # explorer-api ─── .claude/pipeline/01-api.md # # 主对话收集 3 份报告,综合成总览: # summary.md 结构化整合(auth db api 三方视角,标出交集、差异、未覆盖) # 速度对比: # 串行 3 个 3 分钟 # 并行 3 个 1 分钟(2-3 倍速度提升) 第 8 讲配套流水线模式实战 —— 4 段链式修复# .claude/pipelines/fix-order-timeout.sh # 4 段流水线:Explore → Reviewer → Debugger → Test-runner # 中间结果用文件传递,每段失败流水线暂停 set -e PIPELINE_DIR.claude/pipeline/fix-order-timeout mkdir -p $PIPELINE_DIR # 段 1:Explore(找位置) echo [1/4] Explore: 找位置 claude --headless --agent explorer \ --task 找出订单超时相关的所有代码位置,写到 $PIPELINE_DIR/01-explore.md # 门控:检查输出 if [ ! -s $PIPELINE_DIR/01-explore.md ]; then echo ❌ 段 1 失败:explorer 没找到相关位置。流水线终止。 exit 1 fi echo ✅ 段 1 完成 # 段 2:Reviewer(找问题) echo [2/4] Reviewer: 找问题 claude --headless --agent code-reviewer \ --task 读 $PIPELINE_DIR/01-explore.md,审查列出的代码位置,找出超时相关的 bug,写到 $PIPELINE_DIR/02-review.md if [ ! -s $PIPELINE_DIR/02-review.md ]; then echo ❌ 段 2 失败:reviewer 没找到问题。流水线终止。 exit 1 fi echo ✅ 段 2 完成 # 段 3:Debugger(修) echo [3/4] Debugger: 修 claude --headless --agent debugger \ --task 读 $PIPELINE_DIR/02-review.md,修里面的 bug,实际修改代码,并把改动摘要写到 $PIPELINE_DIR/03-debug.md if [ ! -s $PIPELINE_DIR/03-debug.md ]; then echo ❌ 段 3 失败:debugger 没修任何东西。流水线终止。 exit 1 fi echo ✅ 段 3 完成 # 段 4:Test-runner(验) echo [4/4] Test-runner: 验 claude --headless --agent test-runner \ --task 跑测试,确认 $PIPELINE_DIR/03-debug.md 里描述的修改没破坏任何东西。报告写到 $PIPELINE_DIR/04-test.md if grep -q Failed $PIPELINE_DIR/04-test.md; then echo ❌ 段 4 失败:测试不通过。流水线终止,需要回退。 exit 1 fi echo ✅ 段 4 完成 echo echo 流水线全部完成。中间结果: ls -la $PIPELINE_DIR/ 第 8 讲配套3 种通信方式实战# 方式 1:文件传递(最简单) # 每段子代理写固定路径,下一段读固定路径 PIPELINE_DIR.claude/pipeline/$(date %s) mkdir -p $PIPELINE_DIR # 段 1 写:$PIPELINE_DIR/01-explore.md # 段 2 读:01-explore.md,写:$PIPELINE_DIR/02-review.md # 段 3 读:02-review.md,写:$PIPELINE_DIR/03-debug.md # 段 4 读:03-debug.md,写:$PIPELINE_DIR/04-test.md// 方式 2:state.json 状态机 // .claude/state.json { current_pipeline: fix-order-timeout, current_stage: 2, completed: [ {stage: 1, role: explorer, output: .claude/pipeline/.../01-explore.md, duration_s: 45} ], pending: [ {stage: 2, role: reviewer, input: 01-explore.md}, {stage: 3, role: debugger, input: 02-review.md}, {stage: 4, role: test-runner, input: 03-debug.md} ], errors: [], started_at: 2026-06-02T12:00:0008:00 } // 每段子代理启动时读 state.json,完成后更新它: { current_stage: 3, completed: [..., {stage: 2, role: reviewer, output: 02-review.md, duration_s: 30}], pending: [ {stage: 3, ...}, {stage: 4, ...} ], errors: [] }// 方式 3:tasks.json 任务队列(高级,异步场景) // .claude/tasks.json [ { id: task-001, status: in_progress, agent: explorer-auth, input: Explore the auth module, created_at: 2026-06-02T12:00:0008:00, assigned_to: agent-instance-1 }, { id: task-002, status: pending, agent: explorer-db, input: Explore the db module }, { id: task-003, status: pending, agent: test-runner, input: Run tests after fix } ] // 主对话往队列里加任务,空闲的子代理从队列里取任务跑: { id: task-001, status: completed, completed_at: 2026-06-02T12:01:3008:00, output: ... } 第 8 讲配套协调者主对话的 prompt 模板# 协调 prompt 模板(主对话用) ## 任务 [用户原始需求,比如摸清订单系统的代码结构] ## 拆任务 我打算拆成 N 个子任务: 1. [子任务 1] —— 用 [子代理 1] 2. [子任务 2] —— 用 [子代理 2] 3. [子任务 3] —— 用 [子代理 3] ## 通信 - 每段子代理输出到 [文件路径] - 下一段子代理读 [文件路径] 作为输入 - 失败处理:任一段失败,流水线暂停,弹窗让人决定 ## 综合报告 N 个子代理完成后,综合成一份总览: - 共同点(N 个子代理都同意的) - 差异点(子代理之间矛盾的) - 未覆盖(没有任何子代理探索到的) 格式:[Markdown / JSON / 表格 / 自由文本]⚠️ 常见坑⚠️ 启动了 N 个子代理但没明确分工重复劳动同一件事最常见的失败模式主对话说用 3 个 explorer 探索项目,3 个 explorer 都去探索 auth 模块——结果 3 份几乎相同的报告、1 份价值 3 份算力。原因是主对话没给边界。正确做法每个子代理的 prompt 都明确你的边界是 X、不要探索 Y——explorer-auth 只探索 auth,explorer-db 只探索 db,explorer-api 只探索 api。判断标准如果 3 个子代理的报告看起来很像、就是分工没做好。⚠️ 子代理输出格式不规范主对话拿到自然语言散文没法综合多子代理协同的常见痛点N 个子代理的报告格式不一有的用 Markdown 标题、有的用 JSON、有的用自由文本、主对话拿到 N 份格式不一致的报告、综合时无所适从。正确做法主对话的协调 prompt 里硬性规定所有子代理的输出格式用代码块模板、所有子代理的 system prompt 里也写明严格按这个格式输出。这样 N 份报告格式统一、主对话用 jq / grep / 模板就能批量处理。判断标准如果主对话综合时需要先看 N 份报告手动理解、就是格式没规范。⚠️ 流水线串行跑了本质是流水线、但写成了串行、失去并行优势新人最常犯的形式像但本质不像错误明明 4 段之间没有强依赖比如 Explore 找位置和 Reviewer 找问题可以并行、却写成了Explore 等结果 → Reviewer 等 Explore → Debugger 等 Reviewer——总时间4 段之和。正确做法画数据依赖图、能并行的段就用并行模式不能并行的必须有上游输出才用流水线。新手容易把逻辑顺序误认为执行顺序——“先找位置再找问题在逻辑上有顺序、但在执行上完全可以并行先并行跑 4 段 explorer 都找、再 reviewer 统一分析。⚠️ 没设计失败恢复A 失败 → B 等着 → 死锁多子代理协同里最阴险的失败流水线在段 2 失败了网络问题 / 子代理超时 / 输出格式不对、但段 3 还在等段 2 的输出”——死锁、流水线卡住。正确做法每段加超时和重试——段 2 跑了 5 分钟没输出、自动重试 1 次再失败就跳过 报告或终止 通知人。状态记录到 state.json、这样重启流水线能从失败点继续、不会从头跑。判断标准你的流水线有没有 timeout / retry / fallback 机制。如果没有、补上——生产环境的协同系统必须有失败恢复。 一句话备忘多子代理协同是 Claude Code 从单人 AI 助手升级为小型 AI 团队的入口——主对话当协调者、文件传递状态、流水线门控失败、9 层叠加才能让 N 个子代理既并行不悖、又失败可恢复。
![[C++]内存管理：串顺序存储的内存回收](http://pic.xiahunao.cn/yaotu/[C++]内存管理：串顺序存储的内存回收)
