1. Subagents 不是另一个功能而是一种工程方法Claude Code 用了小半年我的体感是它完全可以变成一支“单人团队”。关键不在于你有多会写提示词而在于你有没有把任务拆给不同的虚拟角色去干——这就是 Subagents 最核心的价值。第一次接触这个功能时我以为它只是多了一个可调用的工具实际用下来才发现它背后是一整套 AI 角色工程化的思路把一个大而全的助手拆成多个有明确职责、工具边界和输出标准的“岗位”。很多开发者第一次听到 Subagents第一反应是“这不就是把 prompt 写得更细一点吗”其实差别很大。普通提示词是给主代理增加约束让它在一个上下文里同时扮演多种角色而 Subagents 是把角色物理拆开让每个角色拥有独立的系统提示词、独立的工具权限并且只在需要它的时候被加载进来。这样做的好处非常直接主代理不至于“精神分裂”上下文不会被无用的角色设定占满每个子代理的输出质量也能通过独立调优稳定下来。这篇文章不是讲概念的我想从实操角度聊聊Subagents 到底是什么、配置长什么样、怎么从零建一个真正好用的子代理、遇到问题怎么排查。如果你已经在用 Claude Code 处理日常开发任务或者准备把它引入团队流程这篇文章应该能帮你少走不少弯路。哪怕你之前完全没碰过角色工程化按下面的步骤走一遍也能快速上手。1.1 一个主代理扛不住所有角色先说说我最初遇到的痛点。刚开始用 Claude Code 时我会在一段对话里让它既写功能代码又审查安全漏洞还要生成测试用例最后再帮忙写提交信息。结果很典型它会在“全栈工程师”和“安全审计员”之间来回横跳一会儿过度关注边界条件忽略了业务逻辑一会儿又因为指令太多而遗漏关键要求。根子在于所有角色要求和项目背景都压在同一个上下文里。主代理每次生成回复时都要考虑一大堆相互叠加的指令还得猜你当前最想让它做什么。指令一旦互相冲突比如“要快”和“要稳”同时出现它就容易表现出不稳定。Token 也是实打实的开销那些常年挂着的角色设定每轮对话都在消耗上下文窗口真正有用的代码信息反而被挤掉了。这种情况用 Subagents 就顺很多。主代理只负责理解你的意图、拆分任务、调度子代理真正干活的子代理各自只带一份聚焦的系统提示词面对的任务边界非常窄。就好比一个项目经理不需要自己写前端、压测、做安全整改他只要把活派给对应专家就行。项目越大、任务越杂这种分工带来的稳定性就越明显。1.2 角色工程化的核心思路角色工程化这个词听起来挺玄其实本质就是把“人怎么分工”这件事搬到 AI 配置里。一个合格的 AI 角色至少要回答四个问题我是谁、我能用什么工具、我按什么流程干活、我交付什么格式的结果。这四个问题分别对应 Subagents 配置里的系统提示词、工具白名单、工作步骤和输出规范。举个生活化的例子。你让一个实习生去整理数据如果只说“帮我把数据弄干净”他大概率会用自己的方式理解“干净”。但如果你告诉他你是数据分析助理只能读取指定目录的 CSV先做缺失值检查再处理重复项最后输出一份带问题清单的 Markdown 报告。结果就完全不同。Subagents 就是那个有明确岗位说明的“实习生”。从工程角度来看角色工程化还意味着可复用和可维护。每个 Subagent 都是一个独立的 Markdown 文件可以放进 Git 仓库跟着项目走。团队里任何一个人都可以使用同一套角色配置输出风格天然统一。想调整某个角色的行为不需要去改主提示词只需要改那个角色的文件本身。这种隔离性比在 CLAUDE.md 里堆一堆全局指令要干净得多。1.3 什么时候应该上 Subagents不是所有场景都值得拆角色。我自己的判断标准是三条任务是否高频、边界是否清晰、是否需要不同的工具权限。假如你每周都要让 AI 审查一遍代码变更、生成 Commit Message、梳理接口文档这种高频固定流程就非常适合建 Subagent。如果任务边界模糊比如“帮我看看这段代码怎么优化”你可以先手动跑几次把合适的角色说明沉淀下来再固化成 Subagent。相反一些一次性的闲聊式提问或者只需要主代理顺手回答的问题没必要专门建角色。为所有事情都建 Subagent反而会让配置目录变得臃肿主代理在决策时也会因为候选角色太多而产生选择困难。我见过有人建了十几个 Subagent最后结果还不如一个清晰的主提示词好用。角色工程化的前提是你先知道自己的“团队”需要哪些岗位而不是先造一堆角色再找活干。2. 认识 Agent 文件Subagents 的最小可用形态Subagents 的配置本质上就是一个带 YAML frontmatter 的 Markdown 文件。frontmatter 里写角色的元信息比如名字、描述、可用工具和模型正文部分写这个角色的详细系统提示词。第一次看到这种设计时我觉得很妙它把配置和指令合在同一个文件里谁都能看懂也方便版本管理。我建议你把 Subagent 理解成一个“可以被主代理按需调用的独立 AI 实例”。它平时不会出现在主对话里只有被触发时才会带着自己的提示词和工具权限进入工作状态。这种按需加载的设计让每个角色的上下文都非常干净也为主代理腾出了更多空间去处理任务编排。2.1 文件位置与加载机制自定义 Subagents 的存放路径其实不复杂常见的有两个层级项目级和用户级。项目级放在当前项目目录下的.claude/agents/跟着仓库走团队协作时可以直接共享用户级放在用户目录下的.claude/agents/属于个人偏好适合放那些与具体项目无关、所有项目都能用的通用角色。Claude Code 启动时会扫描这些目录把可用的 Subagents 加载进来。你可以在对话里使用/agents命令查看当前有哪些角色可用。如果新建了一个 Agent 文件但列表里没有大概率是路径不对、文件名扩展名不对或者 frontmatter 里的 name 字段有问题。我通常建完文件后第一件事就是敲一下/agents确认加载成功再继续调。加载机制里还有一点非常重要主代理能不能“看到”这个 Subagent取决于它的 description 字段。主代理会根据 description 的内容判断当前用户请求是否适合交给某个子代理。所以 description 不是随随便便写一句“代码审查工具”就完事的它相当于角色对外展示的名片和触发条件。2.2 核心字段逐个拆解Agent 文件里的 frontmatter 字段我常用到的主要有四个name、description、tools、model。name 是角色的唯一标识尽量用英文小写和短横线比如code-reviewer、test-generator不要带空格和中文。name 主要用来显式触发在对话中直接输入code-reviewer就能手动指定这个角色处理当前任务。description 是整个文件里最重要的字段没有之一。主代理靠它做路由决策所以要写清楚“这个角色擅长什么”“什么时候应该调用它”。我习惯用触发句式来写比如“当用户要求审查代码、检查代码质量、提交前 review 时使用”。如果只写“负责代码审查”主代理很多时候会觉得自己顺手就能做根本不调用 Subagent。tools 字段用于限制这个角色能使用哪些工具。常见的工具包括 Read、Write、Edit、Grep、Glob、Bash 等。工具白名单是 Subagents 的安全边界也是职责边界。审查类角色只需要只读工具那就别给它 Edit 和 Write执行重构的角色才需要写文件的权限。minimal 原则在这里特别适用给得越少出幺蛾子的概率越低。model 字段用来指定该角色使用的模型等级可以根据任务复杂度灵活选。简单、重复度高的任务可以选择成本较低的模型复杂代码分析或大规模重构可以让它用更强的模型。这个字段不是必须配置的如果省略会继承主对话使用的模型。我建议对成本敏感的场景显式配置方便控制开销。2.3 系统提示词的写法要点Agent 文件的正文部分是真正的角色说明书也是决定输出质量的关键。写正文时我一般遵循一个公式角色定位 工作流程 输出规范 禁止事项。角色定位告诉它“你是谁”工作流程告诉它“先做什么再做什么”输出规范告诉它“最后交什么格式”禁止事项告诉它“哪些事情绝对不能做”。这里有一个容易被忽略的点Subagent 不是全权代理。它的工作结果最终要交回给主代理由主代理整合后再呈现给用户。所以正文里最好明确写上“你只负责分析不要修改任何文件”“你的所有结论必须基于实际读取的代码不能凭空猜测”。如果不加这类约束子代理很容易越权或者产生一些看起来很合理但其实没有依据的输出。输出规范越具体越好。与其写“请给出高质量建议”不如写“请用表格输出问题清单包含严重级别、文件路径、行号、问题描述、改进建议”。我踩过不少坑最典型的就是子代理给出一堆“要注重可维护性”“需要优化性能”这种正确的废话。后来我在每个角色的输出规范里都加了“必须引用具体文件和行号否则视为无效结论”效果立竿见影。3. 完整示例手搓一个代码评审 Subagent说再多理论都不如直接跑一遍。这一节我会用一个我自己很常用的场景——代码评审带你从零建一个只读代码审查 Subagent。这个角色的定位很简单发现代码里的逻辑错误、安全隐患、性能问题和可维护性隐患但绝不动手改代码。选这个场景是因为它边界清晰工具权限容易控制而且几乎任何项目都用得上。我一直觉得代码审查是 Subagents 最好的入门项目。它的任务不会太复杂输出格式可以标准化失败模式也很直观——如果角色描述写得不好主代理就不会调用它如果系统提示词写得不够细输出就会泛泛而谈。你可以通过这个小项目把 Subagents 的整套机制摸透之后再建复杂的角色就有感觉了。3.1 场景定义与角色边界先明确需求。我想要的审查角色应该能接收一个文件路径或目录作为输入然后使用只读工具去分析代码。它需要具备发现逻辑漏洞的能力但不能写代码需要能定位到具体文件和行号但不能修改任何内容。这个边界必须写死否则它在“提建议”和“直接改代码”之间就可能越界。触发条件也要提前想好。我希望当我在对话里说“审查一下这段代码”“提交前帮我看看有没有问题”“review 一下上次的改动”时主代理能自动把这个任务交给code-reviewer。所以 description 里就要包含这些触发句式。如果你希望在特定场景手动指定那么通过code-reviewer也可以强制执行两者并不冲突。除了角色边界我还定义了输出格式一个 Markdown 表格列分别是问题级别、文件与位置、问题描述、修改建议。问题级别我习惯用 P0、P1、P2 表示P0 是必须修复的严重问题P1 是建议修复的逻辑问题P2 是一般的优化建议。这种分级能让我一眼看到优先级也方便后续把结论同步给团队。3.2 创建 Agent 文件实际操作时我会在项目根目录下创建.claude/agents/code-reviewer.md然后写入以下内容。这里直接把完整配置文件贴出来你可以根据自己的项目情况调整描述和正文。--- name: code-reviewer description: 对指定的代码文件或目录进行静态审查识别逻辑错误、安全隐患、性能问题、可维护性缺陷并输出结构化审查报告。当用户要求“审查代码”、“检查代码”、“review 代码”、“提交前看看”时优先使用。 tools: Read, Grep, Glob model: sonnet --- 你是一名只读代码评审工程师负责对用户指定的代码进行深入检查。 工作流程 1. 使用 Glob 和 Grep 定位目标文件理解项目结构和代码入口。 2. 使用 Read 阅读关键文件优先分析业务核心路径和异常处理分支。 3. 只输出审查结论不修改任何文件不执行任何代码变更。 输出规范 - 使用 Markdown 表格输出问题清单表头必须包含问题级别、文件与位置、问题描述、改进建议。 - 问题级别按 P0/P1/P2 分级P0 表示必须修复的严重逻辑错误P1 表示推荐修复的隐患P2 表示可选的优化建议。 - 所有结论必须基于实际读取的代码明确标注文件和行号没有足够依据不要臆测。 - 如果没有发现问题明确说明“未发现明显问题”禁止为了凑数编造问题。文件保存后在 Claude Code 会话里输入/agents如果列表里出现code-reviewer就说明加载成功了。这里有个小细节文件名和 frontmatter 里的 name 最好保持语义一致但 name 才是实际触发用的 ID所以即便文件名不同只要 name 唯一就能正常工作。3.3 调试与验证创建完成后我会用一个真实文件做验证。比如我写了一个简单的函数然后对 Claude Code 说“帮我审查一下src/utils.js”。如果主代理正确识别出了这个任务并调用code-reviewer那我应该能在回复里看到一个符合输出规范的审查报告。如果它没有调用而是自己直接在主对话里分析了一通说明 description 的触发信息还不够强。如果发现子代理没被自动调用我一般会先手动试一次直接输入code-reviewer 审查 src/utils.js强制它出场。这一步能区分问题是出在路由还是出在角色本身。手动调用能正常工作但自动路由失败基本就是 description 的问题手动调用都失败那就得回到角色正文里找原因可能是工具权限不足也可能是系统提示词里的需求描述不清晰。第一次输出往往不会完美。常见的问题是表格列名不一致、行号引用不准确、或者问题描述太宽泛。这时候我不急着改正文我会先根据输出反推哪个环节缺了约束。比如它没给行号我就在输出规范里加一句“必须标注文件绝对路径和起始行号”它编了几个不痛不痒的问题我就会在禁止事项里加上“没有发现明确问题时必须如实说明”。这样迭代两三次角色就会变得非常好用。3.4 进阶多角色协作代码审查跑通之后你自然会想扩展更多角色。比如我后来加了一个refactor-planner专门负责分析重构方案它同样只读代码文件不允许直接改代码再比如refactor-executor负责按既定方案执行修改它才拥有 Edit 和 Write 权限。这样审查、规划、执行三个步骤就变成了三个独立角色每个角色的上下文都比一个大而全的“重构助手”要干净得多。多角色协作时我建议还是由主代理统一调度。也就是不让子代理之间互相调用而是让主代理根据任务阶段去选择角色。这么做的好处是流程可控出了问题也容易定位。如果让子代理直接互相调用很容易出现 A 改完 B 又改回去的打架现象或者陷入一层套一层的循环调用Token 消耗蹭蹭上涨。至少在角色工程化的初期把调度权留给主代理是最稳的方案。4. 在真实项目里玩转角色工程化建好第一个 Subagent 后接下来就是如何在真实项目里形成体系。我自己经历过一个阶段觉得所有事都能拆成角色于是疯狂建了一堆 Subagent结果主代理择角色反而开始犯迷糊。痛定思痛后我把角色收敛到几个真正高频、边界清晰的岗位上使用体验才回到正轨。这一节我想分享一些实际组合、权限配置和团队协作经验帮你避免“配置越堆越多效果越来越差”的陷阱。4.1 常用角色组合与分工表我目前比较常用的角色组合大概有这么几类整理成表格方便你对照参考。注意这不是标准答案每个项目的痛点不一样你只需要保留高频且边界清晰的岗位。角色标识核心职责工具权限典型触发场景code-reviewer只读审查代码质量、安全隐患Read, Grep, Glob提交前 review、检查代码问题test-generator分析代码并生成测试用例Read, Grep, Glob, Write为模块补充单元测试commit-message-writer根据 diff 生成符合规范的提交信息Read, Grep, Bash写完代码准备提交时interface-docs梳理接口调用链并生成文档Read, Grep, Glob新同学了解项目、维护 API 文档dependency-auditor分析依赖版本和安全公告Read, Grep, Bash升级依赖前做影响评估分工表里最重要的不是角色名字而是“工具权限”和“触发场景”。比如commit-message-writer其实只需要读取 diff不需要修改文件也不应该拿 Edit 权限test-generator需要写测试文件所以才给它 Write但它不应该误改业务源码。每个角色的工具权限都对应着职责边界这个边界画得越清楚出错的概率越低。4.2 用 Subagents 做复现性更高的日常工作角色工程化带来的最大收益之一是“复现性”。过去你让 AI 写提交信息它这次用 Conventional Commits下次可能就变成一句话描述现在你把这个任务固化到commit-message-writer里它每次都会按同一套格式输出团队里每个人跑出来的结果都长一样。我举个例子。团队约定提交信息格式为类型(范围): 摘要类型限定为 feat、fix、refactor、docs、test 等。那这个角色的正文就可以写明“根据 git diff 识别变更类型输出一行摘要加简要正文如果存在破坏性变更必须在底部标注 BREAKING CHANGE只输出提交信息不要输出执行命令。”这样无论谁在哪个分支上调用产出的格式都是统一的。这种确定性在多人协作时尤其值钱。再比如依赖升级场景。过去靠人肉检查哪些依赖要升级既慢又容易漏。我给dependency-auditor定义了一套流程读取包管理文件、对比可用版本、识别破坏性变更点、输出升级影响清单。每次执行的结果都是一个固定结构的报告项目维护者可以快速做决策而不是重新去翻文档。4.3 权限、模型与团队共享配置进入团队使用阶段有三个问题必须认真对待权限、模型成本、配置管理。权限方面我给每个 Subagent 都设置了最小工具集能只读就不给写权限能不用 Bash 就不用 Bash。这样即使角色被误触发损失也有限。特别是那些会自动分析外部依赖或者运行命令的角色工具权限一定要收紧。模型成本上我一般把高频、低风险的角色固定用成本较低的模型比如简单的提交信息生成和文档梳理涉及复杂代码分析的审查和重构规划才用更强模型。model 字段的价值就体现在这里它能让路由到该角色的任务自动落到合适的模型上不需要每个请求都手动指定长期看能省下一笔不小的费用。团队共享方面最简单的做法是把.claude/agents/目录提交到 Git 仓库。这样所有成员 clone 项目后就能获得同一套角色配置不会出现“我机器上有个审查角色你机器上没有”的割裂。需要注意Agent 文件里千万不要放任何密钥、内部地址或敏感信息因为它会在每个使用者的本地被读取也可能跟着仓库扩散到不该去的地方。5. 常见问题与排查技巧实录用的时间长了你会发现 Subagents 的坑主要集中在路由、上下文、输出质量和循环调用这四类。我把自己踩过的坑和排查思路整理成笔记方便你遇到类似问题时直接对照。5.1 为什么主代理总是“看不见”我的 Subagent这是最常遇到的问题文件建了/agents里也能看到但正常对话时主代理就是不调用它。我排查的第一步是检查 description 是否写得足够“主动”。如果 description 是“负责代码审查”主代理可能认为这件事自己随手就能处理但如果 description 是“当用户要求审查代码或提交前检查时必须使用该角色处理”路由命中概率就会高很多。另外一种情况是候选角色太多。主代理每次要决定是否调用某个 Subagent 时会扫描所有角色的 description如果有一堆角色描述雷同它很难分辨哪个最合适。所以我建议同一类任务最多保留一个主角色不是特别必要的角色直接删掉别让主代理做选择题。如果以上都没问题但还是不自动调用那就直接通过角色名手动指定。手动调用本身也是一种可控的工作方式尤其是那些你明确知道该用什么角色的场景完全没必要依赖自动路由。我在实际工作中代码审查和提交信息生成都是手动触发居多自动路由更多用来处理一些我还没建立起固定流程的临时任务。5.2 上下文失控角色越分越细Token 越烧越快Subagents 虽然能减少主对话里的角色污染但在两种情况下会让 Token 消耗变猛。第一种是角色正文写得太长把项目背景、历史决策、代码规范全部塞进去导致每次调用都要加载一大坨文本。第二种是子代理在分析时读了太多文件把大量无关代码拉进了自己的上下文。解决方案也不复杂。角色正文只保留“岗位必需”的信息项目级背景放在 CLAUDE.md 里让主代理统一管理子代理正文专注于职责、流程和输出格式。如果子代理任务需要项目背景可以在正文中要求它“先读取 CLAUDE.md 或指定文档再开始分析”按需加载。对于读文件太多的问题我会在角色工作流程里加上“优先从关键入口开始读最多读取指定数量的文件避免全量扫描”。5.3 子代理给出的结论“说了等于没说”输出空泛是 Subagent 最让人头疼的问题之一。一个审查角色如果只回复“这段代码存在可维护性问题建议拆分函数”那我基本等于没得到任何有效信息。这类问题的根源通常出在输出规范过于模糊角色不知道你要什么颗粒度的结论。我的解决办法是给输出规范做“硬性限制”。要么要求它用表格输出必须有文件路径、行号、问题级别要么要求它必须引用具体代码片段否则结论无效。还有一个技巧是给一个 few-shot 示例在角色正文末尾放一个简化版的理想输出样例。模型看到样例后会更容易理解你要的格式和深度。这个办法我在很多角色上都用过效果非常直接。5.4 子代理陷入循环或互相打架有些角色会设计成能调用其他子代理比如主代理让规划角色出一个方案规划角色又去调执行角色改代码执行角色发现问题后又调回规划角色最终形成循环。避免这个问题的最好办法是不要让子代理具备调用其他子代理的工具权限所有调度统一由主代理完成。如果发现多个角色在结果上互相冲突比如 A 角色建议删掉某个函数B 角色又建议保留我会检查它们的 description 和输出规范是否对同一类问题给出了不一致的默认偏好。这时候要么合并角色要么在各自的正文里补充一条“遇到职责重叠时只从本角色视角分析并明确指出不确定项”。至少从我的经验看角色边界越清晰冲突越少。6. 一些个人体会Subagents 用到现在我最大的体会是它最值钱的部分不是“省事”而是“稳定”。你不需要每次都在对话里重新描述一遍角色要求只需要把优秀的工作方式固化进一个文件之后每一次调用都有基本线的质量保障。对于经常要做重复性任务的人来说这种确定性带来的效率提升非常明显。如果你打算开始尝试我建议从代码审查这个角色入手因为它最容易验证效果、也最容易调整。花半个小时写完一个文件跑通一次调用再迭代两轮输出规范你会立刻感受到什么是角色工程化。等手感来了再慢慢扩展测试生成、文档梳理、提交信息这些周边角色让 Subagents 真正成为你的虚拟团队。不要一上来就想着建一个复杂的体系先把一个角色用到顺手比什么都重要。
