如果你和我一样曾经在同一个 Claude Code 会话里硬扛所有任务你会很快理解 Sub Agents 的价值。前几篇我们聊了基础用法、工具权限、上下文管理这一篇开始正式拆 Sub Agents 的创建方法。很多人在用 Claude Code 时其实早就遇到了上下文越来越重、任务互相干扰的问题只是没找到合适的拆解方式。Sub Agents 就是用来解决这个问题的它允许你定义一批专职的小号 Claude每个小号只负责一件事有自己的 system prompt、工具权限甚至可以用不同的模型。这篇文章我会从创建方法入手把配置文件格式、目录位置、字段含义、实战模板和踩坑经验一次讲清楚。1. 子代理是干什么的先搞清楚它和普通提示词的区别在开始写配置文件之前我希望你先想明白一个问题为什么需要子代理而不是直接在主对话里加一段“你是一个代码审查员”这样的提示词我在没有子代理之前遇到复杂任务都是靠同一个主对话硬扛先让它读代码再让它改文件再让它写测试最后还要总结。短时间内还好一旦任务链条拉长主对话的上下文就变得越来越重Claude 既要把前面的修改记在小本本上又要时刻留意你最新提出的需求速度变慢不说还经常把早期任务和后来的任务搅在一起。Sub Agent 的诞生本质上就是给这种“单线程硬扛”的局面拆成多个专职 worker。每个 Sub Agent 是一个独立的、带专属 system prompt 和工具权限的小号 Claude。它运行在自己独立的上下文里看不到你和主代理的完整聊天记录只会拿到你或者主代理丢给它的任务描述和相关文件列表。它的返回结果会被送回主对话然后主代理继续推动整体任务。换句话说子代理不是一个角色扮演而是一个真正被“派出去干活”的执行单元。1.1 上下文隔离才是灵魂很多人误以为 Sub Agent 只是换个名字的角色扮演这是最大的误区。实际上当你调用一个 Sub Agent 时它会开启一个全新的会话上下文主对话里的历史不会自动拷过去。你唯一能传递的是调用它时给出的那个 task 参数。这种设计带来的直接好处就是子代理不会把无关的旧话题当作参考不会因为前面聊了三个小时就把当前的小目标带偏。这就像你把一份文件交给一位专职校对他只管校对不需要知道这份文件写了几天、中途改过几版。如果你习惯在日常开发中同时处理多个需求你会体会到这个特性的价值。比如你一边在做重构一边想让 Claude 顺手把十几处日志格式统一。重构逻辑复杂聊了很久日志格式任务很简单但如果放在同一个会话里它容易被淹没。拆成 Sub Agent 后主代理会在合适的时机把这个小任务派给专职子代理子代理在干净上下文里执行完把结果交回来主对话不会被半路冒出来的日志修改记录塞满。1.2 一个子代理一次只办一件事创建 Sub Agent 时你要逼自己把任务边界切得很小。这其实是个逆向的锻炼我之前总想写一个“全能开发助手”什么都往里面塞结果 description 写了五百字系统提示也写得像某个公司的规章制度。后来我才意识到Sub Agent 的设置越聚焦效果越稳定。它不需要知道整个项目的全貌只需要负责某一个具体工序检查格式化、生成测试用例、整理变更日志、阅读错误日志并归纳可能原因。正因为一次只办一件事你才可以在 system prompt 里把这件事的定义、输入格式、输出格式、边界条件都写得很精确。这比在主线 prompt 里堆一大堆“你是一个 XX 助手”要可靠得多因为主线 prompt 会被大量临时指令稀释而子代理的指令只有在它被调用时才会独占地生效。1.3 什么时候不该用子代理不过Sub Agent 不是银弹。步骤高度依赖长对话历史的任务反而不适合拆出去。比如一次涉及三个文件互相引用的重构如果非要做一个子代理来执行你得通过 task 参数把相关文件路径和改到哪一步的背景全部交代清楚这常常比在主对话里直接做还费工夫。我自己的判断标准很简单超过三句说不清楚边界的事先不要拆拆出来之后如果 task 描述比配置文件还长说明边界没划好。所以在学创建方法之前先学会判断“什么不该拆”。子代理最适合的是那些输入输出明确、可独立验证、不需要依赖过往聊天记忆的工序。记住这句话后面写的配置才会真正好用。2. 创建子代理的前置准备和目录规范当你确定一个任务适合拆给子代理之后接下来的重点就是把它变成配置文件。Claude Code 对子代理的目录约定很清晰你不需要额外做什么初始化建好目录、放好文件、重启一下就能自动识别。2.1 项目里该建什么目录Claude Code 约定了一个固定的目录.claude/agents/。在你项目根目录下创建它然后把每个子代理定义写成一个独立的 Markdown 文件。这个目录是你项目级子代理的存放位置Claude 启动时会自动扫描把它们加载进可用的子代理列表。如果你在一个多模块仓库里工作也可以把通用子代理放到用户级目录下具体路径依版本不同有差异项目级目录优先推荐用.claude/agents/因为跟着仓库走团队协作时只要 clone 下来配置就自动带上。需要注意的是文件名最好和子代理的名字一致。假设你要创建一个叫code-reviewer的子代理那就建立code-reviewer.md。这样你在配置文件里填的name字段要和它对应上不管之后是自动调度还是手动点名都不会出现“配置文件叫这个但实际名字叫那个”的混乱。我在第一个项目里就吃过这个亏文件叫review.md配置 name 却写成senior-reviewer结果看起来能加载实际上总感觉调度不精准。2.2 认识 Markdown 配置模板子代理文件的基本结构很简单最上方是一段 YAML 格式的 frontmatter中间用---与正文隔开正文部分是真正的系统提示词。一个最简的模板长这样。--- name: example-agent description: 当需要处理某类具体任务时使用这个代理。描述要写清楚触发场景。 tools: Grep, Glob, Read model: haiku --- 你是一个负责完成某种特定任务的助手。 请严格按照以下流程执行 1. 接收用户提供的文件路径。 2. 使用工具读取文件。 3. 输出处理结果。注意看frontmatter 里我写了四个字段name、description、tools、model。正文部分没有额外的system_prompt:前缀因为它本身就是 system prompt。很多第一次接触的人会把 YAML 格式写漏比如少了闭合的---或者把冒号写成中文冒号这些都会导致整个文件解析失败。如果你保存后没有被扫描到先检查 frontmatter 是否完整。2.3 字段边界tools 是权限不是摆设tools 是很多新手最容易忽略的字段。它控制这个子代理能用哪些工具没有列出来的工具子代理就算在正文里反复要求自己“你可以运行 Bash”也调用不了。这个设计是故意的它把子代理的破坏半径压缩到最小。有的子代理只需要读文件那就只给 Read、Grep、Glob需要改文件才给 Edit需要执行命令才给 Bash。我建议你在创建时按最小权限原则去填先只给读类工具跑通后再考虑加写类或执行类工具。一个配置了 Bash 的子代理就是一个能在你项目里跑任意命令的代理你在 system prompt 里再强调“不要乱执行”逻辑上终究是挡不住意外。与其靠提示词自觉不如在工具层面先划好边界。model 字段则更灵活。你可以给轻量任务配一个便宜快速的模型给复杂分析配更强模型如果不填默认会跟随主代理当前使用的模型。创建一个只做文件聚合的子代理没有必要动用最高规格模型反之一个做架构评审的子代理值得给它一个更强的模型。这里没有唯一正确答案按你的成本预算来就好。3. 从零创建一个“空行检查”子代理为了让上面的规则落到一个能跑通的例子上我写一个很基础但很实用的小工具检测代码里是否存在行尾空格、文件末尾缺换行、缩进混用 Tab 或空格。这个任务边界清晰特别适合作为你的第一个子代理练手。3.1 完整配置示例先给你看完整文件内容--- name: whitespace-guard description: 检查代码文件中的空白字符规范问题包括行尾空格、文件末尾是否有换行、缩进是否混用 Tab 与空格。在批量修改文件后或提交前做格式自查时使用。 tools: Glob, Grep, Read model: haiku --- 你是仓库的空白规范检查员。你的任务只做检查不修改任何文件。 用户会给你一个目录或一批文件路径。请按以下步骤操作 1. 用 Glob 找到目标范围下的代码文件。 2. 用 Grep 搜索行尾空格正则参考[ \t]$ 3. 用 Grep 检查文件末尾是否缺少换行正则参考\n\z 4. 用 Read 检查可疑文件确认是否存在 Tab 与空格混用。 输出格式要求 - 按文件分组输出问题。 - 每条问题包含文件名、行号、原因、建议修法。 - 如果没有问题明确回答“未发现空白规范问题”。 - 只报告不修改。这个文件放在.claude/agents/whitespace-guard.md下就行。是不是很简单但就是这么简单的一个配置里面有几个点很值得细讲。3.2 拆开看每一段的用途先把 frontmatter 拆开看。name 必须是唯一的你可以用驼峰或连字符只要不是中文其实都行中文并不是不行只是后续与文件夹、命令名称的配合会比较麻烦。description 写的是触发条件什么时候用、检查什么、适用范围是什么。这里的关键是让 Claude 的选择器在看到一个完整任务时能准确把任务判断为适合这个子代理处理。描述越具体选择器越不容易跑偏。正文部分我把它当作一份上岗手册来写。第一段交代身份和纪律“只做检查不修改任何文件”第二段给工作流程按顺序列出要用的工具和正则第三段写死输出格式。你可能觉得第三段没什么用但经验告诉我不规定输出格式的子代理很容易打出洋洋洒洒一大段分析文字最后你需要的信息可能埋在第五段里。让输出模板化主代理拿回结果后也能更快地把关键结论转述给你。再看 tools 字段我只给了 Glob、Grep、Read没有给 Edit也没有给 Bash。这个设计就是让它成为一个纯粹的观察者。它看到的问题只能写进返回结果不能自己动手改真正改成什么样由主代理或你自己决定。所以它不会在执行中突然开始改文件把项目弄乱。3.3 如何验证它真的被调用创建完这个文件后你并不需要专门注册。退出并重启 Claude Code然后在任意一个项目里制造一点行尾空白请主代理“检查一下当前目录的空白规范”。如果主代理判断合适就会调用 whitespace-guard。你可以通过调试信息或运行日志观察调用结果不同版本展示路径不一样但基本都能看到它调用了哪个子代理。第一次跑通之后建议你故意留一个问题再确认它的输出。例如在某文件末尾删掉换行看子代理是否真的报出来。这个过程非常重要因为很多子代理配置写错了并不会直接报错而是表现为“主代理好像自己顺手做了”并没有真正触发子代理。所以你必须在验证阶段就确认调用真的发生否则后面所有自动化都是空中楼阁。4. 再写两个实战子代理代码审查与测试生成学会了最简单的读类型子代理接下来就可以挑战带更多权限和更复杂提示词的实战角色。我常用的两个角色是代码评审员和测试生成器它们覆盖了绝大多数日常开发场景也很能说明创建方法里的设计思路。4.1 代码评审员配置第二个例子是一个 code-reviewer。它和第一个最大的区别在于需要阅读 diff 相关文件并且要输出评审结论。它可以用 Read、Grep、Glob不必给 Edit 和 Bash。--- name: code-reviewer description: 当需要审查代码变更、检查潜在 bug、安全隐患、可读性问题时使用。适合在提交 PR 前对变更文件做一轮静态评审。 tools: Read, Grep, Glob model: sonnet --- 你是资深代码评审员。你不会修改代码只输出评审意见。 工作流程 1. 先了解用户提供的变更文件或 diff 内容。 2. 用 Read 读取目标文件。 3. 用 Grep 搜索可疑模式TODO、FIXME、console.log、debugger、硬编码密钥等。 4. 结合上下文判断问题严重程度。 输出格式 - 按严重程度分成阻塞/Bug、安全隐患、建议改进、风格问题。 - 每条意见给出文件路径、行号或代码片段、原因、修改建议。 - 只输出你确有把握的问题不要为了凑数编造风险。这里需要说明的一点是reviewer 的边界感必须非常强。有些子代理一看到代码里面有空行缩进不对就开始输出一大片风格意见结果真正的逻辑缺陷被淹没。所以我在 system prompt 里明确写了按严重程度分级并且要求不要凑数。这个原则对任何审查类子代理都适用质量优于数量不要用一堆琐碎意见淹没真正重要的问题。4.2 测试生成器配置第三个例子是一个测试生成器。它需要读代码结构还需要把生成的测试文件写进去所以 tools 里要出现 Edit 或 Bash。到底给哪个取决于你希望它用什么方式创建文件。最稳妥的是给 Edit让它直接编辑或新建文件如果项目里已经有测试命令也可以给 Bash 执行测试命令但要接受它跑命令的行为。--- name: test-writer description: 当需要为指定函数或模块生成单元测试时使用。可以读取源码、编写测试文件并尝试运行测试命令。 tools: Read, Grep, Glob, Edit, Bash model: sonnet --- 你是测试工程师负责为指定代码补充单元测试。 流程 1. 用 Grep/Glob 定位被测模块。 2. 用 Read 阅读源码和现有测试文件。 3. 理解被测函数的输入输出和边界条件。 4. 用 Edit 在测试目录下新建测试文件遵循项目已有测试框架风格。 5. 用 Bash 运行当前测试命令只观察是否通过不要尝试修复源码。 输出 - 列出你创建/修改的文件。 - 说明覆盖了哪些正常路径和边界条件。 - 如果测试失败给出失败原因定位不进行源码修复。这个配置我刻意在最后写了“不进行源码修复”。原因很简单子代理的任务边界一旦蔓延它就会从“写测试”变成“顺带改源码”最后你可能分不清哪些改动是主代理做的哪些是子代理做的。把任务钉死结果才可控。如果你希望子代理帮忙修复测试暴露出的问题那应该是另一个子代理的活而不是在同一个任务里既写测试又改源码。4.3 通过 Task 工具实现子代理再嵌套最后提一个高级一点的操作tools 字段里可以包含Task。一旦一个子代理拥有 Task 工具它可以在自己的上下文中再次启动另一个子代理。这就像小组长领到工作后又把一部分工作分给组员。不过嵌套层级越深你越难追踪上下文和权限费用也会指数级增长。通常我不建议超过两层主代理派给一级子代理一级子代理最多再派一级。如果你要做一个复杂的流水线优先考虑在主代理层面用多个子代理做串行或并行调度而不是手写一个巨大的嵌套子代理。主代理是总导演子代理是演员不要让演员再去当导演。后续如果要深入聊编排我会单独再写这里你只要知道配置里有这种可能性就行。5. 创建过程中的五个高频翻车点和对应解法理论讲再多不如看真实的坑。我自己的子代理配置经历过无数次“看起来能用实际一跑就废”的阶段。下面这五个问题几乎每个人都会遇到至少一个。5.1 description 写得像废话等于没写我见过不少配置文件description 写的是“用来处理代码相关任务的代理”这基本等于没写。Claude 在做任务分配时需要从这句话里判断要不要调用这个子代理。如果你的描述太宽泛它可能该调用时不调用不该调用时乱调用。正确做法是把触发条件、输入范围、输出目标都浓缩进一两句话里尽量出现具体行为词例如“检查行尾空格”“生成 pytest 测试”“分析日志中的 500 错误”。5.2 tools 少写一个任务就卡在中途这是另一个高频翻车。子代理没有 Bash 工具却要在配置文件里说自己会跑测试那它执行到跑测试那一步就会卡住或者尴尬地对你说“我没有权限执行命令”。你可以在日志里看到工具调用失败。解决办法坦率讲只有补齐工具权限或者改造流程让子代理不依赖那个工具。创建之后对照一下配置正文里提到的动词读文件需要 Read搜索需要 Grep/Glob编辑需要 Edit 或 Write执行命令需要 Bash。5.3 system prompt 没限定输出格式结果变成废话文学如果你只写“请检查这个文件有没有问题”而不规定输出格式子代理很容易给你一大段分析性废话。它可能把原本只有三行的结论扩展成超长评论。我的习惯是在 system prompt 后面固定一个“输出格式”小节明确用 Markdown 表格、编号列表或 JSON 返回。子代理只要被调用主代理拿到的就是结构化结果你再让它整理转述都方便。5.4 和主代理抢工具造成权限冲突有时候主代理和某个子代理工具权限不一致。比如主代理已经允许自动编辑子代理却没配置 Edit主代理把任务派给它之后它只能半途停下请求权限。这种问题不是 bug而是权限模型本身。你应当把子代理当作独立的小号权限是单独算的。启动复杂任务前先把子代理需要的所有工具想清楚不然排查起来很费时间。5.5 嵌套子代理没有出口直接烧完配额最后一个翻车点非常隐蔽你在子代理的 system prompt 里给了它过多自由又没有限制它必须返回结果它可能会自己再调用别的子代理层层展开最后就像递归没有出口一样消耗了大量时间与额度。配置嵌套 Task 时一定要在 prompt 中写明“除非绝对必要不要创建孙代理”如果只是想让某个子代理单独完成一件小事连 Task 工具都不要给它。高频问题典型症状我的解法description 太宽泛该调用时不调用不该调用时乱调用写具体行为词写触发场景tools 缺失执行中途说无权限任务卡住对照正文动词补齐工具输出格式没定义返回大段分析废话在 prompt 里固定输出模板权限冲突子代理半途请求权限单独检查子代理的 tools 列表嵌套无出口层层调用烧完额度不必要就不给 Task 工具6. 我平时怎么组织 Sub Agent 配置文件经验清单到了这一步你已经知道怎么创建单个子代理了。但真正让子代理体系好用起来靠的是一套稳定的组织方式。这一节我把自己的经验整理成一个可复制的清单也算给前面所有创建方法做一个收口。6.1 目录、命名与版本管理平时我把项目里的子代理放在.claude/agents/下每个文件都以 agent 名称命名目录结构可以按角色再分子目录比如reviewers/、generators/、analyzers/但注意子代理的 name 字段要保持全局唯一不一定要和路径一致。团队协作时把整个.claude/目录纳入版本管理新成员 clone 下来就能直接用。这里建议不要在子代理文件里写与项目无关的绝对路径这样换机器、换环境后仍然能跑。6.2 我的子代理文件规范模板我自己的文件规范大致是固定的frontmatter 必填 name、description、tools、model正文固定分成“身份与边界”“工作流程”“输出格式”三段。前两段告诉它“你是谁你能做什么”第三段告诉它“结果长什么样”。这个模板来自我踩过的很多坑专门用于减少输出废话和越权操作。--- name: sample-agent description: 触发条件与使用场景必须具体。 tools: Read, Grep, Glob model: haiku --- # 身份与边界 你是一个专门负责……的子代理。 绝不做……绝不修改……。 # 工作流程 1. 第一步…… 2. 第二步…… # 输出格式 - 必填字段…… - 使用 Markdown 表格……我把这段模板直接保存成一个文件模板新建子代理时复制一份只改动具体内容。你可以根据项目需要调整段落但三段式结构强烈建议保留。尤其是“身份与边界”这个段落很多子代理出错都是因为在 prompt 里没有明确“不要做什么”导致它在不该做的地方自由发挥。6.3 一个被忽略的细节把子代理喂给团队最后想说一个容易被忽略的细节子代理不只是个人效率工具也是在团队中沉淀规范的好地方。你把团队的代码风格检查、PR 评审重点、测试框架要求写成子代理配置文件放进仓库后所有人都共享同样一套执行标准。这比在 wiki 里写一堆文档有用得多因为文档是给人看的子代理是直接干活的。哪怕团队里有人不会写 prompt他也能通过调用子代理获得同样的结果。当然子代理只是一层配置真正的质量上限仍取决于你的描述和验证循环。我在实际使用中最大的体会是先让一个子代理在最小范围跑通再慢慢扩大它的工具权限和任务边界比一开始就上一个大而全的配置要稳得多。暂时写到这里后面我会继续拆解 Sub Agents 的调度和并行编排如果你也在用 Claude Code 划分子代理可以按这套思路先试一遍然后根据自己的项目改出更顺手的版本。
