LLM和Agent——专题6：Multi Agent 入门（5）

Claude Code 多 Agent 编排实战------用 Task 工具实现代码生成+审查+测试闭环

我的终端里跑着 3 个 Claude Code Agent：一个写代码、一个审代码、一个跑测试，它们自动循环直到测试全部通过。

一、引言

Claude Code 不仅仅是一个代码助手，它内置了一套强大的多 Agent 编排能力。通过 Agent、Task、Plan 等工具，你可以在一个会话中调度多个"专业 Agent"协作完成复杂任务。

这篇文章将带你深入 Claude Code 的多 Agent 机制，并通过一个实战案例------自动代码生成→审查→修复→测试闭环------展示如何搭建可复用的多 Agent 工作流。

读完你会获得：

Claude Code 多 Agent 工具链的完整认知
一套可直接使用的多 Agent 协作工作流
如何配置 .claude/settings.json 来固化工作流
多个踩坑经验

二、Claude Code 的 Multi-Agent 工具箱

Claude Code 提供了几个核心工具用于多 Agent 编排：

2.1 Agent 工具

json 复制代码

{
  "name": "Agent",
  "parameters": {
    "subagent_type": "general-purpose | Explore | Plan | code-reviewer | ...",
    "description": "简短描述任务",
    "prompt": "给 Agent 的完整任务指令"
  }
}

这是核心的"派活"工具。你可以创建不同类型的 Agent：

Agent 类型	能力	适合任务
`general-purpose`	全能型	通用任务
`Explore`	只读搜索	代码探索、文件定位
`Plan`	架构设计	方案规划
`code-reviewer`	代码审查	PR Review
`claude-code-guide`	Claude Code 文档	工具用法查询

2.2 Task 工具

json 复制代码

{
  "name": "Task",
  "parameters": {
    "subagent_type": "...",
    "description": "任务描述",
    "prompt": "任务指令",
    "run_in_background": true | false
  }
}

Agent 的升级版。支持后台运行和任务追踪，适合长时间任务和需要并行执行的场景。

2.3 Plan 模式

通过 EnterPlanMode 进入计划模式，Claude 会先探索代码库、设计方案，然后输出实施计划等待确认------这本身就是一个"架构师 Agent"的行为。

2.4 关键区别

特性	Agent	Task	Plan Mode
是否执行代码	可以	可以	只规划
后台运行	不支持	支持	N/A
结果通知	内联返回	完成时通知	输出计划
适合场景	快速委派	长任务/并行	需要确认的复杂任务

三、实战：搭建代码质量闭环流水线

3.1 场景描述

当你在开发一个 Python 项目时，每次写完代码需要：

有人帮你检查代码质量
发现的问题自动修复
跑测试确认修复没有引入新问题
如果测试不通过，重复 2-3 直到通过

这个循环如果手动做，至少 10-15 分钟。用 Claude Code 多 Agent 编排，可以做到"一键触发，自动循环"。

3.2 工作流设计

复制代码

Step 1: 用户提交代码变更
    ↓
Step 2: Code Reviewer Agent 审查代码
    ↓
Step 3: 如果有问题 → Code Fixer Agent 修复
    ↓                ↓ 没有问题
Step 4: Test Runner Agent 运行测试    → 输出审查报告
    ↓
Step 5: 测试失败？→ 回到 Step 3（最多 3 轮）
    测试通过？→ 输出最终报告

3.3 在 Claude Code 中的实际操作

第一轮：代码审查

在 Claude Code 会话中，你可以这样发起：

复制代码

请帮我审查当前 git diff 中的代码变更，重点关注：
1. 潜在 bug
2. 安全问题（如命令注入、SQL 注入）
3. 性能问题
4. 代码可读性

如果发现问题，请自动修复它们，然后运行 pytest 验证。

Claude Code 内部会这样调度：

复制代码

主 Agent 理解任务
    │
    ├── Agent(code-reviewer): 审查 git diff，输出问题列表
    │      返回: [{"file": "app.py", "line": 23, "issue": "命令注入风险", ...}]
    │
    ├── Agent(general-purpose): 根据审查结果修复代码
    │      使用 Edit 工具修改问题文件
    │
    └── Bash: 运行 pytest
            返回: "3 passed, 1 failed"
    │
    ├── Agent(general-purpose): 分析失败测试
    │      定位原因，再次修复
    │
    └── Bash: 再次运行 pytest
            返回: "4 passed"

触发 Code Reviewer Agent

复制代码

Agent(
  subagent_type="code-reviewer",
  prompt="审查 app.py 和 utils.py 中的本次变更。重点关注 SQL 注入和命令注入风险。列出所有问题，按严重级别排序。"
)

触发修复 Agent

复制代码

Agent(
  prompt="根据以下审查结果修复代码。只改涉及安全问题的部分，不要改变功能逻辑。

审查结果：
1. [高危] app.py:23 - user_input 直接拼接到 shell 命令，存在命令注入
2. [中危] utils.py:45 - 数据库查询使用字符串拼接，存在 SQL 注入

修复后不要运行测试，我稍后手动确认。"
)

运行测试

bash 复制代码

$ python -m pytest tests/ -v

3.4 自动化闭环脚本

你可以把它封装成一个可复用的工作流。在 Claude Code 中创建一个 "代码审查闭环" 的 Skill：

markdown 复制代码

# Code Quality Loop Skill

## 触发条件
用户说 "审查代码" / "code review loop" / "检查代码质量"

## 执行流程

### 1. 获取变更
使用 `git diff` 获取当前变更。如果没有变更，询问用户要审查哪些文件。

### 2. 代码审查
启动 code-reviewer Agent，审查所有变更：
- 安全漏洞（OWASP Top 10）
- Bug 风险
- 性能问题
- 代码风格

### 3. 自动修复
如果审查发现问题，启动 general-purpose Agent 进行修复。修复原则：
- 只改与问题直接相关的代码
- 不改变功能行为
- 保留原有注释

### 4. 测试验证
运行项目测试套件。如果测试失败：
- 分析失败原因
- 修复问题
- 重新运行测试
- 最多循环 3 次

### 5. 输出报告
生成审查和修复摘要：
- 发现的问题数
- 已修复的问题数
- 测试最终状态
- 遗留问题（如有）

3.5 使用 Task 实现并行加速

如果变更涉及多个独立文件，可以用后台 Task 并行审查：

复制代码

# 并行启动 3 个审查 Agent
Task(description="审查 app.py", prompt="审查 app.py 的安全问题...", run_in_background=true)
Task(description="审查 utils.py", prompt="审查 utils.py 的代码质量...", run_in_background=true)
Task(description="审查 models.py", prompt="审查 models.py 的 ORM 查询效率...", run_in_background=true)
# 3 个 Task 在后台并行运行，完成后自动通知

四、自定义 Agent 类型配置

4.1 通过 settings.json 注册自定义 Agent

在项目的 .claude/settings.json 中：

json 复制代码

{
  "agents": {
    "security-auditor": {
      "description": "专门进行安全检查的 Agent",
      "system_prompt": "你是一个资深应用安全专家。审查代码时重点关注 OWASP Top 10。",
      "tools": ["Read", "Grep", "Glob", "Bash"],
      "model": "sonnet"
    },
    "test-writer": {
      "description": "为给定代码编写全面测试",
      "system_prompt": "你是一个测试工程师。你编写覆盖边界条件、异常路径的全面测试。",
      "tools": ["Read", "Write", "Edit", "Bash"],
      "model": "haiku"
    },
    "doc-generator": {
      "description": "生成代码文档",
      "system_prompt": "你为 Python 代码生成 Google 风格的 docstring。",
      "tools": ["Read", "Edit"],
      "model": "haiku"
    }
  }
}

4.2 在会话中使用自定义 Agent

配置生效后，在 Claude Code 中可以这样用：

复制代码

启动 security-auditor 审查本次 PR

Claude Code 会使用你配置的 system prompt 和工具集创建一个专门的 Agent。

五、多 Agent 协作的高级模式

5.1 辩论模式：双 Agent 交叉审查

复制代码

同时启动两个审查 Agent，给它们不同的审查角度：

Agent A (security-auditor): 从安全角度审查
Agent B (code-reviewer): 从代码质量和性能角度审查

两个 Agent 完成后，用第三个 Agent 合并和去重审查结果。

python 复制代码

# 概念示例：在 Claude Code 会话中
"""
请并行启动两个审查：
1. security-auditor: 审查本次变更的安全风险
2. code-reviewer: 审查代码质量和性能

两者完成后，帮我合并结果，去重并按严重程度排序。
"""

5.2 Plan-Execute-Review 循环

这是 Claude Code 内置的典型工作模式：

复制代码

1. Plan Agent: 设计方案 → 输出计划
2. 用户确认计划
3. Execute Agent: 按计划实现
4. Review Agent: 审查实现是否符合计划
5. 如果有偏差 → 回到步骤 3

这也是 Claude Code 的 EnterPlanMode + Agent 工具组合的本质。

5.3 Explore-Generate-Validate 流水线

复制代码

1. Explore Agent: 理解现有代码结构和模式
       ↓
2. Generator Agent: 根据探索结果生成新代码
       ↓
3. Validator Agent: 验证新代码
       - 是否遵循现有模式？
       - 是否引入了重复代码？
       - 是否破坏了现有测试？

六、踩坑经验

6.1 Agent 间上下文丢失

每个 Agent 启动时是一个干净的上下文------它看不到主会话中的对话历史。必须在 prompt 中明确传递所有必要信息。

diff 复制代码

- # 不好的做法
- Agent(prompt="审查这个文件")

+ # 好的做法
+ Agent(prompt="审查 app.py。这是用户管理模块的 API 层，
+         预期只处理 JSON 请求，返回格式统一为 {code, data, msg}。
+         最近我们修复了一个 SQL 注入漏洞(#42)，请确保没有类似问题。")

6.2 并行 Agent 的文件冲突

如果两个后台 Agent 同时编辑同一个文件，会出问题。确保并行的 Agent 处理不同的文件。

6.3 Agent 无限循环

Review → Fix → Test Fail → Fix → Test Fail → ... 设置 max_rounds 限制循环次数。

6.4 Agent 的"过度热心"

Agent 天然倾向于"做点什么"，即使没有问题也可能强行找问题修。在 prompt 中明确要求"如果没有发现问题就说没有，不要捏造"。

复制代码

code-reviewer Agent prompt:
"审查代码。如果代码质量良好，直接说'未发现问题'并给出评分。
不要为了看起来'有成果'而编造问题。"

七、总结

Claude Code 的 Agent / Task / Plan Mode 构成了一个完整的多 Agent 编排能力层
Agent 适合快速委派，Task 适合长时间/并行任务，Plan Mode 适合需要确认的复杂变更
代码审查→修复→测试 闭环是最经典且价值最高的多 Agent 工作流之一
通过 .claude/settings.json 可以注册自定义 Agent 类型（如 security-auditor），复用团队最佳实践
给 Agent 足够且精炼的上下文------Agent 不知道你在主会话中讨论过什么
设置 max_rounds 防止无限循环，明确要求 Agent "没问题就说没问题"

Claude Code 的多 Agent 能力让"AI 团队协作"从 PPT 走进了工程实践------关键是要设计好 Agent 之间的分工和上下文传递。