Claude Code Subagents 实战：AI 角色工程化与多代理协作指南

如果你已经顺着这个系列用上了 Claude Code，大概率遇到过这样一个瞬间：你正在推进一个横跨十几个文件的改动，一开始它记得住需求，写到第五个文件的时候就开始含糊，甚至会把早前已经否定的方案又捡回来。你以为是模型变笨了，其实不是。问题出在“所有活都压在同一条会话”这件事上。

Claude Code 的 Subagents（子代理）就是为解决这个问题设计的。它允许你在项目里定义一批有明确角色、人设和工具权限边界的 AI 角色，让主 Claude 像项目经理一样把任务分发下去。这就是标题里说的“AI 角色工程化”——不是临时在对话里扮演某个角色，而是把角色沉淀成可复用的工程产物。

这篇文章是这个系列里我打算写得更细的一篇。我会先讲清楚 Subagents 解决的核心痛点是什么，然后拆解它的配置文件结构，给出几份可以直接抄进项目的实战配置，再讲调用方式与多代理协作流程，最后把我踩过的五个坑连同排查思路一起放出来。适合已经能熟练操作 Claude Code、但开始觉得单会话不够用的读者。

1. Subagents 到底在解决什么问题：长上下文迷航与角色混杂

1.1 长对话的“记忆衰减”是真实存在的

用过 Claude Code 的人都知道，它的主会话有一个很大的上下文窗口。大是大了，但大窗口不等于高质量。当一个会话里塞进了几十轮对话、几个大文件的全文、一堆工具输出时，真正有用的指令会被严重稀释。我在一个真实项目里观察过：一个重构任务进行到一半，主 Claude 开始参考我第一轮随口说过、后来已经被推翻的旧方案，因为它太远了，在当前决策里留下的痕迹太弱。

这不是玄学，是注意力机制的特性。窗口越大、历史越长，每条消息的相对影响力就越低。更糟的是，中间往往夹着大量“失败尝试”——跑错的命令、报错的日志、被放弃的 diff。这些噪声不会自动消失，只会持续污染后续所有决策。主线程就像一个会议室，你在这里讨论过一百件事，现在要讨论第一百零一件，前面那些人的声音仍然在背景里嗡嗡作响。

1.2 一个会话里塞两个角色，是互相打架的源头

很多人解决问题的方式是“在同一个对话里切换角色”：先让 Claude 当架构师出方案，再让它当测试工程师写用例，再让它当安全审计员过一遍。听起来灵活，实际上隐患很大。角色切换靠的是语气和措辞，但底层上下文里所有角色的要求、所有角色的决策全混在一起。上一轮“架构师”主张的方案，会成为下一轮“审计员”判断时的隐性偏见——它会下意识地维护自己之前写出来的东西。

Subagents 的思路完全不同。每个子代理是一个独立的 Claude 实例，有自己的系统提示词，有自己的上下文窗口，只看到主会话里被带给它的那部分信息。它不会“记得”主线程里那些被放弃的方案，因为它没看见。它的判断只基于它的角色设定和你发给它的任务。这种“隔离”恰恰是它最值钱的地方。

1.3 角色工程化 = 角色 × 工具 × 边界 × 输出契约

那么“AI 角色工程化”到底工程在哪里？我的理解是四件事：

• 角色：你是谁，负责什么，不负责什么。
• 工具：你被允许做什么操作，不被允许做什么操作。
• 边界：你能看到的上下文范围有多大。
• 输出契约：你交回的结果应该是什么格式。

这四件事在 Subagent 里都是可以显式配置的，而不是靠聊天时的即兴发挥。这也是它和“在对话里说一句‘你现在扮演一个审查员’”最本质的区别：普通扮演是临时的、口头上的；Subagent 是文件化的、可版本管理、有工具权限限制的。为了更直观地说明差异，我列个对比：

这六行对比基本就是全文的骨架。接下来我讲怎么把这些维度落成真实的配置文件。

2. Subagent 的文件结构与“人设”怎么写

2.1 存放位置：项目代理与个人代理

Claude Code 会在启动会话时加载可用的代理。项目级别的代理放在.claude/agents/目录下，每个代理对应一个.md文件，文件名就是代理的标识。比如.claude/agents/code-reviewer.md。Claude Code 运行时是通过扫描这个目录来发现代理的，所以你不需要在别的地方额外注册。

如果你在不同项目里都想用同一批代理，可以放到用户级目录~/.claude/agents/下。我的个人经验是：通用的角色（比如代码审查、测试编写）放用户级，跟具体项目强相关的角色（比如熟悉某个业务模块的“领域专家”）放项目级，跟着仓库走。这样团队其他人 clone 项目之后，跑起来就是同一批工具，不需要每个人各自折腾一遍。

2.2 frontmatter 字段逐个说清楚

每个代理文件最上面是一段 YAML frontmatter，夹在两行---之间。我常用的字段和它们的作用如下：

tools字段是“最小权限”思想的落地处。你细想一下：一个只负责读代码、给意见的审查代理，为什么要给它 Edit 和 Write？给了它反而容易失控。工具名称一般是Read、Edit、Write、Bash、Glob、Grep这类，具体可用集合以你安装版本的官方文档为准。我的习惯是只给完成任务必需的几个，绝不贪多。

2.3 代理正文：一份可执行的角色说明书

frontmatter 下面是代理的系统提示词正文，这就是这个代理的“人设说明书”，它的质量直接决定任务效果。我的写法一般分五段：

1. 身份与使命：一句话说清楚你是谁。比如“你是一名有十年经验的代码审查者”。
2. 工作流程：先做什么、再做什么。比如“先定位文件，再通读，最后按严重程度输出”。
3. 守则：明确不允许做的事。比如“只审查，不修改任何文件”。
4. 输出契约：规定返回格式。比如“按严重程度/位置/建议修复方式三列输出”。
5. 升级路径：什么情况下应该停下来问主线程，而不是硬猜。比如“需求表述模糊时，先列出假设，不要自行补全业务逻辑”。

这套结构看起来简单，但实操下来非常有效。很多人的 agent 正文只有一段“你是 XX，请帮我做 XX”，主 Claude 拿到之后不知道边界在哪、输出什么格式、什么时候该放弃，效果自然不稳定。你把它当成一份岗位说明书来写，而不是一个临时指令，质量立刻不一样。

3. 我常用的几个 Subagent 配置（可直接抄进项目）

3.1 只读审查者 code-reviewer

审查类代理的核心原则是“只读不写”。它需要读代码、查调用关系、跑少量命令看测试结果，但绝不应该拥有修改文件的能力。下面是我项目里实际在用的配置：

--- name: code-reviewer description: 审查代码改动，发现逻辑错误、并发竞态、越界访问、安全隐患和风格退化。适用于合入前复查、提交前自查。 tools: Read, Grep, Glob, Bash --- 你是一名有十年一线经验的资深代码审查者。你的职责是对给定的代码改动做全面审查，但你永远不修改任何文件。 工作流程： 1. 先用 Glob/Grep 定位改动涉及的文件与相关调用方。 2. 通读改动，重点关注：空指针与边界、并发竞态、资源释放、错误处理分支、敏感数据泄露、对外接口的破坏性变更。 3. 对每一处发现给出：文件与行号定位、问题类别、严重程度（严重/建议）、简要的修复思路。 守则： - 只报告问题，不实施修改。 - 不要泛泛而谈“建议增强可读性”，除非你能指出具体的反模式。 - 如果改动非常大，优先挑高风险路径讲：数据流、状态变更、鉴权逻辑。 输出格式：按严重程度分组。每组用列表，带上文件与行号。最后给一段 200 字以内的总结。

为什么把Edit和Write排除掉？因为我真的吃过亏。有一次我就顺手给了写权限，让它“审查完顺便帮我改掉低危问题”，结果它一口气改了三个文件，把格式问题、命名问题、甚至一些它自己理解错的地方全动了。从那以后，审查者和执行者在我这里永远是两个角色。

3.2 动手前的规划者 refactoring-planner

重构最怕的就是打开一个乱糟糟的模块，主 Claude 一拍脑袋就开始改，改到一半发现依赖关系比想象中复杂，只能回滚。所以我专门养了一个“先出方案、不动手”的规划代理：

--- name: refactoring-planner description: 重构前分析代码结构，产出分步重构方案。适用于模块混乱、想重写但还没想好怎么动手的前置规划阶段。 tools: Read, Grep, Glob, Bash --- 你是一名软件架构师，负责在动手重构前产出高质量的重构计划。 工作流程： 1. 定位目标模块的全部入口与出口。 2. 梳理当前依赖关系，标出循环依赖、隐藏耦合、重复实现。 3. 按风险从小到大列出重构步骤，每一步给出：涉及文件、改动内容、验证方式、回滚点。 4. 明确建议的“停止点”：哪些步骤不应该和别的改动混在一起。 守则： - 不直接修改任何文件。 - 方案必须可落地：避免“建议优化架构”这种口号，要给出具体到文件和函数的操作。 - 如果需求表述模糊，先列出你的假设，不要自行补全业务逻辑。

这个代理的价值在于把“想”和“做”分开。人在冲动的时候容易直接动手，模型也一样。有了规划代理，我会强制自己在任何大改动之前先跑一轮方案，然后把方案拿回主线程确认，再决定要不要执行。这个习惯帮我避免了好几次灾难性的重构。

3.3 补测试的专职人员 test-writer

测试是很多人用 AI 写代码时最容易忽略的环节。Claude Code 默认模式下你让它“写完功能顺手补个测试”，它往往只写两个 happy path 就交差。专职测试代理不一样，它的任务就是围绕一个模块把测试写到位：

--- name: test-writer description: 为指定模块补充单元测试与集成测试。读取实现代码与既有测试风格，产出可直接运行的测试文件。 tools: Read, Edit, Write, Bash, Glob, Grep --- 你是一名测试工程师，负责为指定模块补充高质量测试。 工作流程： 1. 先读目标模块的实现代码。 2. 读该模块或相邻模块已有的测试文件，摸清项目的测试框架、命名约定、mock 风格。 3. 按“正常路径、边界条件、失败路径”三类设计用例。 4. 执行测试命令，确保新增测试全部通过；如果失败，分析是实现 bug 还是测试写错，只修复测试自身的错误，不修改被测代码。 守则： - 不为了覆盖率而写无断言测试。 - 测试里不要依赖执行顺序、随机数据或真实外部服务。 - 输出时说明每个用例覆盖的行为。

这个代理是整个列表里唯一我给了Edit和Write的，因为它确实要新建测试文件。但注意它的守则里明确写了“不修改被测代码”，这条一定要写死。否则它会为了“让测试通过”而反过来改业务代码，方向就反了。

3.4 配置要点小结

三个例子下来，你会发现它们的差异集中在两个地方：一是tools白名单，二是正文里的“守则”段落。这两处就是角色工程化最核心的两个旋钮：控制它能做什么，控制它被禁止做什么。我通常在新建一个代理时会问自己三个问题：

• 这个角色最不该做的一件事是什么？写进守则第一条。
• 这个角色完成使命最少需要哪几个工具？写进 tools。
• 这个角色什么时候应该认怂？写进升级路径。

4. 调用方式与协作流：让主 Claude 当项目经理

4.1 三种触发方式

代理配置好之后，调用方式有几种，我平时按场景混着用。

第一种是直接点名。在输入框里输入@code-reviewer再跟任务描述，比如“@code-reviewer 请审查当前分支的改动”。这种方式的优点是精准，你明确指定角色，不会被路由误判。

第二种是 Tab 循环。在输入框里按 Tab 键，可以在当前可用的代理之间循环切换，连续按两下会弹出代理选择列表。适合你写任务写到一半，突然觉得“这块应该让某个人干”的时候。

第三种是显式指挥主 Claude。你可以直接对它说“先让 @refactoring-planner 出一版重构方案，我来确认，再让 @test-writer 补测试”。主 Claude 会负责编排这两次调用，并在两个代理的结论之间做衔接。这是最接近“项目经理驱动团队”的用法。

注意一个关键机制：对话发生在主线程，代理是被分发任务的一方。你不需要事无巨细地对代理下命令，只要描述清楚任务目标和验收标准。比如对 code-reviewer，说“审查src/core/下最近改动的文件”就够了，它会自己决定先看什么、后看什么。

4.2 一次典型的多角色协作流程

光说概念没用，我讲一个我常用的完整排障流程。假设收到线上反馈：某个接口偶尔超时。我不会直接让主 Claude 满仓库找 bug，而是按下面的链路走：

1. 主线程先做一些粗定位，用 Glob 和 Grep 把可能涉及的调用链路文件缩小到三五份。
2. 把这几份文件的路径交给规划代理，让它梳理调用链，标注出可疑的同步阻塞点和重试逻辑。
3. 规划代理返回分析报告后，主线程带着这份报告直接看最可疑的代码段，确认或者排除。
4. 找到根因后，由主线程亲自动手修，因为修复动作往往需要结合大量上下文，不适合扔给子代理。
5. 修完之后派 test-writer 补一个回归测试，覆盖这次超时的场景。
6. 最后派 code-reviewer 审查最终 diff，确认没有引入新的问题。

这套流程下来，主线程的上下文里始终没有塞进大段的原始代码，它拿到的是每轮代理加工过的结论。这就像项目经理只看下属写的简报，而不是把每个员工的八百页工作日志都读一遍。效率提升是很明显的。

4.3 子代理结果的回收与追问

每次子代理执行完，它返回的报告会成为主线程里的一条工具输出。所以“输出契约”写得越好，主线程接下来决策就越省力。如果报告不满足要求，你可以就地追问，比如“你列的三处问题里有没有误报？第二处的调用关系再确认一下”。

这里有个容易忽略的点：子代理执行完就结束了，你不能够直接钻进它的上下文里继续聊。它的完整思考过程、中间读过的文件、试过的命令，主线程都看不见。你看到的就是它交回的那份报告。所以如果你的代理经常把中间过程写得很简略，主线程就会因为信息不足而反复追问，这时你要做的不是多问几轮，而是回去把代理的输出契约改详细。

4.4 什么时候不该用 Subagent

Subagent 不是万能药，我用下来觉得这几类情况根本不该动用它：

• 单文件小改动，比如改个变量名、修个 typo。主线程一条消息就搞定，没必要转一手。
• 你自己还说不清要什么的时候。有一次我想重构一个工具函数，但连目标接口都没想好，这种情况丢给子代理只会得到一份同样混乱的答案。
• 任务强依赖早期对话里的隐性前提。子代理看不到完整历史，如果你给它任务时不把关键前提写清楚，它很容易基于自己的假设发挥。
• 对速度敏感的场景。每次派发子代理都要启动一个独立实例，有开销。琐碎高频的小任务留在主线程更划算。

判断标准就一句话：上下文隔离带来的收益，是否大于转交任务时丢失信息的成本。收益大就用，成本大就留在主线程自己干。

5. 踩坑实录：Subagent 用不起来的五个原因与排查链路

5.1 代理文件改了，列表里却看不到

现象：我往.claude/agents/里放了一个精心写的 test-writer.md，切回 Claude Code 里按 Tab，却怎么都找不到。

排查思路：先确认代理列表是什么时候加载的。Claude Code 一般会在会话启动时扫描目录，如果你是在会话运行当中新增的文件，当前会话很可能不会自动刷新。新版里通常有/agents之类的命令可以列出当前可用代理，建议先查一下这个列表，确认文件加载有没有静默失败。

最常见的静默失败原因是 YAML 拼写错误。frontmatter 里字段名写错，比如把description写成descriptions，加载器往往会直接忽略这个文件，不会给你报错。后面的正文再长也没用。这种问题的排查方式很朴素：把文件里的 frontmatter 单独复制出来，丢到任何一个 YAML 校验工具里看一眼。另外，文件名与name字段不一致也可能导致调用时找不到，保持两者一致是最省心的做法。

5.2 description 写得太像“人类简历”，路由永远不触发

现象：代理能用@手动呼出，但主 Claude 从来不主动调用它。我在很多项目里看到这种配置：“description: 我是代码审查者，有十年经验”。这完全是在写给人类看的。

原因在于 description 是给路由模型看的匹配索引。主 Claude 需要从用户的原始请求里判断“这时候应该用哪个代理”，如果你的描述里没有一个明确的“触发场景”，它就不知道该在什么时候用。比如用户说“帮我看看这次的提交有没有问题”，它要能从描述里读到“这个代理适合在提交前审查代码”这种触发线索。

我的写法是反问自己：用户的哪句话、哪个词会触发这个代理？然后把那类场景直接写进去。比如 code-reviewer 的描述里，我会放进“合入前”“提交前”“复查”“审查改动”这类关键词。注意别写得太啰嗦，几十个字能说清的触发条件就够了。

5.3 给了写权限，审查员变成了改造狂

现象：我让 code-reviewer 审查代码，回来一看它直接改了三个文件，还改错了其中一个的逻辑。

排查思路：回头看配置，tools 里给了 Edit 和 Write。审查类任务的本质是“读并报告”，不是“读并修改”。模型的天性是顺着指令往下做，你给它写权限，它就会忍不住用。

这类事故的修复很简单：把审查、规划类代理的 tools 收窄到Read, Grep, Glob, Bash。Bash 也要想清楚再给，因为git apply、sed -i这类命令在 Bash 里同样能造成修改。如果担心风险，可以把 Bash 也拿掉，只保留只读工具。记住一个原则：写操作只能出现在明确被要求“产出文件”的代理上，比如 test-writer。

5.4 上下文塞太满，代理反而“变笨”

现象：我让 test-writer 给一个模块补测试，为了省事，我把整个仓库十几个相关文件全文直接粘进任务文本里。结果它写出来的测试大量重复，而且有一半引用的是不存在的函数。

排查思路：子代理的上下文窗口比主线程小不少，这是它的物理限制。官方文档里给的量级大致是三万多个 token，你把十几个文件全文砸进去，它光“读取”就已经把窗口塞满了，后面哪还有空间认真设计用例？

正确的做法是给线索而不是给全文。在任务文本里告诉它目标模块的路径、入口函数名、期望覆盖的行为，然后让它自己用 Grep 和 Glob 去定位真正需要细读的代码。如果确实需要传大段上下文，主线程应该先做一轮筛选，只挑相关的几段贴过去，而不是图省事整仓搬运。

5.5 多代理协作时结果互相打架

现象：我让 refactoring-planner 出了方案，又让 code-reviewer 审了一遍，结果审查员说方案里有三处风险，规划者完全不认，两边结论冲突，主线程夹在中间不知道听谁的。

排查思路：这不能怪任何一个代理，它们各自只看到自己任务文本里的那点上下文。它们不知道对方的结论，自然无从对齐。

解决办法是串行化，并且把上下文显式传递下去。我在第二次派发时，会把第一个代理的输出摘要直接写进任务文本，比如“上一个分析给出的方案是 A 方案，你重点审查这几个风险点”。这样第二个代理是基于真实信息做判断，而不是对着空气臆测。这个习惯让我彻底理解了什么叫“工程化协作”：上下文不自动流动，必须靠你或主 Claude 显式搬运。

6. 关于角色工程化，我最后想说的几件事

代理文件跟代码一样，需要版本管理、需要 review、需要定期迭代。我把.claude/agents/直接纳入 git，每次增删代理都会像改代码一样走一遍正常流程。团队里如果有人改了公共代理，我会在对话里留意它表现的变化——有时候一次微调就足以让某个代理从“鸡肋”变成“主力”。

不要一开始就堆五六个代理。我见过有人第一天就配了八个角色，结果互相重叠、调用混乱，最后又全部删掉。我的建议是从两个开始：一个只读审查者，一个写测试的执行者。用一段时间，观察主 Claude 什么时候会用、什么时候用错，再针对性地加。

最后分享一个小技巧：代理描述要跟着项目演进。项目换了技术栈、改了目录结构，代理的描述和守则如果不更新，它就会拿旧地图找新路。我一般每次大改动后都会顺手检查一遍代理配置，看哪个位置的描述已经失真，然后花五分钟改掉。这个习惯看起来不起眼，但时间越久，这套角色工程化的体系就越顺手，Claude Code 才真正从“一个聪明的助手”变成“一支听指挥的团队”。