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 工具{name:Agent,parameters:{subagent_type:general-purpose | Explore | Plan | code-reviewer | ...,description:简短描述任务,prompt:给 Agent 的完整任务指令}}这是核心的派活工具。你可以创建不同类型的 AgentAgent 类型能力适合任务general-purpose全能型通用任务Explore只读搜索代码探索、文件定位Plan架构设计方案规划code-reviewer代码审查PR Reviewclaude-code-guideClaude Code 文档工具用法查询2.2 Task 工具{name:Task,parameters:{subagent_type:...,description:任务描述,prompt:任务指令,run_in_background:true|false}}Agent的升级版。支持后台运行和任务追踪适合长时间任务和需要并行执行的场景。2.3 Plan 模式通过EnterPlanMode进入计划模式Claude 会先探索代码库、设计方案然后输出实施计划等待确认——这本身就是一个架构师 Agent的行为。2.4 关键区别特性AgentTaskPlan 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 AgentAgent( subagent_typecode-reviewer, prompt审查 app.py 和 utils.py 中的本次变更。重点关注 SQL 注入和命令注入风险。列出所有问题按严重级别排序。 )触发修复 AgentAgent( prompt根据以下审查结果修复代码。只改涉及安全问题的部分不要改变功能逻辑。 审查结果 1. [高危] app.py:23 - user_input 直接拼接到 shell 命令存在命令注入 2. [中危] utils.py:45 - 数据库查询使用字符串拼接存在 SQL 注入 修复后不要运行测试我稍后手动确认。 )运行测试$ python-mpytest tests/-v3.4 自动化闭环脚本你可以把它封装成一个可复用的工作流。在 Claude Code 中创建一个 “代码审查闭环” 的 Skill# 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_backgroundtrue) Task(description审查 utils.py, prompt审查 utils.py 的代码质量..., run_in_backgroundtrue) Task(description审查 models.py, prompt审查 models.py 的 ORM 查询效率..., run_in_backgroundtrue) # 3 个 Task 在后台并行运行完成后自动通知四、自定义 Agent 类型配置4.1 通过 settings.json 注册自定义 Agent在项目的.claude/settings.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 审查本次 PRClaude Code 会使用你配置的 system prompt 和工具集创建一个专门的 Agent。五、多 Agent 协作的高级模式5.1 辩论模式双 Agent 交叉审查同时启动两个审查 Agent给它们不同的审查角度 Agent A (security-auditor): 从安全角度审查 Agent B (code-reviewer): 从代码质量和性能角度审查 两个 Agent 完成后用第三个 Agent 合并和去重审查结果。# 概念示例在 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 的EnterPlanModeAgent工具组合的本质。5.3 Explore-Generate-Validate 流水线1. Explore Agent: 理解现有代码结构和模式 ↓ 2. Generator Agent: 根据探索结果生成新代码 ↓ 3. Validator Agent: 验证新代码 - 是否遵循现有模式 - 是否引入了重复代码 - 是否破坏了现有测试六、踩坑经验6.1 Agent 间上下文丢失每个 Agent 启动时是一个干净的上下文——它看不到主会话中的对话历史。必须在 prompt 中明确传递所有必要信息。- # 不好的做法 - 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 之间的分工和上下文传递。