Claude Code自定义子代理：从内置局限到团队专属AI角色-北京尧图网络

写这篇文章的动机其实来自我在实际项目里的一次崩溃式体验——用 Claude Code 处理一个跨模块重构任务时默认的 Agent 行为总是在主对话里“大包大揽”一会儿分析代码、一会儿查文档、一会儿给建议上下文越拖越长最后核心任务反而跑偏了。研究了一圈才发现这工具本身就支持子代理subagents机制用户可以自定义一套属于自己项目和团队的 Agent 角色把高频且独立的任务拆分出去。这个功能的价值远不止加几个角色而是重新理解了 AI 编程工具的分工逻辑。这篇文章就聊聊我怎么从内置子代理不够用到自己造了几个趁手子代理的完整过程包括配置文件的写法、提示词的设计细节、以及我踩过的各种坑。1. 内置子代理到底哪里不够用1.1 子代理机制的本质是什么要理解自定义子代理的价值先得搞清楚 Claude Code 的 Agent 调度模型。它并不是一个单一 AI 在从头到尾干所有事而是有一个主对话 Agent 来理解你的整体意图、拆解执行步骤再按需调度不同的子 Agent 去完成特定任务。这些子 Agent 有独立的系统提示词、独立的上下文窗口、独立的任务边界干完之后把结果汇总回主对话。这个机制的设计初衷非常像大型团队的协作方式主 Agent 是团队负责人子 Agent 是专项组。如果所有事都堆在主 Agent 的上下文里对话一长前面的信息会被截断模型的注意力会被稀释输出质量也会肉眼可见地下降。子代理存在的意义本质上是把复杂任务做上下文隔离——各干各的最后交付结果。听起来很完美但实际用了就会发现问题。1.2 内置子代理的典型局限Claude Code 默认会提供一些内置的子代理角色比如负责生成提交信息的、负责生成测试用例的、负责审查代码的。我刚上手时觉得挺省心但随着项目深入内置子代理的短板暴露得相当明显。最大的痛点是覆盖面有限。内置子代理的设计目标是通用场景它不可能预料到你的项目有特殊的编码规范、特殊的目录结构、特殊的工具链。比如我们团队用的是自定义的 API 封装层内置的代码审查子代理根本不知道我们的约定审查出来的结果就是正确的废话——语法没错但完全不符合项目实际规范。另一个痛点是职责定位过于宽泛。内置的代码审查子代理既要检查风格、又要查逻辑、还要看是否缺少注释什么都会的结果就是什么都浅尝辄止。我给它的任务颗粒度一旦细化比如只检查这个接口是否有输入校验缺失它往往还是按照自己的泛化模板来回话上下文消耗不小产出却不够聚焦。还有上下文管理的效率问题。内置子代理被调用时会携带一部分主对话的信息如果项目里有大量公共工具类、类型定义、配置文件内置子代理经常反复读取同样的内容造成 token 浪费。自定义子代理可以用精准的系统提示词告诉它不要读哪些文件把上下文留给真正需要的部分。如果你只是写脚本、做小 Demo内置子代理完全够用。但一旦进入真实项目、有明确的代码规范、有反复出现的高频任务内置子代理就会成为瓶颈。这也是我决定自己造的直接原因。2. 自定义子代理的工作原理与配置格式2.1 存放位置与加载机制Claude Code 的自定义子代理通常放在项目根目录的.claude/subbagents/文件夹里也可以放在用户级别的~/.claude/subbagents/。项目级的配置只对当前项目生效适合沉淀团队规范用户级的配置全局可用适合放一些与具体项目无关的通用角色比如通用代码审查或Git 操作助手。每个子代理是一个独立的 Markdown 文件文件名就是子代理的名字比如code-reviewer.md、db-analyzer.md。Claude Code 启动时会扫描这些文件把它们注册为可调度的角色。这里有个非常重要的细节配置改动之后需要重启当前会话才能生效至少在我使用的版本里是这样的改完不重启就发现子代理召唤不出来这个坑我踩过好几次。2.2 配置文件的字段解析每个子代理文件有一个 YAML 格式的 frontmatter文件头用---包裹里面定义元信息下面则是系统提示词正文。核心字段有这些字段名作用说明name子代理的唯一标识调用时用建议与文件名保持一致全小写加连字符description子代理的功能描述这是最关键的一个字段主 Agent 靠它判断何时调用这个子代理tools允许该子代理使用的工具列表不写就带默认工具集写了就严格限制比如只读工具不给写权限model子代理使用的模型配置可选不写就用主对话的模型配置system prompt子代理的系统提示词文件头下面的正文部分定义角色行为、输出格式、操作边界顺便提一下model字段。Claude Code 支持给不同的子代理指定不同的模型档位比如轻量的总结任务用较小的模型、复杂的架构分析用较大的模型。这个配置在节省成本方面很有效——不是所有任务都需要满血模型来处理分类一下能省不少 token。2.3 触发逻辑description 是召唤口令子代理的调度逻辑非常简单粗暴主 Agent 收到用户指令后会浏览所有子代理的description字段根据语义判断哪个角色适合处理当前任务然后自动调度。所以你写的description就是子代理的召唤口令要写得精准、可匹配、覆盖触发场景。写这个字段最常见的问题是两个极端。一个是写得太宽泛比如负责所有代码相关工作那主 Agent 什么任务都可能丢给它不仅干扰主任务还容易抢活。另一个是写得太狭窄比如负责检查 user.go 文件的错误处理那主 Agent 基本永远想不到用它因为触发面太小。我的经验是用当用户需要处理 X 任务时这个子代理可以提供 Y 输出的句式明确职责和产出物让主 Agent 能清晰判断匹配关系。3. 自己动手做一个代码审查专家子代理3.1 需求分析与设计思路我做第一个自定义子代理时场景很简单团队有一套后端服务代码入库前大家会不定期用 Claude Code 帮忙过一遍逻辑。但这个过一遍很模糊——是要检查设计模式还是要按团队的代码规范逐行审或者是只关注性能风险内置的代码审查子代理根本不知道这些我需要一个能按我们项目规范审查的子代理。我定的需求是这样的输入是一个文件路径或一段代码输出是三部分——按团队规范检查出的问题、潜在逻辑风险、以及优先级排序。不需要它改代码只做分析和建议因为改动需要主 Agent 和开发者共同确认。3.2 系统提示词的撰写要点系统提示词是子代理的人设写得越精准输出越可控。我设计这个子代理的系统提示词时用了几个原则。明确角色身份和任务边界。开篇直接定义你是一个严格的代码审查员不负责修改代码只输出审查结果。然后列出团队规范的具体条目比如所有对外接口必须做参数校验禁止使用全局可变状态错误处理必须向上抛出而不是吞掉。定义输出结构。我要求它必须按指定格式输出问题描述、涉及文件与行号、严重程度阻断/重要/建议、对应规范条目、修改建议。这个输出结构看起来琐碎但非常关键——它让结果可以被主 Agent 直接消费也方便集成到后续流程里。设置行为约束。明确告诉它不要输出与审查无关的内容不要修改任何文件不要执行测试命令遇到不确定的规范优先在原代码注释中寻找依据而不是猜测。3.3 完整配置示例下面是我的code-reviewer.md文件配置省去了具体项目名的部分保留了核心逻辑--- name: code-reviewer description: 当需要根据团队编码规范审查代码文件、检查逻辑风险或定位性能隐患时使用此子代理。输入文件路径或代码片段输出结构化审查意见。 tools: Read, Glob, Grep model: sonnet --- 你是一名严格的代码审查员服务对象是使用本团队技术栈的后端开发者。你的任务是审查用户提供的代码文件或片段并输出结构化审查意见。团队强制规范 1. 所有对外 API 必须做输入参数校验包括类型、长度、取值范围。 2. 禁止在循环体内发起网络请求或数据库查询。 3. 错误处理不得吞掉异常必须向上抛出或记录日志后显式处理。 4. 函数体超过 60 行时需要拆分。 5. 禁止使用全局可变状态状态必须通过参数传递。输出格式 - 问题列表按严重程度降序排列每个问题包含 - 严重程度阻断 / 重要 / 建议 - 位置文件路径与行号 - 问题描述一句话说清楚问题是什么、为什么是问题 - 规范依据对应上述规范条目或逻辑风险说明 - 修改建议不超过三句话的具体改法行为约束 - 你只做审查绝不直接修改代码文件。 - 不执行测试命令不运行程序。 - 如果代码中已有明确注释说明某处行为的合理性以注释为准并跳过该问题。 - 不要把时间花在格式化或风格类问题上优先关注逻辑与隐患。一个小细节是model: sonnet。审查任务不需要最强的推理能力中等档位足够成本低不少速度也快。如果审查结果出现误判再考虑升级模型档位。3.4 调用方式与实测体验配置好之后调用方式有几种。最直接的是对话里直接说明需求比如用 code-reviewer 审查一下auth/service.go这个文件主 Agent 会自动匹配并调度。另一种是让主对话在分析代码时自然触发当它判断一个任务属于需要详细审查时会自己把子代理拉进来。实测下来第二种方式是子代理价值最大的场景——你根本不需要记着去召唤它主对话会把它当成一个协作者来用。第一次用的时候我对比了一下效果同样一份包含三个潜在空指针风险的文件内置审查只会说这里可能有空指针自定义审查会直接指出具体是哪个变量在哪个分支下可能为 nil、应该加什么校验、对应了团队的哪条规范。这就是内置不够用和自己造的核心差异——输出颗粒度完全不同。4. 再做一个数据库告警分析子代理4.1 场景与设计思路第二个子代理是数据库告警分析起因是团队经常处理线上数据库的慢查询和锁等待问题。这种任务有固定的分析路径——看表结构、看索引、看 SQL 的执行计划、判断是否存在锁竞争——非常适合做成独立的子代理。这个子代理的设计与代码审查有些不同因为它要处理的是片段而不是项目内的完整文件。用户会丢给它一段 SQL、或者一段慢查询日志、或者几个相关联的表结构它需要输出可能的原因和优化建议。而且必须设定边界它只是分析不直接生成修改方案更不执行任何写操作。4.2 上下文隔离的设计数据库分析场景特别容易出现上下文膨胀。慢查询日志往往很长表结构定义也动辄几百行如果这些全塞进主对话其他任务的效率会被大幅拖累。子代理正好解决这个问题——用户把日志片段丢给它它的独立上下文处理完后只输出结论主对话的窗口完全不被污染。但这里也暴露了一个新问题子代理的上下文是冷启动的它不了解项目的表结构全貌。我的解决方式是在系统提示词里给一个引导告诉它先读取哪些公共配置文件、数据库 schema 放在哪个目录、索引命名规则是什么这样它能快速进入状态而不是从零摸索。4.3 配置与提示词示例--- name: db-analyzer description: 当出现慢查询、数据库锁等待、索引失效、SQL 性能异常等需要分析数据库相关问题时使用此子代理。输入 SQL、执行计划或表结构信息输出原因分析与优化建议。 tools: Read, Glob, Grep, Bash model: sonnet --- 你是一名资深的数据库性能分析专家只负责分析不负责修改线上配置。工作步骤 1. 如果提供了日志或 SQL先提取其中的关键信息表名、索引名、涉及的条件字段。 2. 如果用户没有提供完整的表结构先检查项目中是否有数据库 schema 定义文件读取相关部分。 3. 分析可能的原因按概率排列缺少索引 / 索引未命中 / 锁竞争 / 大表扫描 / 数据倾斜。 4. 给出建议每条建议必须对应具体原因并注明需要人工确认的环节。输出格式 - 根因判断一句话结论 - 详细分析按可能性排序的三到五条原因每条附带判断依据 - 优化建议可执行的操作列表明确标注哪些操作需要 DBA 或核心负责人确认后再执行行为约束 - 绝不执行任何写操作包括 UPDATE、DELETE、ALTER。 - 如果你需要查看执行计划可以用只读命令获取但不得修改任何数据库对象。 - 分析内容以用户提供的日志和项目内 schema 为准不要臆测表结构。 - 输出必须区分确定结论和推测结论不混淆两者。这里有个细节值得说tools字段里我加了Bash因为某些情况下需要执行只读命令比如explain来辅助判断。但这也意味着这个子代理有命令行能力所以系统提示词里的绝不执行写操作就非常关键这是安全边界不能省。4.4 实测下来最惊喜的地方这个子代理用了几周之后我最真实的感受是省心。以前遇到慢查询要在对话里交代各种背景信息现在直接把日志丢给子代理它自动读取项目里的 schema 文件给出结论和建议整个过程几乎不需要额外指挥。原来需要三十分钟来回沟通的排查过程压缩到了几分钟。而且它的输出一致性很高——因为系统提示词固定了格式和步骤十次输出有十次的格式都一样不像主对话里人工指挥时每次给的报告结构都不一样。这种稳定输出在团队协作场景下价值极大可以直接把它的报告贴进 issue 里。5. 常见问题与排查技巧实录5.1 子代理为什么不响应这个我踩了太多次。排查顺序大致如下先看文件名和name字段是否一致再确认配置文件是否放在正确的目录然后检查tools列表里是否包含当前子代理需要的基础工具比如需要读文件但没加Read最后看description是否写得太窄导致主 Agent 根本意识不到该用它。还有一个容易忽略的改动配置后需要重启会话不重启就可能继续沿用旧配置甚至完全找不到新子代理。5.2 输出质量忽上忽下如果同一个子代理有时候输出很准、有时候胡说八道通常不是模型的问题而是description触发的输入范围超过了子代理的职责边界。也就是说主 Agent 把不太适合这个子代理的任务也丢给它了。比如我的代码审查子代理设计的是只审查不修复但如果任务里出现帮我修改这个文件里的 bug主 Agent 可能也会调用它结果它就瞎指挥。解决方式是明确在description里限缩触发范围用仅当任务是 X 时才使用这样的措辞。5.3 上下文太长处理不动子代理也会有上下文压力。一个常见的错误是系统提示词里让子代理阅读所有相关文件一旦项目庞大子代理会从头到尾读一堆文件还没开始干活上下文就爆了。处理方式是给子代理设置明确的最小读取原则只读用户明确指出的文件只读 schema 定义不读测试代码不读构建配置。把禁止做什么写清楚比应当做什么更有效。5.4 需要写文件但没有对应权限如果你的子代理任务涉及创建文件或修改代码但内置的tools列表没有包含写入类工具它就会罢工或者只输出建议不动手。实际上我在尝试做一个自动生成测试文件的子代理时配置里忘了加写文件的工具结果它每次都对测试内容分析半天但文件一直没有落盘。排查之后发现就是因为权限列表里少了写入工具。反过来如果不需要写文件就千万不要给写权限——默认最小权限原则能降低子代理误操作的风险。5.5 子代理之间互相抢活当自定义子代理数量变多之后会出现角色职责重叠的问题。比如我同时有代码审查和通用审查两个子代理description都包含检查代码质量主 Agent 就会随机选一个输出的侧重点完全不同导致不稳定。解决方法是做职责收敛同一类任务只留一个子代理或者在description里用明确的关键词区分一个专用于合入前逐行审查一个专用于安全审计互不重叠。5.6 常见问题速查表现象可能原因排查与解决子代理从未被调用description 触发面太窄或不匹配扩大描述范围加入触发关键词子代理什么任务都接description 写得太泛限定任务边界明确仅当...才使用输出格式每次都变提示词未定义输出结构强制指定输出模板不允许自由发挥子代理读了大量无关文件缺少最小读取原则在提示词里明确禁止读取的内容配置改了好几次都无效会话未重启重启会话重新加载配置子代理试图修改文件未限制工具权限从 tools 中移除写工具提示词声明禁止6. 几个让我获益最大经验分享自定义子代理这件事真正让我上头的不是配置格式怎么写而是想清楚什么任务值得被封装成一个子代理。我自己总结的标准是高频、独立、有明确产出物、不需要频繁与主对话交互。如果一个任务需要边想边问、需要不断调整方向那它就不适合做成子代理硬做只会增加调度成本。另外要注意一点子代理的职责虽然是独立分析但最终决策权一定要收在主对话手里。我一开始尝试让子代理直接修改代码并提交结果它一次改了四个文件看代码后发现至少两处修改是不必要的重构还好没造成实际损失。那之后我给所有的写类工具都加了人工确认环节子代理分析主对话审批人做最终判断。这个边界如果守不住子代理走得太远会反噬项目。最后再分享一个小技巧把团队的编码规范沉淀到子代理的系统提示词里是一项几乎零成本的长期收益。每次新增一条团队规范顺手更新对应子代理的提示词你会发现团队的代码风格变化会非常直观地体现在 AI 协作的结果里——因为每个被调用的子代理都默认带着这份规范去工作。到这一步自定义子代理就不仅仅是内置不够用自己造的程度了而是变成了一种项目管理工具。

Claude Code自定义子代理：从内置局限到团队专属AI角色

相关推荐

金三银四网安跳槽指南：十大岗位方向与技术底气解析

tiny11builder 教程：一条命令把 Windows 11 官方 ISO 瘦身为可引导精简镜像

Chrome远程调试Pending authentication报错：从ADB授权到USB调试排查指南

更多资讯

CoCa模型深度解析：对比学习与生成式预训练的融合之路

原生双端音视频社交源码：架构、难点与部署避坑指南

十月AI前端岗面试策略：从被动应答到主动引导

JavaScript计算器入门：解决input值类型转换与四则运算陷阱

ChatGPT智能UI逆向拆解：协议驱动的流式组件渲染与前端架构

大模型Agent记忆系统实战指南：上下文管理、向量检索与遗忘机制

今日更新

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？