Claude Code 多 Agent:分工、协作与验证
围绕探索、实现与验证拆分 Agent 职责,记录任务编排、交接和边界处理。
站内整理版 · 2026.11.10:收紧标题和效果表述,原始发表日期保留。文中的模型、命令、价格和耗时属于当时记录,本轮未重新运行验证。
嗨大家好,我是钟师傅。
前两天有读者朋友私信我:「钟师傅,我用 Claude Code 写代码挺顺的,但感觉它干活干多了就开始"犯傻",明明之前讲过的事情又忘了,是不是哪里设置不对?」
这个问题我太熟悉了。
因为我自己也踩过这个坑——以为给 AI 塞越多信息它就越聪明,结果恰恰相反。
今天这篇文章,就是来解决这个问题的:不是让一个 AI 变得更聪明,而是组建一支 AI 团队,让它们分工协作。
这套方法来自 Anthropic(Claude 的母公司)内部验证的 Multi-Agent 架构。根据他们的数据:一个由 Claude Opus 4 担任"领导"、多个 Claude Sonnet 4 担任"员工"的多智能体系统,在研究任务上的表现比单个最强的 Claude Opus 4 智能体高出 90.2%。
没错,团队的力量在 AI 世界同样适用。
一、为什么你需要一支AI团队 🤔
单兵作战的三大天花板
在讲怎么搭建之前,先说说为什么单个 Agent 会遇到瓶颈。
第一,上下文窗口限制
AI 的"记忆"是有限的。当你在一个对话里塞了太多东西——需求文档、代码文件、历史记录——AI 就会开始"幻觉",输出的结果越来越离谱。
这就像让一个人同时记住 100 件事,然后问他第 37 件是什么。
第二,专业化不足
你让一个 Agent 又写代码、又写文档、又做测试、又审查代码——每个环节它都只能做到 60 分。
专注做一件事的人,往往比什么都做的人做得更好。AI 也一样。
第三,串行处理的效率瓶颈
单个 Agent 一次只能做一件事。当你的项目需要同时进行开发、测试、文档编写时,它只能排队一件一件来,大大拖慢了进度。
解决方案:像CEO一样管理AI
想象你是一家公司的 CEO。
遇到法律问题,你不会自己去翻法条,而是找法务部。遇到财务问题,你不会自己算账,而是找财务部。
每个部门有自己的专业知识和权限范围,他们在自己的"办公室"里处理复杂任务,最后只给你汇报一个精炼的结论。
这套逻辑,就是 Multi-Agent 系统的核心思想。
举个例子:你让主对话(CEO)审查 src/api 的代码变更。主对话把任务委派给 Sub-Agent(代码审查部),Sub-Agent 在独立环境里读取 20 个文件、分析 500 行代码、检查 15 个安全规则、生成详细报告,最后只返回一句结论:"发现 2 个高危问题:SQL 注入、未处理异常。"
你看,复杂的分析过程全在 Sub-Agent 的"独立办公室"里完成了,CEO 只需要接收最终结论,不用被海量细节淹没。
分工可以让每个 Agent 专注于一个任务,但是否节省时间,还取决于任务独立性、交接成本与复核工作量。
💡 核心洞察:复杂的分析过程全在 Sub-Agent 的"独立办公室"里完成,CEO 只需要接收最终结论,不用被海量细节淹没。
Skills vs Sub-Agent:一句话搞懂区别
在动手之前,先搞清楚一个关键概念:Skills 和 Sub-Agent 有什么区别?
一句话总结:Skills 是"加技能",Sub-Agent 是"派活"。
💡 核心洞察:Skills 是给主 Agent 加技能点,本质还是一个人干活;Sub-Agent 是派一个专家去处理任务,本质是多个人在协作。
| 对比项 | Skills | Sub-Agent |
|---|---|---|
| 本质 | 知识注入 | 任务委派 |
| 上下文 | 共享主对话 | 独立隔离 |
| 适用场景 | 增强单一能力 | 复杂任务分工 |
| 类比 | 学一门新技能 | 雇一个专家 |
理解这个区别,你就知道什么时候用 Skills,什么时候用 Sub-Agent 了。
二、创建你的第一个 Sub-Agent
理论讲完了,开干。
方法一:对话式创建(最简单)
可以先通过对话创建,再检查生成的配置。
第一步,在 Claude Code 对话框输入 /agents 并回车。
第二步,选择「Create New Agent」。
第三步,选择范围。Project 只对当前项目生效,放在 .claude/agents/ 目录;User 对你所有项目都生效,放在 ~/.claude/agents/ 目录。
第四步,选择「Generate with Claude」,让 AI 帮你生成配置。
第五步,告诉它你想要什么样的 Agent。
这里给你一个万能模板,直接复制进去就能用:
帮我创建一个 Claude Code 子代理:
「子代理信息」名称:code-reviewer,范围:项目级别,用途:审查代码质量、检查最佳实践、发现潜在bug。
「行为定义」触发时机:用户说"审查代码"或"review"时,工作流程:读取代码 → 分析问题 → 输出报告,工具需求:Read, Grep。
「系统提示要包含」角色定义、具体工作步骤、输出格式要求。
请严格按照高质量系统提示的5个部分来编写。
方法二:手动创建(更灵活)
如果你想完全掌控配置,可以手动创建 Markdown 文件。
Sub-Agent 的配置文件由两部分组成:YAML frontmatter + 系统提示。
配置示例如下:
「YAML 头部」
name: code-reviewer
description: 审查代码质量、最佳实践和潜在bug。当用户说"审查代码"、"review"、"检查代码质量"时使用。
tools: Read, Grep
model: sonnet
「系统提示正文」
你是一个专注于代码质量的审查专家。你的职责是发现代码中的问题并提供改进建议。
触发后的第一个动作:
-
确认要审查的代码范围;
-
使用 Grep 搜索相关文件;
-
使用 Read 读取代码内容。
核心工作流:
-
检查代码规范(命名、格式、注释);
-
检查潜在bug(空指针、边界条件、异常处理);
-
检查安全问题(SQL注入、XSS等);
-
检查性能问题(循环优化、内存泄漏)。
输出格式要求:
问题严重级别(高/中/低)、具体代码位置、问题描述、修复建议。
边界情况处理:
如果代码范围太大,建议分批审查;如果遇到不熟悉的语言,明确告知用户;不确定时,标注为"待确认"而非猜测。
把这个文件保存到 .claude/agents/code-reviewer.md,你的第一个 Sub-Agent 就创建完成了。
三大设计原则
创建 Agent 容易,创建一个好用的 Agent 不容易。
记住这三个原则:
第一,单一职责
每个 Agent 只做一件事,并把它做到极致。
如果你发现需要用两句话才能描述一个 Agent 的职责,那它应该被拆成两个。
第二,最小权限
只给 Agent 完成任务所需的最少工具。
一个代码审查 Agent 不需要 Bash 权限,给它 Read 和 Grep 就够了。权限越少,AI 越专注,出错概率越低。
第三,显式委派
description 要写得像一份清晰的岗位说明书,包含明确的触发词。
黄金公式:description = 做什么 + 什么时候用 + 触发词示例
description 示例:审查代码质量、最佳实践和潜在bug(做什么)。
当用户说"审查代码"、"review"时使用(什么时候用)。
触发词示例——用户说"帮我review一下这个文件",助手回应"我将使用code-reviewer来审查代码"。
系统提示的5部分结构
一个高质量的系统提示,应该包含这5个部分:
「第一部分:角色定义」你是一个专注于某具体领域的某角色名称。你的职责是某核心职责。
「第二部分:触发后的第一个动作」当被调用时,立即执行:1. 检查关键前提;2. 确认必要条件;3. 如果缺少信息,主动询问。
「第三部分:核心工作流程」按以下步骤执行:步骤1、步骤2、步骤3。
「第四部分:输出格式要求」输出必须包含:必需项1、必需项2。格式可以是 JSON、Markdown 或纯文本。
「第五部分:边界情况处理」如果遇到情况A,采用处理方式A;如果遇到情况B,采用处理方式B;不确定时,停止并请求人工确认。
模型选择指南
不同的任务应该用不同的模型:
| 场景 | 推荐模型 | 原因 |
|---|---|---|
| 简单工具调用 | haiku | 快速响应,成本低 |
| 常规任务 | sonnet | 平衡性能和成本 |
| 复杂分析/架构决策 | opus | 最强推理能力 |
三、帮助你造Agent的Agent 🤖
到这里,你已经学会了如何创建单个 Sub-Agent。
但如果你需要频繁创建不同的 Agent 呢?每次都要想配置、写提示词、检查格式,太累了。
这里有个骚操作:创建一个专门帮你造 Agent 的 Agent。
没错,用 AI 来造 AI。
为什么需要这个"造物主"
手动创建 Agent 有几个痛点:
容易忘记关键配置——description 里忘了写触发词?系统提示缺了边界情况处理?这些小问题会导致你的 Agent 不好用。
质量也容易参差不齐。有时候写得详细,有时候偷懒,不同 Agent 的水平差异很大。而且每次都要从零开始想结构、写模板,纯粹是重复劳动。
解决方案就是:把"如何创建高质量 Agent"这套方法论,固化成一个专门的 Agent。
Sub-Agent-Creator:我的造物主配置
我自己用的这个"造 Agent 的 Agent",核心设计如下:
「配置参数」
name: sub-agent-creator,
description: 帮助用户设计和创建高质量的 Sub-Agent 配置文件。当用户想要创建新的 agent、设计子代理、或说"帮我创建一个agent"、"新建子代理"时使用。tools: Read, Write, Glob,model: sonnet。
它的工作流程是这样的:用户说"帮我创建一个自动生成 commit message 的 agent",Sub-Agent-Creator 被触发后会先收集需求(问你要解决什么问题、什么时候触发、需要哪些工具),然后验证设计是否符合三大原则,接着自动生成完整的 YAML + 系统提示,最后保存到 .claude/agents/ 目录。整个过程不到 2 分钟,你的新 Agent 就已就绪。
它是怎么确保质量的
关键在于它的系统提示里内置了一套检查清单:
单一职责检查:能用一句话描述这个 agent 做什么吗?如果需要两句话,考虑拆分为两个 agent。
最小权限检查:每个工具都是必需的吗?能否用更少的工具完成任务?
触发词检查:description 中是否包含 2-3 个触发词?是否提供了使用示例?
每次创建新 Agent 前,它都会自动跑一遍这个清单。
实际使用示例
我跟它说:"帮我创建一个专门做代码审查的 agent"
它会先问我几个问题:
"这个 agent 要解决什么问题?比如检查代码规范、发现潜在 bug、还是安全审计?"
"什么时候应该触发它?用户说'审查代码'、'review'、还是其他关键词?"
"需要哪些工具?是否需要执行命令(Bash),还是只需要读取和搜索(Read, Grep)?"
等我回答完,它就自动生成一个完整的 Agent 配置文件,并保存到正确的目录。
整个过程不到 2 分钟。
第一次用的时候我愣了一下——我花了半小时才写好的 Agent 配置,它 2 分钟就搞定了,而且比我写得还规范。
💡 核心洞察:用 AI 来造 AI——把"如何创建高质量 Agent"这套方法论,固化成一个专门的 Agent。
一个小技巧:常用模板
如果你不确定要创建什么 Agent,可以让它推荐。它内置了几个常用模板:
| 模板 | 职责 | 推荐工具 |
|---|---|---|
| 代码审查 | 检查代码质量和最佳实践 | Read, Grep |
| 文档生成 | 为代码生成文档 | Read, Write, Glob |
| 测试生成 | 为函数生成单元测试 | Read, Write |
| Git 操作 | 自动生成 commit message | Bash, Read |
| 代码重构 | 重构指定代码段 | Read, Edit, Grep |
有了这个"造物主",你就可以快速批量创建标准化的 Agent 团队了。
四、Multi-Agent协作——从单兵到军团 🚀
有了多个 Agent 之后,下一个问题是:怎么让它们协作起来?
这就涉及到 Multi-Agent 的编排模式。
三种编排模式
根据 Anthropic 的官方文档,Multi-Agent 系统主要有三种编排模式:
第一种,并行模式(Parallelization)
多个 Agent 同时执行不同任务,互不干扰,最后汇总结果。比如用户任务下发后,Agent A 写代码、Agent B 写测试、Agent C 写文档,三个同时进行,最后汇总结果。
适用场景:任务之间没有依赖关系,可以同时进行。比如同时写代码、测试和文档。
优点:独立任务可以同时推进;总时间还要包含调度、合并与复核。
第二种,顺序模式(Sequential)
一个 Agent 完成后,把结果交给下一个 Agent,像流水线一样。比如:用户任务 → Agent A 写代码 → Agent B 审查代码 → Agent C 修复问题 → 最终结果。
适用场景:任务之间有依赖关系,后一个任务需要前一个的输出。比如先写代码,再审查,再修复。
优点:每个环节都能拿到上一步的完整结果,质量更可控。
第三种,层级模式(Hierarchical)
一个"领导" Agent 负责分配任务、监督进度、汇总结果,多个"员工" Agent 负责执行具体任务。就像公司组织架构:顶层是领导 Agent(Orchestrator),下面分别是员工 A(Builder)、员工 B(Tester)、员工 C(Scribe),领导统一调度,员工各司其职。
适用场景:复杂项目,需要动态调整计划、处理异常情况。
优点:最灵活,领导 Agent 可以根据执行情况实时调整策略。
如何选择编排模式
一张表帮你快速决策:
| 场景 | 推荐模式 | 原因 |
|---|---|---|
| 任务独立,追求速度 | 并行 | 同时执行,并计入交接与复核 |
| 任务有先后依赖 | 顺序 | 确保每步输入正确 |
| 复杂项目,需要灵活调度 | 层级 | 领导可动态调整 |
| 不确定用哪个 | 层级 | 最通用,容错性最好 |
我个人最常用的是层级模式,因为它最接近真实的团队协作方式——有人统筹,有人执行。
Claude Code 中的实现方式
在 Claude Code 里,Multi-Agent 是通过 Task 工具实现的。
当主对话需要委派任务给 Sub-Agent 时,它会调用 Task 工具,指定要使用的 Agent 类型和具体任务。比如主对话收到"帮我重构这个模块并写测试",就会同时发起两个 Task 调用:一个给 builder 重构 src/utils 模块,一个给 validator 为重构后的代码写测试。
这里有个关键点:你可以在一条消息里同时发起多个 Task 调用。
如果这些任务之间没有依赖关系,它们会并行执行。如果有依赖关系,就需要等前一个完成再发起下一个。
Claude Code 会自动判断依赖关系,但你也可以在提示词里明确指定:"先完成 A,再执行 B"。
实战案例:Four Agent 开发团队
光说不练假把式。这里给你一个我实际在用的 Multi-Agent 配置,适合中小型项目开发。方法来源于推特技术大佬@YukerX 的文章
叫做 "Four Agent" 团队,由四个角色组成:
Four Agent 团队的协作流程是这样的:Architect(架构师)先分析需求并拆解任务,然后把任务交给 Builder(建造者)实现代码。Builder 完成后,Validator(验证者)接手进行测试验证。最后,Architect 和 Validator 都会把成果汇总给 Scribe(文档官),由它来完成文档更新。
四个角色分工如下:
| 角色 | 职责 | 模型 | 工具 |
|---|---|---|---|
| Architect | 分析需求、设计架构、拆解任务 | opus | Read, Grep, Glob |
| Builder | 写代码、实现功能 | sonnet | Read, Write, Edit, Bash |
| Validator | 写测试、跑测试、验证功能 | sonnet | Read, Write, Bash |
| Scribe | 写文档、加注释、更新 README | haiku | Read, Write, Edit |
工作流程是这样的:
第一步,Architect 先出场
你说:"帮我实现一个用户登录功能"
Architect 会分析需求,输出一份任务分解清单:
任务分解:第一步,创建 User 模型和数据库迁移。第二步,实现登录 API 端点。第三步,添加 JWT token 生成逻辑。第四步,编写单元测试。第五步,更新 API 文档。
第二步,Builder 接手
根据 Architect 的任务清单,Builder 逐个实现功能,写代码、创建文件。
第三步,Validator 验证
Builder 完成后,Validator 为新代码编写测试,运行测试套件,报告问题。如果发现 bug,会反馈给 Builder 修复。
第四步,Scribe 收尾
功能完成、测试通过后,Scribe 更新文档:添加 API 说明、补充代码注释、更新 README。
为什么是这四个角色
这个配置不是随便拍脑袋想的。
为什么要有 Architect?
很多人直接让 AI 写代码,结果写出来的东西零散、不成体系。Architect 的作用是在动手之前先想清楚:要做什么、怎么拆分、按什么顺序。
这一步可以用 opus 模型,因为需要强推理能力。
为什么 Builder 和 Validator 要分开?
让同一个 Agent 既写代码又测代码,就像让学生自己给自己判卷子——容易放水。
分开之后,Validator 会用"挑刺"的心态来检查 Builder 的代码,更容易发现问题。
💡 核心洞察:让同一个 Agent 既写代码又测代码,就像让学生自己给自己判卷子——容易放水。
为什么 Scribe 用 haiku?
文档工作相对简单,不需要太强的推理能力。用 haiku 模型,响应更快、成本更低。
一键启动团队
你可以这样启动整个团队:
"用 Four Agent 团队帮我实现用户注册功能,要求:邮箱验证、密码加密、返回 JWT token"
Claude Code 会自动按顺序调用四个 Agent,最后给你一个完整的功能实现,包括代码、测试和文档。
当然,你也可以只用其中几个。比如只想审查代码,就说"用 Validator 帮我检查这个文件"。
五、指挥官Agent——让AI自己调度AI 🎯
到这里,你已经有了一支 Agent 团队。
但问题来了:每次都要手动决定"这个任务该派给谁",还是有点累。
有没有可能让 AI 自己来做这个决策?
答案是:创建一个"指挥官" Agent。
Agent-Commander:我的指挥官配置
这个 Agent 的职责很明确:分析任务、组建团队、下达指令、监控进度。
「配置参数」
name: agent-commander,
description: Agent指挥官 - 负责协调和指挥多个AI Agent完成复杂任务。当用户有复杂任务需要"协调多个agent"、"组建agent团队"、"指挥agent完成任务"时使用。tools: Task, Read, Write, Glob, Grep, AskUserQuestion,model: opus。
注意几个关键点:
model 用 opus,因为指挥官需要强推理能力来分析任务、做出决策。
tools 里有 Task,这是关键,它让指挥官可以调用其他 Agent。还有 AskUserQuestion,遇到不确定的情况,它会主动问你,而不是自己瞎猜。
指挥官的工作流程
当你说"帮我重构整个项目的代码结构,同时更新文档和测试"时:
第一步,扫描资源
指挥官先用 Glob 搜索所有可用的 Agent,了解"手下有哪些人可以用"。
第二步,分析任务
它会 think hard 分析你的任务:可以分解为哪些子任务?每个子任务需要什么能力?子任务之间有什么依赖关系?
第三步,组建团队
根据分析结果,从可用 Agent 中挑选合适的团队成员。
选择原则:最小团队、能力互补、避免冗余。
第四步,下达指令
向每个 Agent 下达明确的指令,包含:目标、输入、输出要求、约束条件。
第五步,监控进度
每个 Agent 返回结果后,指挥官会检查完成度、评估质量、识别问题。如果发现问题,要求重做或调整计划。
一个实际场景
你说:"我要给项目加一个评论功能,包括前后端"
指挥官的输出会是这样的:
「Agent指挥官 - 任务分析报告」
任务理解:为项目添加完整的评论功能,覆盖前后端实现。
子任务分解:第一步,设计评论功能架构,预计由 architect 执行。第二步,实现后端 API,预计由 builder 执行。第三步,实现前端组件,预计由 builder 执行。第四步,编写测试用例,预计由 validator 执行。第五步,更新 API 文档,预计由 scribe 执行。
团队组建:architect 负责需求分析和架构设计,执行顺序第一;builder 负责前后端代码实现,执行顺序第二;validator 负责测试验证,执行顺序第三;scribe 负责文档更新,执行顺序第四。
准备开始执行,确认吗?
你确认后,它就自动开始调度,每完成一步都会汇报进度。
指挥官的边界情况处理
好的指挥官不只是会派活,还要会处理意外。
任务过于模糊?主动问你澄清,而不是猜测。
没有合适的 Agent?先问你是否要创建新 Agent,经过确认后再调用 sub-agent-creator 创建。
Agent 执行失败?分析原因,尝试调整指令重新执行,最多重试 2 次。如果还是失败,向你报告并请求指导。
子任务有冲突?暂停执行,向你说明情况,请求决策后继续。
人机协作的正确姿势
这里要强调一点:指挥官再强,最终决策权还是在你手上。
创建新 Agent、改变计划方向、处理重大异常——这些事情,指挥官都会先征求你的同意。
AI 负责执行和建议,人负责决策和把关。
💡 核心洞察:指挥官再强,最终决策权还是在你手上。创建新 Agent、改变计划方向、处理重大异常——这些事情,指挥官都会先征求你的同意。
六、写在最后 ✨
回到开头那个读者的问题:AI 干活干多了就"犯傻",怎么办?
答案不是让单个 AI 更聪明,而是组建一支 AI 团队。
每个 Agent 专注做一件事,做到极致。用 Multi-Agent 协作模式,让它们分工配合。再用一个指挥官 Agent,自动调度整个团队。
从一个人干活,变成带一支队伍。
原文引用过多 Agent 的性能对比,但没有在此保留指标定义与测试条件,因此不把它换算为日常工作的提效比例。
我自己的体验是:搭建好这套系统后,很多原来需要反复沟通、手动干预的任务,现在一句话就能搞定。
上周我让指挥官帮我重构一个老项目,它自己拉了 4 个 Agent 干了 2 小时,我只点了 3 次确认。以前这活儿我得盯一整天。
如果你也想试试,从第二章开始,先创建你的第一个 Sub-Agent。
然后用第三章的"造物主",快速批量创建更多 Agent。
最后用第五章的指挥官,把它们组织成一支听话的 AI 军团。
干就完了。
最后,感谢你看到这里
如果觉得有收获,不妨顺手 点赞 / 在看 / 转发 / 评论
想第一时间收到 AI 工具实战干货?给我个星标
有更野的玩法?评论区聊聊