graph TB
    subgraph "Coordinator Layer"
        A[主Agent<br/>Coordinator] --> B{任务分析}
    end

    subgraph "Dispatch Layer"
        B -->|代码搜索| C[Explore Agent]
        B -->|架构设计| D[Plan Agent]
        B -->|代码实现| E[General-purpose Agent]
        B -->|后台任务| F[Background Agent]
    end

    subgraph "Isolation Layer"
        C --> G[主Worktree]
        D --> G
        E --> H[隔离Worktree]
        F --> I[独立Worktree]
    end

    subgraph "Aggregation Layer"
        G --> J[结果聚合]
        H --> J
        I --> J
        J --> K[主Agent<br/>继续处理]
    end

    style A fill:#4A90D9,color:#fff
    style C fill:#50C878,color:#fff
    style D fill:#FFD700,color:#333
    style E fill:#FF6B6B,color:#fff
    style F fill:#9B59B6,color:#fff
    style K fill:#4A90D9,color:#fff

单文件修改         → 主Agent直接做
2-3个文件的搜索    → Explore SubAgent
5+模块并行重构     → 多个General-purpose SubAgent + Worktree
需要实时协调的团队  → Agent Teams（邮箱通信）
长时间后台任务     → Background Agent

// Task tool参数
{
  subagent_type: "Explore",
  description: "搜索认证模块",
  prompt: "在src/auth/目录下找到所有JWT相关的中间件函数，列出文件路径和函数签名",
  model: "haiku"  // 默认就是haiku，可省略
}

# 在Claude Code交互模式中输入：
> 用Explore Agent搜索整个项目，列出所有数据库模型文件及其字段定义

# 等效的-p模式：
claude -p "使用Task tool启动Explore类型的subagent，搜索项目中所有数据库模型定义（包括schema.prisma、models/*.ts、entities/*.ts），输出每个模型的名称、字段列表和关联关系"

claude -p "启动Plan类型的subagent分析src/monolith/目录，设计将其拆分为5个微服务的方案，包括：
1. 每个微服务的职责边界
2. 服务间通信方式（同步/异步）
3. 数据库拆分策略
4. 迁移顺序和依赖关系
输出为结构化的实施计划"

// 关键参数
{
  subagent_type: "general-purpose",
  description: "重构认证模块",
  prompt: "将src/auth/下的所有JWT逻辑迁移到src/middleware/jwt.ts...",
  isolation: "worktree"  // 创建独立worktree，防止冲突
}

sequenceDiagram
    participant Main as 主Agent
    participant WT as Git Worktree
    participant Sub as SubAgent

    Main->>WT: git worktree add .claude/worktrees/feat-auth
    WT->>Sub: 切换工作目录到worktree
    Sub->>Sub: 在隔离环境中修改文件
    Sub->>Sub: 运行测试验证
    Sub->>Main: 返回结果 + worktree路径
    Main->>Main: 审查变更
    Main->>WT: git merge 或 丢弃worktree

{
  subagent_type: "general-purpose",
  description: "运行完整测试套件",
  prompt: "执行npm run test:all并分析失败的测试用例...",
  run_in_background: true  // 关键参数
}

1. 创建 → 立即返回output_file路径
2. 执行中 → 主Agent继续处理其他任务
3. 完成 → 系统自动通知主Agent
4. 获取结果 → 使用TaskOutput工具读取

flowchart LR
    A[任务分解] --> B[Agent 1<br/>模块A重构]
    A --> C[Agent 2<br/>模块B重构]
    A --> D[Agent 3<br/>模块C重构]
    A --> E[Agent 4<br/>测试编写]

    B --> F[结果聚合]
    C --> F
    D --> F
    E --> F

    F --> G[冲突检测]
    G --> H[合并/解决冲突]
    H --> I[集成验证]

    style A fill:#4A90D9,color:#fff
    style F fill:#FFD700,color:#333
    style I fill:#50C878,color:#fff

# 先让Plan Agent分析哪些文件需要修改
claude -p "分析以下5个模块中哪些TypeScript文件存在隐式any类型：
- src/api/
- src/services/
- src/utils/
- src/models/
- src/controllers/
输出每个模块需要修改的文件数量和预估复杂度"

# 在Claude Code中输入：

请并行启动5个general-purpose SubAgent，每个处理一个模块的TypeScript严格模式迁移：

Agent 1 (src/api/): 为所有请求处理函数添加参数和返回值类型
Agent 2 (src/services/): 修复业务逻辑层的隐式any
Agent 3 (src/utils/): 为工具函数添加泛型约束
Agent 4 (src/models/): 确保数据模型的类型完整性
Agent 5 (src/controllers/): 补全控制器层的类型定义

每个Agent使用worktree隔离，完成后运行该模块的单元测试。

// 主Agent自动收集所有SubAgent的结果
// 典型结果结构：
[
  { agent: "Agent 1", status: "success", files_modified: 12, tests_passing: true },
  { agent: "Agent 2", status: "success", files_modified: 8, tests_passing: true },
  { agent: "Agent 3", status: "partial", files_modified: 5, tests_passing: false, 
    error: "src/utils/validators.ts:23 - circular type reference" },
  { agent: "Agent 4", status: "success", files_modified: 3, tests_passing: true },
  { agent: "Agent 5", status: "success", files_modified: 15, tests_passing: true }
]

# 查看worktree列表
git worktree list

# 检查各worktree的变更
for wt in .claude/worktrees/*/; do
  echo "=== $wt ==="
  git -C "$wt" diff --stat
done

# 合并成功的worktree
git -C .claude/worktrees/agent-1 merge --no-edit feat/api-types
git -C .claude/worktrees/agent-2 merge --no-edit feat/services-types

# 处理失败的worktree（手动介入）
git -C .claude/worktrees/agent-3 diff src/utils/validators.ts

# 环境变量启用
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# 或在.claude/settings.json中配置
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

graph LR
    subgraph "SubAgent模式"
        SA[主Agent] --> SB[SubAgent 1]
        SA --> SC[SubAgent 2]
        SB -->|返回结果| SA
        SC -->|返回结果| SA
    end

    subgraph "Agent Teams模式"
        TA[Agent A] <-->|邮箱消息| TB[Agent B]
        TA <-->|邮箱消息| TC[Agent C]
        TB <-->|邮箱消息| TC
    end

    style SA fill:#4A90D9,color:#fff
    style TA fill:#FF6B6B,color:#fff
    style TB fill:#FF6B6B,color:#fff
    style TC fill:#FF6B6B,color:#fff

// Agent A 发送消息给 Agent B
// 在Agent A的会话中：
"请通过邮箱通知负责前端模块的Agent，API接口已经调整完毕，新增了以下端点..."

// Agent B 检查邮箱
// 在Agent B的会话中：
"检查你的邮箱，看是否有来自后端Agent的API变更通知"

# .claude/team-roles.yml 示例
team:
  name: "fullstack-team"
  members:
    - role: "coordinator"
      description: "任务分解和进度跟踪"
      focus: ["任务分配", "冲突调解", "集成验证"]

    - role: "backend-dev"
      description: "后端API和数据库开发"
      focus: ["API端点", "数据库迁移", "业务逻辑"]

    - role: "frontend-dev"
      description: "前端UI和状态管理"
      focus: ["组件开发", "状态管理", "API集成"]

    - role: "qa-engineer"
      description: "测试编写和质量保障"
      focus: ["单元测试", "集成测试", "E2E测试"]

src/
├── routes/
│   ├── users.ts      # v1用户路由
│   ├── products.ts   # v1产品路由
│   └── orders.ts     # v1订单路由
├── controllers/
│   ├── userController.ts
│   ├── productController.ts
│   └── orderController.ts
├── middleware/
│   ├── auth.ts
│   └── validation.ts
└── types/
    └── api.ts

#!/bin/bash
# migrate-api-v2.sh - 使用Claude Code的多Agent编排进行API迁移

# 阶段1：分析（Plan Agent）
echo "=== Phase 1: Analysis ==="
claude -p --output-format json \
  "启动Plan subagent分析当前API结构。读取src/routes/、src/controllers/和src/types/api.ts，输出：
1. 每个端点的当前签名
2. 需要变更的字段列表
3. 依赖关系图
将结果保存到.claude/migration-plan.md" \
  > .claude/analysis-result.json

# 等待分析完成
ANALYSIS_EXIT=$?
if [ $ANALYSIS_EXIT -ne 0 ]; then
  echo "Analysis failed!"
  exit 1
fi

# 阶段2：并行迁移（Fan-out）
echo "=== Phase 2: Parallel Migration ==="

# 使用-p模式启动3个并行Claude Code实例
claude -p \
  "使用general-purpose subagent在worktree中完成users模块的API v2迁移：
1. 创建src/routes/v2/users.ts
2. 更新src/controllers/userController.ts
3. 确保向后兼容v1端点
4. 运行npm test -- --grep 'user'
使用worktree隔离" &
PID_USER=$!

claude -p \
  "使用general-purpose subagent在worktree中完成products模块的API v2迁移：
1. 创建src/routes/v2/products.ts
2. 更新src/controllers/productController.ts
3. 确保向后兼容v1端点
4. 运行npm test -- --grep 'product'
使用worktree隔离" &
PID_PRODUCT=$!

claude -p \
  "使用general-purpose subagent在worktree中完成orders模块的API v2迁移：
1. 创建src/routes/v2/orders.ts
2. 更新src/controllers/orderController.ts
3. 确保向后兼容v1端点
4. 运行npm test -- --grep 'order'
使用worktree隔离" &
PID_ORDER=$!

# 等待所有并行任务完成
wait $PID_USER
RESULT_USER=$?
wait $PID_PRODUCT
RESULT_PRODUCT=$?
wait $PID_ORDER
RESULT_ORDER=$?

echo "User module: $([ $RESULT_USER -eq 0 ] && echo 'SUCCESS' || echo 'FAILED')"
echo "Product module: $([ $RESULT_PRODUCT -eq 0 ] && echo 'SUCCESS' || echo 'FAILED')"
echo "Order module: $([ $RESULT_ORDER -eq 0 ] && echo 'SUCCESS' || echo 'FAILED')"

# 阶段3：集成（主Agent）
echo "=== Phase 3: Integration ==="
claude -p \
  "检查所有worktree中的变更，合并到主分支：
1. 列出所有worktree: git worktree list
2. 检查每个worktree的测试结果
3. 合并成功的worktree变更
4. 更新src/routes/index.ts注册v2路由
5. 更新API类型定义src/types/api.ts
6. 运行完整测试套件: npm test
7. 如果测试通过，清理worktree"

# 在Claude Code交互模式中，一条消息触发多Agent并行：

请并行启动3个general-purpose SubAgent，分别处理以下模块的API v2迁移：

模块1 - Users:
- 创建 src/routes/v2/users.ts（新的v2端点）
- 更新 src/controllers/userController.ts（支持v2格式）
- 保留v1路由的向后兼容

模块2 - Products:
- 创建 src/routes/v2/products.ts
- 更新 src/controllers/productController.ts
- 保留v1路由的向后兼容

模块3 - Orders:
- 创建 src/routes/v2/orders.ts
- 更新 src/controllers/orderController.ts
- 保留v1路由的向后兼容

每个Agent使用worktree隔离工作。所有Agent完成后：
1. 聚合结果
2. 更新路由注册文件
3. 运行完整测试套件
4. 报告每个模块的状态

flowchart TD
    A[3个SubAgent完成] --> B{所有测试通过?}
    B -->|是| C[合并Worktree]
    B -->|否| D[分析失败原因]
    D --> E{可自动修复?}
    E -->|是| F[启动修复Agent]
    E -->|否| G[标记待人工处理]
    F --> B
    C --> H[运行集成测试]
    H --> I{集成测试通过?}
    I -->|是| J[清理Worktree<br/>完成迁移]
    I -->|否| K[回滚+分析冲突]
    K --> L[手动解决冲突]

    style J fill:#50C878,color:#fff
    style G fill:#FF6B6B,color:#fff
    style L fill:#FFD700,color:#333

请执行MapReduce模式的批量操作：

Map阶段：
- 扫描src/下所有*.test.ts文件
- 每个文件分配一个Explore SubAgent
- 每个Agent分析其测试文件的质量（覆盖率、断言数量、边界情况）

Reduce阶段：
- 聚合所有Agent的分析结果
- 按模块统计测试质量分数
- 输出优先改进的前10个测试文件

请按流水线模式执行以下步骤，每步完成后再启动下一步：

Step 1 (Plan Agent): 分析数据库schema变更的影响范围
Step 2 (General-purpose): 执行数据库迁移脚本
Step 3 (General-purpose): 更新所有受影响的TypeScript类型定义
Step 4 (General-purpose): 修复因类型变更导致的编译错误
Step 5 (Background Agent): 运行完整测试套件并生成报告

每一步开始前确认上一步已成功完成。

请并行启动以下后台任务，然后持续监控进度：

后台任务1: 运行完整E2E测试套件（预计10分钟）
后台任务2: 执行npm audit安全检查
后台任务3: 运行性能基准测试

启动后，每完成一个任务就立即处理其结果。
全部完成后输出综合报告。

{
  "subagents": {
    "security-auditor": {
      "description": "安全审计专用Agent，扫描OWASP Top 10漏洞",
      "subagent_type": "general-purpose",
      "model": "opus",
      "tools": ["Bash", "Read", "Grep", "Glob"],
      "system_prompt": "你是一个安全审计专家。专注于SQL注入、XSS、CSRF、认证绕过等漏洞。对每个发现评估严重程度（Critical/High/Medium/Low）并给出修复建议。"
    },
    "test-writer": {
      "description": "测试编写Agent，为指定函数生成单元测试",
      "subagent_type": "general-purpose",
      "model": "sonnet",
      "isolation": "worktree"
    }
  }
}

graph LR
    A[1个Agent<br/>串行执行<br/>基准时间: 60min] --> B[2-3个Agent<br/>轻度并行<br/>时间: 25-30min]
    B --> C[4-6个Agent<br/>最优区间<br/>时间: 12-18min]
    C --> D[7-10个Agent<br/>收益递减<br/>时间: 10-15min]
    D --> E[10+个Agent<br/>协调开销>收益<br/>时间: 12-20min]

    style C fill:#50C878,color:#fff
    style E fill:#FF6B6B,color:#fff

# 反模式：给SubAgent传递过多上下文
请启动一个SubAgent，以下是需要处理的全部500行代码：
[粘贴500行代码]  ← 浪费上下文窗口

# 最佳实践：让SubAgent自己读取
请启动一个SubAgent处理src/api/users.ts中的类型问题。
它会自行读取文件并修复。

总成本 ≈ 协调Agent成本 + Σ(并行Agent成本)
       ≈ (主Agent tokens × Opus单价) + (N × 子Agent tokens × 模型单价)

最优并行数 N* = √(总任务数 × 平均任务复杂度 / 协调开销)

# 方案1：拆分为更小的子任务
# 将"重构整个模块"拆分为"重构单个文件"

# 方案2：使用Background Agent
将长时间运行的任务设为run_in_background: true

# 方案3：增加max_turns
通过max_turns参数限制Agent的最大轮次：
{
  max_turns: 50  // 默认通常足够，复杂任务可增加
}

# 查看冲突文件
git diff --name-only .claude/worktrees/agent-1 .claude/worktrees/agent-2

# 让主Agent解决冲突
claude -p "检查worktree agent-1和agent-2中的冲突文件，智能合并两者的修改：
- 保留两者的类型定义（取并集）
- 如果逻辑冲突，优先agent-1的版本
- 运行测试验证合并结果"

// 使用TaskOutput工具主动查询
{
  task_id: "agent-background-abc123",
  block: true,      // 阻塞等待结果
  timeout: 60000    // 超时时间60秒
}

// 或查看输出文件
// Background Agent会返回一个output_file路径
// 使用Read工具读取该文件