Claude Agent 编排完全指南：智能体协作的艺术#

1
┌─────────────────────────────────────────────────────────────────┐
2
│                     Claude Code 智能体编排                        │
3
├─────────────────────────────────────────────────────────────────┤
4
│                                                                 │
5
│  ┌───────────────────────┐    ┌───────────────────────┐         │
6
│  │   场景一：对话式编排    │    │   场景二：API/脚本式编排  │         │
7
│  │                       │    │                       │         │
8
│  │  用户直接说话触发代理   │    │  编写自动化脚本调用 API  │         │
9
│  │  "帮我并行做这三件事"   │    │  实现复杂的 CI/CD 流程  │         │
10
│  │                       │    │                       │         │
11
│  │  交互式，即时反馈      │    │  可重复，可集成到系统    │         │
12
│  └───────────────────────┘    └───────────────────────┘         │
13
│                                                                 │
14
└─────────────────────────────────────────────────────────────────┘

1
用户: 首先并行进行安全审查和代码审查，然后根据审查结果
2
      执行重构，最后更新文档
3

4
执行流程:
5
  阶段 1 (并行):  [security-reviewer] + [code-reviewer]
6
                      ↓
7
  阶段 2 (串行):  [refactor-cleaner] 根据审查结果重构
8
                      ↓
9
  阶段 3 (并行):  [doc-updater] + [code-reviewer] 文档更新 + 验证

1
# Python 示例：通过 API 调用多个代理
2
from anthropic import Anthropic
3

4
client = Anthropic()
5

6
def orchestrate_security_review(code_path: str):
7
    """编排安全审查工作流"""
8

9
    # 启动安全审查代理
10
    security_review = client.messages.create(
11
        model="claude-opus-4-5",
12
        max_tokens=4096,
13
        messages=[
14
            {
15
                "role": "user",
16
                "content": f"请审查以下代码的安全漏洞：\n{open(code_path).read()}"
17
            }
18
        ],
19
        # 使用代理标识
20
        metadata={
21
            "agent": "security-reviewer"
22
        }
23
    )
24

25
    return security_review.content
26

27
def orchestrate_full_review(code_path: str):
28
    """完整审查工作流：安全 + 代码质量 + 性能"""
29

30
    # 并行执行多个审查
31
    results = [
32
        client.messages.create(
33
            model="claude-sonnet-4-6",
34
            max_tokens=2048,
35
            messages=[{"role": "user", "content": f"安全审查: {code_path}"}],
36
            metadata={"agent": "security-reviewer"}
37
        ),
38
        client.messages.create(
39
            model="claude-sonnet-4-6",
40
            max_tokens=2048,
41
            messages=[{"role": "user", "content": f"代码审查: {code_path}"}],
42
            metadata={"agent": "code-reviewer"}
43
        ),
44
        client.messages.create(
45
            model="claude-haiku-4-5",
46
            max_tokens=2048,
47
            messages=[{"role": "user", "content": f"性能分析: {code_path}"}],
48
            metadata={"agent": "performance-reviewer"}
49
        ),
50
    ]
51

52
    return [r.content for r in results]

1
// TypeScript 示例：CI/CD 中的自动化审查
2
import Anthropic from '@anthropic-ai/sdk';
3

4
const client = new Anthropic();
5

6
async function ciSecurityGate(codeChanges: string[]): Promise<boolean> {
7
  const results = await Promise.all(
8
    codeChanges.map(async (change) => {
9
      const response = await client.messages.create({
10
        model: 'claude-opus-4-5',
11
        max_tokens: 4096,
12
        messages: [{
13
          role: 'user',
14
          content: `安全审查此提交: ${change}`
15
        }],
16
        metadata: { agent: 'security-reviewer' }
17
      });
18
      return response.content;
19
    })
20
  );
21

22
  // 检查是否有 CRITICAL 或 HIGH 级别问题
23
  const hasBlockingIssues = results.some(r =>
24
    r.includes('[CRITICAL]') || r.includes('[HIGH]')
25
  );
26

27
  if (hasBlockingIssues) {
28
    console.error('安全审查未通过，阻止合并');
29
    process.exit(1);
30
  }
31

32
  return true;
33
}

1
┌─────────────────────────────────────────────────────────────┐
2
│                    一句话记住编排语法                         │
3
├─────────────────────────────────────────────────────────────┤
4
│                                                             │
5
│  并行执行 ──── "同时"、"并行"、"一起"                        │
6
│                                                             │
7
│  串行执行 ──── "先...然后..."、"按顺序"、"一步一步"           │
8
│                                                             │
9
│  指定代理 ──── 直接说出代理名称或用途                          │
10
│                                                             │
11
│  混合编排 ──── 组合使用以上模式                               │
12
│                                                             │
13
└─────────────────────────────────────────────────────────────┘

1
┌─────────────────────────────────────────────────────────────┐
2
│                    共享上下文 (Session Context)              │
3
├─────────────────────────────────────────────────────────────┤
4
│                                                             │
5
│  ┌─────────────┐   结果写入   ┌─────────────┐               │
6
│  │ Agent 1     │ ──────────▶ │             │               │
7
│  │ security    │             │  共享上下文  │               │
8
│  └─────────────┘             │             │               │
9
│                               │  - 审查结果  │               │
10
│  ┌─────────────┐   读取上下文 │  - 代码状态  │               │
11
│  │ Agent 2     │ ◀────────── │  - 任务进度  │               │
12
│  │ refactor    │             │             │               │
13
│  └─────────────┘             └─────────────┘               │
14
│                                     ▲                        │
15
│                                     │ 写入                   │
16
│                               ┌─────────────┐               │
17
│                               │ Agent 3     │               │
18
│                               │ doc-updater │               │
19
│                               └─────────────┘               │
20
└─────────────────────────────────────────────────────────────┘

1
用户: 实现用户认证功能，要求：
2
      1. 先规划整体方案
3
      2. 安全审查通过后再写代码
4
      3. 代码写完后进行完整审查
5
      4. 审查通过才合并
6

7
执行流程:
8

9
  Step 1: [planner] 规划
10
  ┌────────────────────────────────────────────────┐
11
  │ • JWT + Refresh Token 方案                     │
12
  │ • 密码使用 bcrypt 哈希                         │
13
  │ • 添加 Rate Limiting                          │
14
  │ • 实现 MFA 支持                               │
15
  └────────────────────────────────────────────────┘
16
                            │
17
                            ▼
18
  Step 2: [security-reviewer] 安全预审
19
  ┌────────────────────────────────────────────────┐
20
  │ ✓ 密码存储方案: bcrypt OK                      │
21
  │ ✓ Token 刷新机制: 建议添加 token rotation      │
22
  │ ⚠ 需要注意: 登录尝试次数限制                     │
23
  └────────────────────────────────────────────────┘
24
                            │
25
                            ▼ (审查通过)
26
  Step 3: [tdd-guide] 开发
27
  ┌────────────────────────────────────────────────┐
28
  │ RED: 登录失败处理测试                            │
29
  │ GREEN: 实现基本的登录逻辑                       │
30
  │ REFACTOR: 提取 AuthService                     │
31
  └────────────────────────────────────────────────┘
32
                            │
33
                            ▼
34
  Step 4: [code-reviewer] + [security-reviewer] 双重审查
35
  ┌────────────────────────────────────────────────┐
36
  │ [security-reviewer] ✓ 无高危问题               │
37
  │ [code-reviewer] ✓ 代码质量达标                 │
38
  └────────────────────────────────────────────────┘
39
                            │
40
                            ▼ (通过)
41
  完成：可以合并到主分支

1
                    ┌──────────────────┐
2
                    │   用户确认/干预   │
3
                    └────────┬─────────┘
4
                             │ yes
5
                             ▼
6
┌──────────┐    ┌────────────────────┐    ┌──────────┐
7
│  任务 A   │───▶│   检查点 (Gate)    │───▶│  任务 B   │
8
└──────────┘    └────────────────────┘    └──────────┘
9
                      │ no
10
                      ▼
11
              ┌──────────────────┐
12
              │   等待用户指令     │
13
              └──────────────────┘

1
❌ 反模式 1: 过度并行
2
   "帮我并行分析这个项目的 100 个文件"
3
   → 结果难以整合，容易遗漏问题
4

5
❌ 反模式 2: 忽略检查点
6
   "直接重构，不用审查了"
7
   → 高风险，可能引入严重问题
8

9
❌ 反模式 3: 串行过度
10
   "先审查 1 号文件，通过后再审查 2 号..."
11
   → 效率低下，代理可以并行处理独立任务
12

13
❌ 反模式 4: 代理职责混乱
14
   "让 code-reviewer 去规划功能"
15
   → 专业代理做专业事

1
                    ┌─────────────────┐
2
                    │  任务可并行吗？   │
3
                    └────────┬────────┘
4
                             │
5
              ┌──────────────┴──────────────┐
6
              │ yes                         │ no
7
              ▼                             ▼
8
    ┌─────────────────┐           ┌─────────────────┐
9
    │ 找出所有独立任务   │           │ 确定任务依赖关系  │
10
    │ 并行启动代理      │           │ 按依赖顺序串行    │
11
    └─────────────────┘           └─────────────────┘
12
              │                             │
13
              └──────────────┬──────────────┘
14
                             ▼
15
                   ┌─────────────────┐
16
                   │ 需要安全审查吗？   │
17
                   │ (认证/支付/数据)   │
18
                   └────────┬────────┘
19
                            │
20
              ┌─────────────┴─────────────┐
21
              │ yes                       │ no
22
              ▼                           ▼
23
    ┌─────────────────┐         ┌─────────────────┐
24
    │ [security-      │         │  继续其他代理     │
25
    │  reviewer] 强制  │         │                 │
26
    └─────────────────┘         └─────────────────┘

1
用户: 在 user-service 中发现了一个 SQL 注入漏洞，
2
      请帮我修复并确保没有引入新问题。
3

4
┌─────────────────────────────────────────────────────────────┐
5
│                     阶段 1: 诊断                             │
6
├─────────────────────────────────────────────────────────────┤
7
[security-reviewer] 分析漏洞位置和原因
8
  → 漏洞位置: user_query 参数
9
  → 漏洞类型: 字符串拼接 SQL
10
  → 影响范围: 用户数据泄露风险
11
  → 修复建议: 使用参数化查询
12
└─────────────────────────────────────────────────────────────┘
13
                              │
14
                              ▼
15
┌─────────────────────────────────────────────────────────────┐
16
│                     阶段 2: 修复 (并行)                       │
17
├─────────────────────────────────────────────────────────────┤
18
[build-error-resolver] 准备修复方案
19
  → 替换为 PreparedStatement
20
  → 添加输入验证
21

22
[code-reviewer] 审查修复方案
23
  → 方案可行
24
  → 建议添加异常处理
25
└─────────────────────────────────────────────────────────────┘
26
                              │
27
                              ▼
28
┌─────────────────────────────────────────────────────────────┐
29
│                     阶段 3: 实现与验证                         │
30
├─────────────────────────────────────────────────────────────┤
31
[tdd-guide] 编写回归测试
32
  → 测试 SQL 注入防护
33
  → 测试正常查询功能
34

35
[e2e-runner] 执行端到端测试
36
  → 验证修复未破坏其他功能
37
└─────────────────────────────────────────────────────────────┘
38
                              │
39
                              ▼
40
┌─────────────────────────────────────────────────────────────┐
41
│                     阶段 4: 最终审查                          │
42
├─────────────────────────────────────────────────────────────┤
43
[security-reviewer] 最终安全确认
44
  → ✓ SQL 注入漏洞已修复
45
  → ✓ 无新安全引入
46

47
[code-reviewer] 代码质量确认
48
  → ✓ 测试覆盖率 87%
49
  → ✓ 无死代码
50
└─────────────────────────────────────────────────────────────┘
51
                              │
52
                              ▼
53
                           完成

1
用户: 需要开发一个新的订单处理模块，请协调整个流程。
2

3
┌─────────────────────────────────────────────────────────────┐
4
│  编排计划                                                    │
5
├─────────────────────────────────────────────────────────────┤
6
阶段 1 (串行): [architect] 订单系统架构设计
7
  → 订单状态机设计
8
  → 库存扣减策略
9
  → 支付集成方案
10

11
阶段 2 (并行): [planner] 任务分解 + [security-reviewer] 安全评审
12
  → 任务分解清单
13
  → 安全需求清单
14

15
阶段 3 (串行): [tdd-guide] TDD 开发循环
16
  → RED: 写测试
17
  → GREEN: 实现功能
18
  → REFACTOR: 重构优化
19

20
阶段 4 (并行): [code-reviewer] + [security-reviewer] 双重审查
21
  → 代码质量审查
22
  → 安全漏洞扫描
23

24
阶段 5 (并行): [e2e-runner] + [build-error-resolver] 测试验证
25
  → 端到端测试
26
  → 构建验证
27

28
阶段 6 (串行): [doc-updater] 文档更新
29
  → API 文档
30
  → 使用手册
31
└─────────────────────────────────────────────────────────────┘

1
┌─────────────────────────────────────────────────────────────┐
2
│                    智能体编排三原则                           │
3
├─────────────────────────────────────────────────────────────┤
4
│                                                             │
5
│  1. 并行优先：独立任务并行执行，最大化效率                     │
6
│                                                             │
7
│  2. 串行保稳：有依赖的任务按序执行，保证正确性                 │
8
│                                                             │
9
│  3. 安全第一：安全相关代码必须经过 security-reviewer           │
10
│                                                             │
11
└─────────────────────────────────────────────────────────────┘

1
╔═══════════════════════════════════════════════════════════╗
2
║                  Claude Agent 编排速查卡                      ║
3
╠═══════════════════════════════════════════════════════════╣
4
║                                                           ║
5
║  并行执行                                                  ║
6
║  ─────────                                                ║
7
║  "帮我并行做这三件事"                                       ║
8
║  "同时处理 A、B、C"                                         ║
9
║                                                           ║
10
║  串行执行                                                  ║
11
║  ─────────                                                ║
12
║  "先做 A，然后做 B，最后做 C"                                ║
13
║  "按顺序执行这些步骤"                                       ║
14
║                                                           ║
15
║  指定代理                                                  ║
16
║  ─────────                                                ║
17
║  "帮我规划" → planner                                       ║
18
║  "审查代码" → code-reviewer                                 ║
19
║  "安全检查" → security-reviewer                             ║
20
║  "修复构建" → build-error-resolver                         ║
21
║                                                           ║
22
║  混合编排                                                  ║
23
║  ─────────                                                ║
24
║  "先并行审查，然后串行重构，最后并行验证"                      ║
25
║                                                           ║
26
╚═══════════════════════════════════════════════════════════╝