Claude Code多Agent编排实战：从Subagent到Agent Team全链路

graph TB
    subgraph "Layer 3: Agent Team 团队协作"
        LT[Team Lead<br/>协调者] --> T1[Teammate 1<br/>前端]
        LT --> T2[Teammate 2<br/>后端]
        LT --> T3[Teammate 3<br/>测试]
        T1 <-->|直接通信| T2
        T2 <-->|直接通信| T3
    end

    subgraph "Layer 2: Subagent 任务委派"
        PA[Parent Agent<br/>父代理] --> SA1[Explore Agent<br/>代码探索]
        PA --> SA2[General Agent<br/>通用任务]
        PA --> SA3[Custom Agent<br/>自定义]
        SA1 -.->|返回结果| PA
        SA2 -.->|返回结果| PA
        SA3 -.->|返回结果| PA
    end

    subgraph "Layer 1: Worktree 文件隔离"
        W1[Worktree A<br/>feature-auth]
        W2[Worktree B<br/>bugfix-123]
        W3[Worktree C<br/>pr-456]
        W1 --- W2 --- W3
        W1 ---|共享Git历史| MAIN[Main Branch]
        W2 ---|共享Git历史| MAIN
        W3 ---|共享Git历史| MAIN
    end

quick       → 精准查找，适合定位特定函数/文件（约30秒）
medium      → 平衡探索，适合理解模块间关系（约1-2分钟）
very thorough → 全面扫描，适合新项目上手或架构分析（约3-5分钟）

> 帮我搜索项目中所有的数据库查询函数

> Use the Task tool with an Explore subagent set to "very thorough" to map out 
> all the API endpoints in this codebase. Return a structured list with method, 
> path, handler function, and middleware for each endpoint.

Dispatching Explore agent (very thorough)...
  Scanning src/routes/... 
  Scanning src/api/...
  Found 23 endpoints across 4 route files

  Summary:
  ├── src/api/auth.ts     → 5 endpoints (register, login, logout, refresh, me)
  ├── src/api/users.ts    → 8 endpoints (CRUD + search + profile)
  ├── src/api/todos.ts    → 7 endpoints (CRUD + filtering + sharing)
  └── src/api/admin.ts    → 3 endpoints (stats, export, health)

/agents

A security audit agent that scans source code for OWASP Top 10 
vulnerabilities. It should check for: SQL injection, XSS, CSRF, 
authentication flaws, and insecure dependencies. Return a severity-
ranked report with file paths, line numbers, and remediation suggestions.

---
name: security-auditor
description: Scans code for OWASP Top 10 vulnerabilities
model: claude-sonnet-4-6
tools:
  - Read
  - Grep
  - Glob
  - Bash
---

You are a security code auditor. Analyze the codebase for these vulnerability categories:

1. **Injection** (SQL, NoSQL, Command, LDAP)
2. **Broken Authentication**
3. **Sensitive Data Exposure**
4. **XML External Entities (XXE)**
5. **Broken Access Control**
6. **Security Misconfiguration**
7. **Cross-Site Scripting (XSS)**
8. **Insecure Deserialization**
9. **Using Components with Known Vulnerabilities**
10. **Insufficient Logging & Monitoring**

For each finding, provide:
- Severity: Critical / High / Medium / Low
- File path and line number
- Vulnerable code snippet
- Remediation recommendation with code example

Output as a structured markdown table sorted by severity.

claude --agents '[
  {
    "name": "perf-profiler",
    "description": "Profiles React components for unnecessary re-renders",
    "model": "claude-sonnet-4-6",
    "tools": ["Read", "Grep", "Glob"]
  }
]'

优先级从高到低：
1. Managed Settings  → 组织级，管理员部署
2. --agents CLI标志  → 当前会话
3. .claude/agents/   → 当前项目（可提交Git共享）
4. ~/.claude/agents/ → 用户级，所有项目可用
5. 插件 agents/     → 插件提供

> Use the security-auditor agent to scan the src/auth/ directory

# 方式一：指定名称
claude --worktree feature-auth

# 方式二：简写
claude -w bugfix-123

# 方式三：自动命名（如 bright-running-fox）
claude --worktree

# 方式四：基于PR创建
claude --worktree "#142"

// ~/.claude/settings.json
{
  "worktree": {
    "baseRef": "head"
  }
}

# .worktreeinclude（使用.gitignore语法）
.env
.env.local
config/secrets.json

---
name: parallel-refactorer
description: Refactors a module in isolation
isolation: worktree
---

You are a code refactoring specialist. ...

> Use worktrees for your subagents when parallelizing this refactoring

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

> I'm building a real-time chat application. Create an agent team with:
> - One teammate for the WebSocket backend (Node.js + Socket.io)
> - One teammate for the React frontend (chat UI, message list, typing indicators)
> - One teammate for writing integration tests
> All three should work in parallel. The backend and frontend can start simultaneously;
> tests should wait until both are done.

// ~/.claude/settings.json
{
  "teammateMode": "in-process"  // 或 "tmux", "auto"
}

# 直接与Teammate交互
> Ask the backend teammate to also add rate limiting to the WebSocket connections

# 要求计划审批
> Spawn an architect teammate to refactor the auth module. 
> Require plan approval before they make any changes.

# 关闭Teammate
> Ask the researcher teammate to shut down

# 清理Team
> Clean up the team

> Spawn a teammate using the security-reviewer agent type to audit the auth module.

{
  "hooks": {
    "TeammateIdle": [{
      "type": "command",
      "command": "bash -c 'npm test 2>&1 || exit 2'"
    }],
    "TaskCompleted": [{
      "type": "command",
      "command": "bash -c 'npx eslint $(cat stdin | jq -r .files[].path) 2>&1 || exit 2'"
    }]
  }
}

flowchart TD
    START[需要并行工作] --> Q1{任务之间<br/>需要通信吗？}
    Q1 -->|否| Q2{每个任务<br/>需要修改文件吗？}
    Q1 -->|是| TEAM[Agent Team<br/>多会话协调]
    Q2 -->|否| Q3{只是搜索/<br/>分析代码？}
    Q2 -->|是| Q4{修改同一文件/<br/>有依赖关系？}
    Q3 -->|是| SUB_EXPLORE[Explore Subagent<br/>Haiku只读]
    Q3 -->|否| SUB_PLAN[Plan Subagent<br/>只读规划]
    Q4 -->|是| SEQUENTIAL[单会话顺序执行<br/>不要并行]
    Q4 -->|否| Q5{需要物理<br/>文件隔离？}
    Q5 -->|是| WORKTREE[Worktree + Subagent<br/>隔离执行]
    Q5 -->|否| SUB_GENERAL[General-purpose Subagent<br/>同一目录并行]

gantt
    title 团队工作区功能开发时间线
    dateFormat X
    axisFormat %s分钟

    section Phase 1 - 并行探索
    Explore DB层          :a1, 0, 3min
    Explore API层         :a2, 0, 3min
    Explore 前端层        :a3, 0, 3min

    section Phase 2 - 并行实现
    Schema设计            :b1, 3, 8min
    API路由实现           :b2, 8, 18min
    前端组件开发          :b3, 8, 20min

    section Phase 3 - 验证
    集成测试编写          :c1, 18, 28min
    API文档生成           :c2, 18, 23min
    端到端验证            :c3, 28, 33min

> I need to add a "Team Workspace" feature to this SaaS app. 
> Use the Task tool to spawn 4 Explore subagents in parallel:
> 1. Explore the database layer: find all Prisma models, migration patterns, relations
> 2. Explore the API layer: find route patterns, middleware, auth decorators, error handling
> 3. Explore the frontend: find component structure, state management, routing patterns
> 4. Explore the test suite: find test frameworks, fixtures, integration test patterns
> 
> Each should return a 200-word summary with key files and patterns identified.

> Based on the exploration results, design a Prisma schema for workspaces. 
> Include: Workspace, WorkspaceMember, WorkspaceInvite models.
> Follow the existing model patterns. Write the migration file.

> Now implement in parallel using 3 Subagents with worktree isolation:
> 
> Subagent A (in worktree): Implement 5 API routes for workspaces:
>   POST /workspaces, GET /workspaces/:id, PUT /workspaces/:id, 
>   DELETE /workspaces/:id, POST /workspaces/:id/members
>   Follow the route patterns from exploration. Use the schema from Step 2.
> 
> Subagent B (in worktree): Build 3 React pages:
>   WorkspaceList, WorkspaceSettings, InviteMembers
>   Follow the component patterns from exploration. Use existing UI library.
> 
> Subagent C (in worktree): Generate OpenAPI docs for all new endpoints.
>   Follow existing doc format.
> 
> Return a summary of files created/modified for each.

> Write integration tests for all workspace API routes.
> Cover: CRUD operations, member management, permission checks, 
> error cases. Follow the test patterns from exploration.
> After writing tests, run the full test suite and fix any failures.

# 查看Worktree状态
git worktree list

# 切到各Worktree审查修改
cd .claude/worktrees/<name> && git diff

# 合并分支
git checkout main
git merge worktree-subagent-a
git merge worktree-subagent-b
git merge worktree-subtree-c

# 清理Worktree
git worktree remove .claude/worktrees/<name>

Spawn N sub-agents, one per directory in this list: {directories}.
Each sub-agent reads its directory, identifies the 3 most important files,
and returns a 100-word summary covering: purpose, key patterns, dependencies.
Aggregate into a 500-word architecture brief.

Spawn N sub-agents, one per module in this list: {modules}.
Each sub-agent reads its module + existing test patterns from /tests,
then writes one test file matching the existing patterns.
Return only the test file content, not implementation changes.

Spawn 3 sub-agents. Each one researches a different approach to {problem}:
(a) library-based, (b) custom code, (c) external service.
Each returns a 200-word comparison of pros, cons, and rough cost/complexity.
Synthesize into a recommendation.

Spawn 5 agent teammates to investigate different hypotheses about {bug}.
Have them talk to each other to disprove each other's theories,
like a scientific debate. Update the findings doc with whatever 
consensus emerges.

API Tier 1: 最多 ~5 并发（超出会排队，失去并行优势）
API Tier 4: 可支持 ~20+ 并发

最佳ROI: 4个并行Subagent

> Before spawning the subagent, output the prompt you are about to use.
> Let me review it first.

# 查看当前API使用量
# 登录 console.anthropic.com 查看 Usage 页面

git worktree list
cd .claude/worktrees/<name>
git diff --name-only

flowchart LR
    subgraph "开发者终端"
        USER[开发者指令]
    end

    subgraph "Claude Code主会话"
        ORCH[主代理<br/>Orchestrator]
        CM[CLAUDE.md<br/>项目配置]
        ORCH --- CM
    end

    subgraph "Subagent池"
        direction TB
        E1[Explore<br/>Haiku/只读]
        E2[Explore<br/>Haiku/只读]
        GP1[General<br/>Sonnet/全工具]
        GP2[General<br/>Sonnet/全工具]
        CUST[Custom Agent<br/>自定义]
    end

    subgraph "Agent Team"
        direction TB
        TL[Team Lead]
        TM1[Teammate 1]
        TM2[Teammate 2]
        TM1 <-->|Mailbox| TM2
        TL -->|任务分配| TM1
        TL -->|任务分配| TM2
    end

    subgraph "Worktree隔离层"
        direction TB
        WT1[/worktree-a/]
        WT2[/worktree-b/]
        WT3[/worktree-c/]
    end

    USER --> ORCH
    ORCH -->|Task Tool| E1
    ORCH -->|Task Tool| E2
    ORCH -->|Task Tool| GP1
    ORCH -->|Task Tool| GP2
    ORCH -->|Task Tool| CUST

    ORCH -->|Team创建| TL

    GP1 -.->|isolation: worktree| WT1
    GP2 -.->|isolation: worktree| WT2
    CUST -.->|isolation: worktree| WT3

    E1 & E2 & GP1 & GP2 & CUST -.->|结果返回| ORCH