← blog AI Agent · 2026-04-08
Claude Agent 编排完全指南
深入解析 Claude Code 中的智能体编排机制，涵盖并行执行、串行执行、互动协调等核心编排方式，以及可用代理列表和实战技巧。
在现代软件开发中，Claude Code 不再只是单一的 AI 助手，而是化身为一个智能体编排平台。通过巧妙地组合多个专业代理（Agent），你可以同时处理复杂的安全审查、性能分析和代码重构任务——这正是 Agent 编排的核心魅力所在。
本文将深入探讨 Claude Code 中的智能体编排机制，涵盖从基础概念到高级技巧的完整知识体系。
1. 核心概念：什么是智能体编排
1.1 编排 vs 自动化
| 对比维度 | 传统自动化 | 智能体编排 |
|---|---|---|
| 执行模式 | 预定义的固定流程 | 动态决策和任务分配 |
| 组件关系 | 脚本调用脚本，线性执行 | 多个独立代理协作 |
| 错误处理 | 简单的 try-catch | 代理间相互感知和协调 |
| 扩展性 | 受限于脚本逻辑 | 按需添加新代理类型 |
1.2 两种使用场景
Claude Code 的智能体编排可以在两种截然不同的场景中运行：
graph TD
Orchestration["Claude Code 智能体编排"]
subgraph 场景一["场景一：对话式编排"]
S1A["用户直接说话触发代理<br/>'帮我并行做这三件事'"]
S1B["交互式，即时反馈"]
S1A --> S1B
end
subgraph 场景二["场景二：API/脚本式编排"]
S2A["编写自动化脚本调用 API"]
S2B["实现复杂的 CI/CD 流程"]
S2C["可重复，可集成到系统"]
S2A --> S2B --> S2C
end
Orchestration --> 场景一
Orchestration --> 场景二2. 可用代理列表详解
Claude Code 内置了 9 个专业代理，每个代理都有其独特的职责和使用场景：
2.1 代理总览表
| 代理名称 | 用途 | 触发时机 | 典型场景 |
|---|---|---|---|
planner | 实现规划 | 复杂功能开始前 | 创建技术方案、任务分解 |
architect | 系统设计 | 架构决策时刻 | 设计系统蓝图、技术选型 |
tdd-guide | 测试驱动开发 | Bug 修复或新功能 | 编写测试、验证实现 |
code-reviewer | 代码审查 | 编写代码后 | 审查代码质量、提出改进 |
security-reviewer | 安全分析 | 提交代码前 | 检查漏洞、OWASP Top 10 |
build-error-resolver | 构建错误修复 | 构建失败时 | 诊断错误、修复编译问题 |
e2e-runner | 端到端测试 | 关键用户流程验证 | 运行完整的用户场景测试 |
refactor-cleaner | 死代码清理 | 代码维护阶段 | 移除无用代码、优化结构 |
doc-updater | 文档更新 | 文档需要同步时 | 更新 API 文档、README |
2.2 代理职责详解
planner - 实现规划代理
职责：创建详细的实现计划
输入：功能需求描述
输出：分解的任务列表、技术方案
适用：任何复杂功能开始前architect - 架构设计代理
职责：进行系统级设计决策
输入：需求和约束条件
输出：架构图、设计模式建议
适用：微服务设计、数据库选型等重大决策tdd-guide - TDD 流程代理
职责：引导测试驱动开发
输入：功能需求
输出：RED 测试 → GREEN 实现 → REFACTOR 循环
适用：新功能开发、Bug 修复code-reviewer - 代码审查代理
职责：审查代码质量和模式
输入：待审查的代码
输出：具体改进建议（按 CRITICAL/HIGH/MEDIUM/LOW 分级）
适用：代码编写完成后security-reviewer - 安全分析代理
职责：识别安全漏洞
输入：代码或系统设计
输出：安全问题和修复建议
适用：涉及认证、支付、用户数据时（强制触发）build-error-resolver - 构建错误解决代理
职责：诊断和修复构建问题
输入：构建错误日志
输出：错误原因分析和修复步骤
适用：npm build、mvn compile 等失败时e2e-runner - 端到端测试代理
职责：执行完整的用户场景测试
输入：测试场景描述
输出：测试结果报告
适用：关键流程上线前的验证refactor-cleaner - 重构清理代理
职责：识别和移除死代码
输入：代码库
输出：可删除的代码列表、重构建议
适用：定期代码维护doc-updater - 文档更新代理
职责：保持文档同步
输入：代码变更
输出：更新的文档内容
适用：API 变更、功能更新后3. 对话式编排：直接在对话中触发
在 Claude Code 对话中，你可以通过自然语言直接触发智能体编排。这是最直接的编排方式。
3.1 并行执行：同时处理多个任务
当任务之间相互独立时，并行执行是最高效的选择。
触发方式
直接说："帮我并行做这三件事"工作原理图
graph TD
User["用户: '帮我并行做这三件事'"] --> Master["Claude Code 主控"]
Master --> A1["Agent 1 (安全审查)"]
Master --> A2["Agent 2 (代码审查)"]
Master --> A3["Agent 3 (性能分析)"]
A1 --> Result["结果汇总返回"]
A2 --> Result
A3 --> Result实际对话示例
用户: 帮我并行做这三件事：
1. 审查 auth 模块的安全性
2. 检查用户输入验证逻辑
3. 审查数据库查询的 SQL 注入防护
Claude Code:
→ [security-reviewer] 正在审查 auth 模块安全性...
→ [code-reviewer] 正在检查用户输入验证逻辑...
→ [security-reviewer] 正在审查 SQL 注入防护...
汇总结果:
┌─────────────────────────────────────────────────────┐
│ [CRITICAL] SQL 注入：user_query 参数未使用参数化查询 │
│ [HIGH] XSS 漏洞：profile 接口未转义 HTML 输出 │
│ [MEDIUM] 缺少 Rate Limiting 在登录接口 │
└─────────────────────────────────────────────────────┘3.2 串行执行：按顺序依次处理
当任务之间存在依赖关系（必须先完成 A 才能做 B）时，使用串行执行。
触发方式
直接说："先做 A，然后做 B，最后做 C"工作原理图
graph LR
User["用户: '先做 A，然后做 B，最后做 C'"] --> Master["Claude Code 主控"]
Master --> TaskA["任务 A (规划阶段)"]
TaskA -->|完成后| TaskB["任务 B (开发阶段)"]
TaskB --> TaskC["任务 C (审查阶段)"]实际对话示例
用户: 先规划这个新功能的实现方案，然后按照方案写代码，最后写测试
Claude Code:
阶段 1 - [planner] 创建实现计划
┌─────────────────────────────────────┐
│ 1. 数据模型设计 │
│ 2. API 端点规划 │
│ 3. 业务逻辑分层 │
│ 4. 任务分解清单 │
└─────────────────────────────────────┘
阶段 2 - 执行计划中的任务...
阶段 3 - [tdd-guide] 编写测试
┌─────────────────────────────────────┐
│ ✓ 单元测试覆盖率达到 85% │
│ ✓ 集成测试验证通过 │
└─────────────────────────────────────┘3.3 混合编排：并行与串行结合
复杂场景中，你可以自由组合并行和串行执行：
用户: 首先并行进行安全审查和代码审查，然后根据审查结果
执行重构，最后更新文档
执行流程:
阶段 1 (并行): [security-reviewer] + [code-reviewer]
↓
阶段 2 (串行): [refactor-cleaner] 根据审查结果重构
↓
阶段 3 (并行): [doc-updater] + [code-reviewer] 文档更新 + 验证4. API/脚本式编排：自动化工作流
除了对话式编排，你还可以在自动化脚本中调用 Claude API，实现复杂的编排逻辑。
4.1 使用 Anthropic SDK 调用代理
# Python 示例：通过 API 调用多个代理
from anthropic import Anthropic
client = Anthropic()
def orchestrate_security_review(code_path: str):
"""编排安全审查工作流"""
# 启动安全审查代理
security_review = client.messages.create(
model="claude-opus-4-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": f"请审查以下代码的安全漏洞：\n{open(code_path).read()}"
}
],
# 使用代理标识
metadata={
"agent": "security-reviewer"
}
)
return security_review.content
def orchestrate_full_review(code_path: str):
"""完整审查工作流：安全 + 代码质量 + 性能"""
# 并行执行多个审查
results = [
client.messages.create(
model="claude-sonnet-4-6",
max_tokens=2048,
messages=[{"role": "user", "content": f"安全审查: {code_path}"}],
metadata={"agent": "security-reviewer"}
),
client.messages.create(
model="claude-sonnet-4-6",
max_tokens=2048,
messages=[{"role": "user", "content": f"代码审查: {code_path}"}],
metadata={"agent": "code-reviewer"}
),
client.messages.create(
model="claude-haiku-4-5",
max_tokens=2048,
messages=[{"role": "user", "content": f"性能分析: {code_path}"}],
metadata={"agent": "performance-reviewer"}
),
]
return [r.content for r in results]4.2 TypeScript SDK 示例
// TypeScript 示例：CI/CD 中的自动化审查
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic();
async function ciSecurityGate(codeChanges: string[]): Promise<boolean> {
const results = await Promise.all(
codeChanges.map(async (change) => {
const response = await client.messages.create({
model: 'claude-opus-4-5',
max_tokens: 4096,
messages: [{
role: 'user',
content: `安全审查此提交: ${change}`
}],
metadata: { agent: 'security-reviewer' }
});
return response.content;
})
);
// 检查是否有 CRITICAL 或 HIGH 级别问题
const hasBlockingIssues = results.some(r =>
r.includes('[CRITICAL]') || r.includes('[HIGH]')
);
if (hasBlockingIssues) {
console.error('安全审查未通过，阻止合并');
process.exit(1);
}
return true;
}4.3 两种场景对比
| 对比维度 | 对话式编排 | API/脚本式编排 |
|---|---|---|
| 交互方式 | 自然语言触发 | 程序化调用 |
| 适用场景 | 探索性工作、即时协作 | CI/CD、自动化流程 |
| 执行速度 | 实时交互 | 可批量、无人值守 |
| 状态管理 | 会话内自动维护 | 需要自行管理上下文 |
| 错误恢复 | 人工干预 | 脚本化重试逻辑 |
| 典型用途 | 日常开发、代码审查 | 发布流水线、质量门禁 |
5. 编排语法参考：说什么触发什么
5.1 触发代理的关键词
| 你说的话 | 触发的代理 | 说明 |
|---|---|---|
| “帮我规划一下这个功能” | planner | 生成实现计划 |
| “设计一下系统架构” | architect | 架构设计 |
| “用 TDD 方式开发” | tdd-guide | 测试驱动开发 |
| “帮我审查这段代码” | code-reviewer | 代码审查 |
| “检查有没有安全漏洞” | security-reviewer | 安全分析 |
| “构建失败了，帮我看看” | build-error-resolver | 构建错误修复 |
| “跑一下端到端测试” | e2e-runner | E2E 测试执行 |
| “清理一下死代码” | refactor-cleaner | 代码重构清理 |
| “更新一下文档” | doc-updater | 文档更新 |
5.2 编排模式语句
并行执行语句
# 基本并行
"并行处理这三个任务"
"同时做 A、B、C"
"帮我同时审查这三个文件"
# 强调并行
"这三件事完全独立，一起处理"
"不需要等我确认，直接并行执行"串行执行语句
# 基本串行
"先做 A，然后做 B，最后做 C"
"按顺序执行这些步骤"
"一步一步来"
# 带条件
"先规划，如果没问题就执行"
"先审查代码，通过后再重构"混合编排语句
# 串行 + 并行组合
"先并行审查（安全+代码），然后串行重构"
# 带反馈循环
"先做 A，告诉我结果，我确认后再做 B"
# 条件执行
"如果审查发现严重问题就先停下来，否则继续"5.3 快速记忆表
| 编排方式 | 触发关键词 |
|---|---|
| 并行执行 | “同时”、“并行”、“一起” |
| 串行执行 | “先…然后…”、“按顺序”、“一步一步” |
| 指定代理 | 直接说出代理名称或用途 |
| 混合编排 | 组合使用以上模式 |
6. 高级技巧：代理间通信与协调
6.1 上下文共享机制
多个代理之间通过共享上下文进行通信：
graph TD
subgraph SharedContext["共享上下文 (Session Context)"]
SC["共享上下文<br/>审查结果 / 代码状态 / 任务进度"]
end
Agent1["Agent 1 (security)"] -->|结果写入| SC
SC -->|读取上下文| Agent2["Agent 2 (refactor)"]
Agent3["Agent 3 (doc-updater)"] -->|写入| SC6.2 多步骤协调示例
用户: 实现用户认证功能，要求：
1. 先规划整体方案
2. 安全审查通过后再写代码
3. 代码写完后进行完整审查
4. 审查通过才合并
执行流程:
Step 1: [planner] 规划
┌────────────────────────────────────────────────┐
│ • JWT + Refresh Token 方案 │
│ • 密码使用 bcrypt 哈希 │
│ • 添加 Rate Limiting │
│ • 实现 MFA 支持 │
└────────────────────────────────────────────────┘
│
▼
Step 2: [security-reviewer] 安全预审
┌────────────────────────────────────────────────┐
│ ✓ 密码存储方案: bcrypt OK │
│ ✓ Token 刷新机制: 建议添加 token rotation │
│ ⚠ 需要注意: 登录尝试次数限制 │
└────────────────────────────────────────────────┘
│
▼ (审查通过)
Step 3: [tdd-guide] 开发
┌────────────────────────────────────────────────┐
│ RED: 登录失败处理测试 │
│ GREEN: 实现基本的登录逻辑 │
│ REFACTOR: 提取 AuthService │
└────────────────────────────────────────────────┘
│
▼
Step 4: [code-reviewer] + [security-reviewer] 双重审查
┌────────────────────────────────────────────────┐
│ [security-reviewer] ✓ 无高危问题 │
│ [code-reviewer] ✓ 代码质量达标 │
└────────────────────────────────────────────────┘
│
▼ (通过)
完成：可以合并到主分支6.3 反馈循环控制
graph TD
TaskA["任务 A"] --> Gate["检查点 (Gate)"]
Gate -->|yes| TaskB["任务 B"]
Gate -->|no| Wait["等待用户指令"]
UserConfirm["用户确认/干预"] --> Gate7. 最佳实践与反模式
7.1 推荐做法
| 场景 | 推荐做法 | 原因 |
|---|---|---|
| 独立任务 | 并行执行 | 效率最大化 |
| 有依赖任务 | 串行执行 | 保证正确性 |
| 关键路径 | 设置检查点 | 人工确认安全 |
| 大任务 | 先规划后执行 | 减少返工 |
| 安全相关 | security-reviewer 强制参与 | 防止漏洞 |
7.2 常见反模式
❌ 反模式 1: 过度并行
"帮我并行分析这个项目的 100 个文件"
→ 结果难以整合，容易遗漏问题
❌ 反模式 2: 忽略检查点
"直接重构，不用审查了"
→ 高风险，可能引入严重问题
❌ 反模式 3: 串行过度
"先审查 1 号文件，通过后再审查 2 号..."
→ 效率低下，代理可以并行处理独立任务
❌ 反模式 4: 代理职责混乱
"让 code-reviewer 去规划功能"
→ 专业代理做专业事7.3 推荐的决策流程
graph TD
Q1["任务可并行吗？"] -->|yes| P1["找出所有独立任务<br/>并行启动代理"]
Q1 -->|no| P2["确定任务依赖关系<br/>按依赖顺序串行"]
P1 --> Q2["需要安全审查吗？<br/>(认证/支付/数据)"]
P2 --> Q2
Q2 -->|yes| P3["[security-reviewer] 强制"]
Q2 -->|no| P4["继续其他代理"]8. 实战案例：完整的工作流编排
8.1 案例：修复安全漏洞
用户: 在 user-service 中发现了一个 SQL 注入漏洞，
请帮我修复并确保没有引入新问题。
┌─────────────────────────────────────────────────────────────┐
│ 阶段 1: 诊断 │
├─────────────────────────────────────────────────────────────┤
[security-reviewer] 分析漏洞位置和原因
→ 漏洞位置: user_query 参数
→ 漏洞类型: 字符串拼接 SQL
→ 影响范围: 用户数据泄露风险
→ 修复建议: 使用参数化查询
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 阶段 2: 修复 (并行) │
├─────────────────────────────────────────────────────────────┤
[build-error-resolver] 准备修复方案
→ 替换为 PreparedStatement
→ 添加输入验证
[code-reviewer] 审查修复方案
→ 方案可行
→ 建议添加异常处理
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 阶段 3: 实现与验证 │
├─────────────────────────────────────────────────────────────┤
[tdd-guide] 编写回归测试
→ 测试 SQL 注入防护
→ 测试正常查询功能
[e2e-runner] 执行端到端测试
→ 验证修复未破坏其他功能
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 阶段 4: 最终审查 │
├─────────────────────────────────────────────────────────────┤
[security-reviewer] 最终安全确认
→ ✓ SQL 注入漏洞已修复
→ ✓ 无新安全引入
[code-reviewer] 代码质量确认
→ ✓ 测试覆盖率 87%
→ ✓ 无死代码
└─────────────────────────────────────────────────────────────┘
│
▼
完成8.2 案例：新功能开发工作流
用户: 需要开发一个新的订单处理模块，请协调整个流程。
┌─────────────────────────────────────────────────────────────┐
│ 编排计划 │
├─────────────────────────────────────────────────────────────┤
阶段 1 (串行): [architect] 订单系统架构设计
→ 订单状态机设计
→ 库存扣减策略
→ 支付集成方案
阶段 2 (并行): [planner] 任务分解 + [security-reviewer] 安全评审
→ 任务分解清单
→ 安全需求清单
阶段 3 (串行): [tdd-guide] TDD 开发循环
→ RED: 写测试
→ GREEN: 实现功能
→ REFACTOR: 重构优化
阶段 4 (并行): [code-reviewer] + [security-reviewer] 双重审查
→ 代码质量审查
→ 安全漏洞扫描
阶段 5 (并行): [e2e-runner] + [build-error-resolver] 测试验证
→ 端到端测试
→ 构建验证
阶段 6 (串行): [doc-updater] 文档更新
→ API 文档
→ 使用手册
└─────────────────────────────────────────────────────────────┘9. 总结：智能体编排的核心原则
9.1 编排三原则
┌─────────────────────────────────────────────────────────────┐
│ 智能体编排三原则 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 并行优先：独立任务并行执行，最大化效率 │
│ │
│ 2. 串行保稳：有依赖的任务按序执行，保证正确性 │
│ │
│ 3. 安全第一：安全相关代码必须经过 security-reviewer │
│ │
└─────────────────────────────────────────────────────────────┘9.2 快速参考卡
| 编排方式 | 例句 |
|---|---|
| 并行执行 | “帮我并行做这三件事” / “同时处理 A、B、C” |
| 串行执行 | “先做 A，然后做 B，最后做 C” / “按顺序执行这些步骤” |
| 指定代理 | “帮我规划” → planner、“审查代码” → code-reviewer、“安全检查” → security-reviewer、“修复构建” → build-error-resolver |
| 混合编排 | “先并行审查，然后串行重构，最后并行验证” |
通过掌握 Claude Agent 编排的这些技巧，你可以将复杂的开发任务分解为可管理的步骤，并利用专业代理协同完成。记住：并行处理独立任务、串行处理依赖任务、安全审查不可跳过。善用这些原则，你的工作效率将大幅提升。