1. 先说清楚子代理和普通对话里的角色不是一回事我们在日常用 Claude Code 的时候经常会在系统提示词里塞一堆你是一个某某专家这种设定。很多刚接触子代理概念的朋友会问这跟直接在 prompt 里写角色扮演有什么区别区别大了。子代理Sub-agents在 Claude Code 里是一个独立的执行单元它有自己的一套系统提示词、独立的工具权限、甚至可以用不同的模型来跑。主代理也就是你平时对话的那个 Claude通过 Task 工具把任务派发出去子代理在相对隔离的上下文里执行执行完把结果交回来。这个机制天然保证了几个好处上下文隔离子代理收到的不是你的全部对话历史而是任务相关的指令和内容。这避免了主上下文的污染也大幅降低了 token 开销。专注度可控如果你在系统提示词里同时塞了十几个职责模型很容易精神分裂。子代理天然只干一件事不会被其他指令干扰。资源按需分配复杂推理任务可以指定更强的模型跑简单任务用轻量模型省钱省时间。简单做个类比主代理就像项目组的负责人什么活都接子代理是组里几个专家负责人接到对应领域的活儿就把专家叫过来处理。专家只处理自己专业的活干完交结果不掺和别的。Claude Code 内置了一批基础的子代理像网页搜索、读取 PDF 这类通用能力。但很多人会遇到一个现实问题内置的代理太通用了它不知道你项目的规范、不了解你们的代码风格、也没法执行公司内部的流程。这时候自定义子代理就是必须掌握的能力。2. 内置子代理的边界和自定义的真正动机内置子代理解决的是通用任务它们的设计目标是让大多数用户在大多数场景下都能用。但落到真实项目里你会发现几个明显的断层第一内置代理不了解你的项目背景。我试过让内置的代理帮忙做代码评审结果它只会机械地检查语法和明显的逻辑错误完全不知道我们这个项目的约定是接口返回必须带 traceId、状态码必须走统一枚举。这些项目级的知识内置代理一概不知。第二内置代理的工具权限是固定的。有些任务需要读数据库连接配置来生成文档有些需要跑测试命令来验证修改内置代理不会主动去碰这些工具或者给了权限也不知道怎么组合使用。第三内置代理的输出格式不符合团队习惯。我们团队要求代码评审必须输出风险等级、影响范围、建议改法三段式内置代理输出的东西还得人工二次整理。自定义子代理解决的就是这些项目特有的问题。你可以在子代理的系统提示词里写入项目规范、代码约定、团队流程可以限制它只能访问某些工具可以指定它用哪个模型来跑。说白了就是为具体项目场景造一个专属专家。那是不是所有场景都需要自定义也不是。如果只是偶尔查个网页、读个 PDF内置的完全够用。自定义子代理的适用场景通常有几个特征任务会反复发生不是一次性需求任务有明确的项目上下文通用 prompt 搞不定任务对输出格式有稳定要求希望每次产出一致任务需要固定的工具组合和流程如果你手头的工作满足两三条那就值得花点时间做一个自定义子代理。3. 自定义子代理的完整格式与字段拆解自定义子代理的本质是一个 Markdown 文件放在项目的.claude/agents/目录下Claude Code 启动时会自动加载这个目录下所有代理定义。每个文件对应一个子代理文件名就是代理的身份标识相关。3.1 目录结构与命名规则你的项目/ ├── .claude/ │ ├── agents/ │ │ ├── code-reviewer.md │ │ ├── ts-migrator.md │ │ └── ... │ └── ...注意几点目录名必须是.claude/agents/拼错一个字母都加载不出来。文件名建议全部小写用短横线连接单词。路径名会出现在 Task 工具的上下文里太长太随意会影响触发匹配。团队协作时这个目录应该提交进版本库让所有成员共享同一套代理配置。3.2 Frontmatter 字段详解每个代理文件的头部是 YAML 格式的 frontmatter定义元信息。格式如下--- name: code-reviewer description: 当需要代码评审、审查代码质量、评估改动风险时使用。适合提交代码前的自查和团队代码评审场景。 tools: Read, Grep, Glob, Bash model: sonnet ---逐个字段说name代理的唯一标识最好和文件名保持一致。这个字段主要给内部识别用保持简洁清晰即可。description这是最重要的字段。它不是给人看的是给主代理的匹配器看的。主代理拿到一个任务时会读取所有子代理的 description然后判断哪个代理适合处理当前任务。所以 description 要写得像搜索关键词把你希望触发这个代理的场景都覆盖到。tools允许该子代理使用的工具列表逗号分隔。常见的包括工具名用途典型场景Read读取文件内容分析代码、读文档Write写入文件生成代码、改配置Edit精确编辑文件局部修改代码Grep搜索文件内容定位关键逻辑Glob按模式查找文件找指定类型文件Bash执行 shell 命令跑测试、装依赖提示tools 字段是白名单机制不写就默认没有权限。有个隔离的好处是防止子代理拿到不该碰的工具。但注意千万别把 Bash 忘掉否则子代理想跑测试都跑不了。model指定该子代理运行的模型。可选值一般是 sonnet、opus 这类标记。选型的逻辑很简单任务复杂度越高、越需要推理能力就用更强的模型简单任务用轻量模型省成本。注意这个字段可以不写不写的话默认继承主配置的模型。3.3 正文系统提示词的写法Frontmatter 下面是正文这就是子代理的系统提示词。写法上跟给主代理写系统提示词类似但有两个关键区别子代理的上下文不包含你的对话历史所以背景信息要写全。默认它只知道你派发任务时给的那点上下文其他项目信息一概不知。正文里可以引用.claude/目录下的共享文件。比如你可以在正文里写代码规范参考 .claude/rules/code-standard.mdClaude Code 会把这些文件内容拼进子代理的上下文里。下面是一个典型的结构你是一名严格的代码评审专家。你的职责是对给定的代码进行深度审查识别潜在缺陷、安全隐患和性能问题。 ## 评审流程 1. 先用 Glob 定位目标文件用 Read 读取完整内容 2. 结合项目的编码规范见 rules/code-standard.md逐项检查 3. 输出评审结论 ## 输出格式 严格按照以下格式输出 ### 风险等级 - P0必须修复的严重问题安全漏洞、数据丢失风险 - P1应该修复的重要问题逻辑错误、边界未处理 - P2建议改进的优化点性能、可读性 ### 发现的问题 按等级列出每项包含文件位置、问题描述、原因分析、修复建议 ### 总体结论 用不超过 3 句话概括本次评审结果这里有三个原则值得强调明确流程、明确格式、明确边界。子代理默认情况下就像一张白纸你越明确地告诉它先做什么再做什么它执行起来的稳定性就越高。我用过一段时间的体感是有流程定义的子代理比自由发挥的子代理输出质量稳定得多。4. 一个能直接抄作业的实战案例理论讲再多不如直接上手一个案例。我用代码评审代理当例子完整演示从立项到落地的全过程。4.1 项目背景我们团队最近接了一个中等规模的 Web 项目多人协作代码风格需要统一提交前要过一轮评审。之前评审全靠人工效率低还容易漏。我准备写一个 code-reviewer 子代理接入 Claude Code 的工作流里帮忙做第一轮机器评审。4.2 代理文件在.claude/agents/下新建code-reviewer.md--- name: code-reviewer description: 用于代码评审和代码质量检查。当你需要审查代码改动、发现潜在bug、评估代码安全性、检查代码是否符合项目规范时使用 code-reviewer。适合在代码提交前、合入主干前做质量把关。 tools: Read, Grep, Glob, Bash model: sonnet --- 你是一名资深的前端代码评审专家熟悉现代 Web 开发技术栈。你的目标是在代码合入前发现所有值得关注的问题。 ## 项目背景 - 技术栈TypeScript React Node.js - 关键约定所有接口返回结构必须包含 code、message、data 三个字段异步操作错误必须用 try-catch 包裹并做兜底处理禁止在组件内直接写内联样式统一走样式文件 - 安全红线任何用户输入必须经过校验禁止直接拼接进 SQL 或 HTML ## 评审步骤 1. 使用 Glob 查找待评审文件确认文件列表 2. 逐个用 Read 读取文件完整内容 3. 对照项目背景中列出的约定逐项检查 4. 如有必要用 Grep 在项目中搜索相关调用确认改动的影响范围 5. 汇总输出评审报告 ## 评审维度 - 逻辑正确性边界条件、异常分支、异步竞态 - 安全性输入校验、注入风险、敏感信息处理 - 一致性命名规范、接口返回结构、错误处理方式 - 可维护性函数复杂度、重复代码、模块依赖 ## 输出要求 严格按以下格式输出 ### 评审范围 列出本次评审涉及的文件列表 ### 发现的问题 按严重程度分组列出 - P0必修安全问题、会导致线上故障的问题 - P1应修逻辑错误、明显的代码质量问题 - P2建议优化点、风格问题 每个问题包含文件路径、具体行号、问题描述、修复建议 ### 评审结论 最后给出一段不超过 100 字的总结明确本次改动是否可以合入。4.3 使用方式写好之后直接在 Claude Code 对话里说用 code-reviewer 评审一下 src/modules/payment 目录下最近改动的代码主代理会读取这个任务的意图匹配到 code-reviewer 的 description然后通过 Task 工具把这个任务派发出去。子代理收到指令后会按照我写的系统提示词开始工作先找文件、读文件、对比规范、输出报告。这个过程你不需要手动指定工具或步骤全在子代理内部完成。你看到的就是一个独立的评审报告返回。4.4 实际效果与调优我第一次跑这个代理的时候输出质量整体不错但有两个问题问题一它评审的时候只看了单个文件没有跨文件追踪调用关系。比如某个函数在 A 文件被改了签名B 文件还在用旧签名调用它没发现。问题二输出里有两处误报把本来合规的代码标成了 P1。针对问题一我在系统提示词的评审步骤里加了一步如果改动涉及公共函数或导出接口用 Grep 搜索项目中所有对该函数的引用确认调用方兼容性。加了这个之后跨文件问题基本能抓到了。针对问题二我在输出要求里加了对于判定为 P1 及以上的问题必须附上具体代码引用和解释避免误判。逼着它给证据误报明显减少。这类调优说白了就是喂反馈。子代理系统提示词里写得越细执行越稳定。每次跑完发现漏了什么就往步骤里补一条规则迭代几次之后基本就固化了。5. 我在实际项目里踩过的坑用了一段时间自定义子代理遇到的坑不算少。挑几个典型的说说省得大家重复交学费。5.1 代理找不到description 写得像个谜语第一次写完代理兴冲冲去对话里说帮我做个 review结果主代理完全没理会它直接用主对话的模式回答了一通。我第一反应是文件名不对检查了目录结构没问题。后来才意识到是我 description 里的触发词没覆盖到review这个说法。原理很简单主代理判断用哪个子代理靠的就是 description 的语义匹配。不是精确的编号匹配而是理解任务意图然后找最合适的。注意description 里一定要把你和团队成员习惯说的口语词都写上。比如既能用代码评审也能用code review、检查代码质量、过一遍改动全都铺进去匹配率才会高。5.2 子代理没权限Bash 忘写了有个场景是让子代理帮忙跑测试验证改动结果它告诉我没有权限执行 Bash。我愣了一下回去看 tools 字段只写了 Read、Grep、Glob 三个。子代理确实读懂了代码、给出了修改建议但无法跑测试来验证。这个坑的教训是在设计子代理时想清楚它要做什么每加一个职责就确认一下对应的工具权限。做代码生成就补 Write/Edit做测试就跑 Bash做依赖分析就加 Grep。5.3 子代理太笨模型选错有个文档生成代理我图省事用了轻量模型跑。结果生成的文档结构混乱还有几处明显的臆测内容。后来换成更强的模型效果好了一个档次。模型选型这事别省凡是涉及代码生成、逻辑推理、多步骤判断的任务尽量用能力更强的模型纯文本抽取、格式转换这类线性任务才适合轻量模型。省下来的 token 不值得赔进去的时间。5.4 多个代理互相打架项目里代理一多问题也跟着来。有一次我发现一个代理频繁被错误触发排查下来是 description 和另一个代理的语义范围重叠太多。主代理有时候会随机选一个导致输出完全不符合预期。解决方案很直接给每个代理的 description 划清楚边界。比如一个管后端接口评审一个管前端组件评审description 里明确写上仅用于后端改动或仅用于前端界面相关。另外也要控制代理总数。我的经验是一个项目保持在五六个以内太多了一是匹配容易乱二是维护成本上去了。5.5 代理上下文太小背景信息不足前面说过子代理默认不继承对话历史只拿到任务相关的上下文。有次我让它生成一个新模块的代码它在没有背景的情况下硬编产出的代码风格和项目完全不一致。解决思路有两个层面一是在系统提示词的项目背景部分写清楚技术栈、目录结构、编码约定二是把大文件内容放到.claude/rules/或.claude/context/目录下用 符号引用让 Claude Code 自动拼进子代理上下文。常见问题典型表现解决办法代理触发不了主代理无视代理直接回答重写 description覆盖更多触发词工具权限不足子代理说没法执行操作tools 字段补全所需工具输出质量差幻觉、结构混乱更换更强的模型细化输出要求代理互相冲突任务派给错误的代理划清 description 边界控制代理数量不了解项目产出不符合规范写全项目背景用 引用共享上下文文件6. 进阶玩法分工协作、MCP 接入和效果边界核心用法掌握之后有几个进阶方向值得探索。6.1 子代理之间互相调用子代理不是只能被主代理调用子代理之间也可以通过 Task 工具互相协作。比如我上面写的 code-reviewer发现某个问题跟后端接口有关它可以再派一个 api-schema 代理去检查接口定义。这种层层分派的设计能把一个庞大任务拆成多个小任务并行处理。不过要注意子代理之间的协作需要你在系统提示词里显式允许并且明确任务边界。不加约束的话代理之间容易互相踢皮球或者一个代理干了一大堆本来不该它干的活。6.2 接入 MCP 服务器如果你在 Claude Code 里配了 MCP 服务器比如数据库查询、内部知识库、任务管理工具自定义子代理也可以声明使用这些 MCP 能力。做法是在 frontmatter 或者系统提示词里声明允许使用的 MCP 服务。这个组合的效果很惊艳。拿数据库来说子代理可以直接连上开发库做结构分析、查数据分布产出的方案会精确得多。我们内部有个负责 SQL 优化的代理效果好的一个例子是直接定位到一个慢查询的索引缺失问题省了 DBA 半天时间。6.3 什么时候不该用自定义子代理最后提一个反直觉的经验不是所有任务都适合做成子代理。一次性任务如果这个需求就出现一次没必要做成代理直接在对话里让他处理就行。做成代理的维护成本反而高。需要强交互的任务子代理是派出去干活然后把结果带回来的模式中间过程你基本没法干预。如果任务需要多次确认需求、来回调整还是留在主对话里做。极高复杂度任务子代理上下文有限一个任务如果涉及十几个文件、跨多个模块的大重构建议拆成多个小任务交给多个代理或者干脆主对话里分步处理。自定义子代理是一把好用的刀但刀的价值在于刀刃和刀柄各有分工。用对了地方效率翻倍用错了地方反而添乱。我自己的感受是迭代子代理就是一个投资的过程前期花时间把规范、流程、输出格式写清楚后面每一次使用都省时间、稳定产出。那种写了一个代理用了三个月团队每次评审都走它的感觉真的挺值的。你的项目里如果有反复出现的固定任务不妨挑一个试试手。