Claude Code Subagents 新手指南：什么时候该派小助手

预计阅读 15 分钟。目标不是让你马上搭一套多 Agent 系统，而是先听懂：Subagent 到底适合接什么活，什么时候会帮忙，什么时候反而添乱。

这篇会给你一份能直接抄的最小配置，再把判断感讲透：这件事该不该派出去，派给谁，怎么知道它做完了。

先抄一份：最小可用的 article-reviewer

不想先读理论，只想照着配一个出来？把下面这个文件存到项目的 .claude/agents/article-reviewer.md，一个只读复检助手就成型了。Subagent 本质就是一个带 YAML 头部（frontmatter）的 Markdown 文件——头部声明配置，正文写它的工作守则：

---
name: article-reviewer
description: 当用户要求复检 Markdown 文章时使用。只检查重复段落、标题是否兑现、代码比例是否过高、语气是否像机器翻译；不修改文件，只返回问题清单和建议。
tools: Read, Grep, Glob
model: haiku
---

你是文章复检助手，你的任务是找问题，不是重写文章。

工作时：
1. 先确认用户指定的文章路径，只读取必要文件。
2. 按严重程度从高到低列出问题。
3. 每条问题说明位置、原因和建议改法。
4. 不发布、不改文件、不创建新文件。

存好后在 Claude Code 里输入 请用 article-reviewer 复检这篇文章 {路径}，只返回前 10 个最值得改的问题，它就会在自己的上下文里读文章、列清单、交回结论，全程不碰你的文件。

这份配置里真正决定它行不行的只有三件事，下文会逐一展开：

• description：写清「什么时候用它」，Claude Code 靠它判断要不要派这个助手（不是靠名字）。
• tools：白名单，只给 Read, Grep, Glob 三样读类工具——省略这一行会让它继承主会话的全部工具，对只读助手是多余的风险。
• model：这里写 haiku 让它更省更快；不写则默认 inherit，沿用主会话的模型。

官方文档说 frontmatter 里只有 name 和 description 是必填项，其余（tools、model、disallowedTools 等）都可省略。具体字段以官方当前文档为准。

下面从「该不该派」讲起，再一节节把这三件事讲透，还会给你两个能直接抄的进阶配置。

30 秒答疑：Subagent 该不该派，先对号入座

先用一句话回答最多人搜进来想问的问题：Claude Code Subagents 是主会话派出去的小助手，适合接「明确、能一句话说清完成标准、又会产生一堆你不想看的中间材料」的任务——比如代码审查、跑测试只报失败、读一堆文件只回结论。任务模糊、需要反复沟通、完成标准说不清，就别派，先在主会话把目标谈清楚。

下面这张表帮你快速对号入座，找到你这种情况该怎么做：

要点速览

• Subagent 的本质是「上下文隔离」：让一件明确小事在单独上下文里完成，不把主会话越搅越乱。
• 新手第一个 subagent 建议做「只读复检助手」——风险低、边界清、输出好验收。
• 决定它行不行的不是名字，是 description（什么时候用它）和工具权限（只给任务需要的那几个）。
• 最常见的新手错误：让审查类助手继承全部工具，结果一个本该「只读」的助手把文件改了。

一、先讲清楚：Subagent 是被派出去的小助手

你可以把 Claude Code Subagents 理解成「被派出去的小助手」。主会话像你本人，负责看全局、决定方向、收口结果。Subagent 像一个专门处理某类任务的同事，接到一件明确的小活，自己去看资料、做判断，最后把结果带回来。

💡 通俗讲：Subagent 不是「另一个更聪明的 AI」，而是「你临时雇来干一件具体小事的人」。它和你不在同一张办公桌上工作，活干完只把结论递回来。把这一点记住，后面所有判断都会变简单。

这和普通聊天不一样。普通聊天里，所有事情都挤在同一个上下文里。聊着聊着，前面的背景、临时想法、工具输出都混在一起。Subagent 的价值，是让某些任务在单独的上下文里处理，不把主会话越搅越乱。

所以你先别把它想得太神。它不是「很多 AI 一起变聪明」，而是「把一件明确小事交给一个更合适的临时助手」。这个理解够用，而且更不容易走偏。

我会把它当成一次很短的交接。你不可能对同事说「你去把项目弄好」，然后期待他马上交出正确结果。你会说清楚：看哪几个文件、只检查什么、不要修改、最后给我三条结论。Subagent 也是这样，交接越清楚，它越像助手；交接越含糊，它越像另一个会猜的人。

二、它真正解决的是上下文污染

新手第一次用 Claude Code 做长任务，最常见的感觉是：前面还很清楚，越到后面越乱。它看过很多文件，跑过很多命令，讨论过几个方向，最后你自己都忘了哪段信息还重要。

Subagent 能缓解这个问题。比如你正在做功能开发，主会话只负责改代码和收口；代码审查这件事可以交给一个 reviewer subagent。它在自己的上下文里看变更、列风险、给建议，回来只交付结论。主会话不用塞满所有审查细节。

用一句通俗的话概括「上下文隔离」：不要让每件小事都把主桌面弄乱。能单独处理的，就放到单独桌面处理。

这种隔离对长任务很有用。比如你正在改一个功能，主会话里已经有需求、实现、测试、你的临时判断。如果这时又让它做一次完整代码审查，审查材料会把主会话塞得更满。交给 subagent 后，主会话只拿审查结论，桌面会干净很多。

官方文档里也把这一点讲得很清楚：Subagent 适合处理会产生大量搜索结果、日志、文件内容的旁路任务。它在自己的上下文里工作，最后把摘要交回主会话。对新手来说，这句话比「多 Agent 协作」更重要。

你可以先认识 Claude Code 自带的几类 subagent。Explore 偏只读探索，适合查文件、看代码结构、找线索；Plan 会在计划模式里帮主会话收集上下文；general-purpose 能处理更复杂的多步任务。你不一定要手动调用它们，但知道这些角色存在，能帮你理解为什么主会话有时会把一部分工作派出去。

这几个内置助手的设计也透露了一个思路：按任务挑成本。官方给 Explore 配的是更快更省的 Haiku 模型，而且只给只读工具，因为它的活就是「快速翻一遍代码库、找到线索」，既不需要慢模型，也不需要写权限。general-purpose 则继承主会话的模型和全部工具，因为它要处理既探索又改动的复杂任务。你自己写 subagent 时也可以照这个思路：简单的审查、查找类任务用便宜模型加只读工具，复杂任务再上更强的配置。

这里有个很实用的判断：只要某个任务会产生大量中间材料，但最终你只需要结论，就适合考虑 subagent。比如「读 30 个文件后告诉我配置入口在哪里」，中间材料很多，主会话不一定需要全部记住；「把这段代码改成另一个变量名」，很小，就没必要派。

🔥 翔宇判断：很多人衡量 subagent 的标准是「它聪不聪明」，我的标准只有一个——它能不能把一堆我不想看的中间材料挡在主会话外面，只把结论递回来。我认为「过程很吵、结论很短」的任务派出去比留在主会话好，因为这类任务最伤的不是算力而是上下文：读三十个文件、翻几百行日志、跑一整套测试，过程材料如果全留在主会话，几轮下来上下文就被它们占满，主会话连最初的目标都开始记不清。反过来，几句话就能改完的活留在主会话，派出去只是多一道交接成本。判断 subagent 该不该用，先看它隔离的是不是噪音，而不是看它有多强。

三、不是所有任务都该派出去

Subagent 适合明确、可交付、边界清楚的任务。不适合模糊、需要你一直调整方向、结果很难验收的任务。

适合派出去的例子：检查一组代码变更有没有明显风险；整理某个目录里的重复文件；查一篇文章有没有重复段落；跑测试并总结第一个真实失败；把一批日志归纳成三类问题。

不适合派出去的例子：帮我把项目整体做得更好；你看着优化一下；把所有问题都修了；顺便规划未来三个月。这类任务太大，派出去以后你很难判断它有没有越界。

如果你不知道该不该派，先问一句：这个任务能不能用一句话定义完成标准？能，就可以考虑；不能，先别派。

💡 通俗讲：判断一个任务该不该派，有个很简单的尺子——你能不能把「做完了」三个字说清楚。「检查这篇文章有没有重复段落，列出行号」有明确的完成标准，做没做完一看便知；「帮我看看这篇文章怎么样」没有完成标准，它审到哪算到哪。前者适合派，后者先在主会话把要求谈清楚再说。

比如「检查这篇文章是否有重复段落，并列出行号」是好任务；「帮我看看这篇文章怎么样」就太散。前者有边界，有输出，有验收；后者会让 subagent 自己决定审什么、怎么看、写多少。新手阶段，越明确越好。

四、项目级和用户级怎么选

Claude Code 的 subagent 可以放两个地方。项目级放在当前项目的 .claude/agents/，只服务这个项目；用户级放在 ~/.claude/agents/，可以跨项目使用。

新手优先用项目级。原因很简单：多数 subagent 都和项目有关。一个内容库的文章复检助手、一个源码项目的测试助手、一个网站项目的 SEO 检查助手，都带着项目上下文。放项目级，更容易和团队共享，也更不容易污染其他项目。

用户级适合非常稳定的个人助手，比如「帮我总结终端输出」「帮我做代码审查草稿」这种跨项目都差不多的任务。还没验证稳定之前，不要急着放到全局。

还有一个细节：项目级 subagent 更适合写进版本管理。团队里每个人拿到项目，都能看到同一批助手。用户级更像你自己的私人习惯，不适合承载团队规则。把这两层分清，后面维护会轻很多。

官方路径可以记成两句。

项目级放在 .claude/agents/，适合当前项目专用。比如这个仓库需要一个文章复检助手、一个 SEO 检查助手、一个发布前清单助手，它们都应该跟项目走。

用户级放在 ~/.claude/agents/，适合你自己跨项目复用。比如你个人一直用的「终端输出归纳助手」，不一定要让每个项目都带着它。

Claude Code 也提供 /agents 入口来创建和管理 subagent。新手不一定要手写文件，先从 /agents 里生成一个只读助手，再回头看它生成的 Markdown 文件，学习成本会低很多。

五、名字不重要，描述才重要

很多人会花时间给 subagent 起一个很酷的名字。名字当然要清楚，但真正影响调用的是描述。Claude Code 会根据任务内容和 subagent 的描述判断要不要派它出场。

描述应该写「什么时候用它」，不要只写「它是什么」。比如「用于检查文章是否有重复段落、AI 腔、过多代码，并给出修改建议」，就比「内容审查专家」更好。前者告诉 Claude 触发场景，后者只是头衔。

写描述时尽量具体。它负责什么，不负责什么，输出什么格式，遇到不确定要不要停下来说明。描述越具体，Subagent 越不像一个泛泛助手，越像一个可复用的小岗位。

我会在描述里加两类话。第一类是触发条件：什么时候应该主动用它。第二类是禁区：它不应该做什么。比如文章复检助手可以写「只审查，不重写，不发布」。这句话很普通，但能避免很多越界。

如果你希望 Claude Code 在合适场景主动派它，而不用每次手动提醒，可以在描述里写上「主动使用」这类引导词。官方文档也提到，在 description 里加上类似「use proactively」的措辞，能让 Claude 更倾向于在匹配场景下自动调用这个 subagent。不过这一步建议等它稳定之后再用，理由在第七节会展开。

🔥 翔宇判断：description 不是给人看的标签，是给 Claude Code 看的「调度规则」。它判断要不要派一个 subagent，靠的就是任务内容和这段描述匹不匹配。所以把力气花在描述上，远比花在起名字上值。一个描述清楚的 article-reviewer，比一个名字很酷但描述含糊的助手好用得多。

六、工具权限越少越稳

Subagent 可以配置自己能用哪些工具。新手最容易犯的错，是让它继承所有工具。看起来省事，实际风险更高。一个只负责审查文章的助手，不需要发布权限；一个只负责查资料的助手，不需要改文件权限；一个只负责跑测试的助手，不需要访问账号后台。

工具越少，行为越好预测。你知道它最多能做什么，也更容易排查问题。它不能做的动作，就会回到主会话让你决定。

这不是削弱能力，而是让能力有边界。真正成熟的自动化，不是把所有门都打开，而是只打开这件任务需要的门。

如果你不确定该给哪些工具，就先少给。它需要更多能力时，会在结果里暴露出来：比如「我无法读取测试文件」「我不能运行测试」。这时再补，比一开始全开更稳。权限是可以逐步加的，事故很难撤回。

⚠️ 常见踩坑：新手最容易踩的一个坑，是图省事让审查类助手继承全部工具。结果一个本该「只读不写」的复检助手，因为带了写权限，在某次任务里直接改了文件。把工具收窄到任务真正需要的那几个（审查类常见的是 Read、Grep、Glob），从一开始就堵住这种意外。

七、自动派发和点名派发

Subagent 有两种使用方式。一种是自动派发：Claude Code 看到任务和描述匹配，就自己派给合适的 subagent。另一种是你点名：比如「让 code-reviewer 检查最近改动」。

新手先用点名派发。因为你能更清楚地观察它接了什么任务、怎么返回结果。等你确认某个 subagent 很稳定，再让它自动出现。

自动派发适合高频、边界明确、你不想每次手动提醒的任务。比如每次完成代码修改后自动找 reviewer 检查，或者每次内容重写后找 proofreader 看重复和语气。没稳定前，不要急着自动化。

点名使用还有一个好处：你能训练自己的判断。每次你手动说「让某某 subagent 看一下」，你就在学习什么任务适合派出去。等这种判断稳定了，再让 Claude Code 自动派发，才不会失控。

官方文档里还提到几种显式调用方式：你可以用自然语言点名，也可以通过界面里的 @ 提及某个 agent，还可以用 --agent 让整个会话以某个 agent 的身份运行。新手先记第一种就够了：自然语言点名。比如「请用 article-reviewer 检查这篇文章，只返回问题清单」。这句话既说明用谁，也说明返回什么。

@ 提及更适合你已经有一批稳定 agent 时使用。它能更明确地指定这次任务由哪个助手处理，但它不会自动替你写好任务边界。你仍然要交代文件路径、检查范围、不要做什么。

--agent 属于更强的用法，适合把整个会话切到某个 agent 的工作方式。新手不要先用它。因为这时不是「派一个小助手做一件事」，而是「让主会话自己变成那个助手」。没有稳定配置前，这个切换反而会让你更难判断问题出在哪里。

八、第一个 Subagent 应该做什么

第一个 subagent 不要做「万能助手」。我的建议是从审查类开始，因为审查通常风险低、边界清楚、输出容易验收。

比如你可以做一个「文章复检助手」。它只读文章，不改文章；只输出问题清单，不直接重写；只看重复段落、过多术语、代码比例、标题兑现度。这样即使它判断错，也不会破坏文件。

等你对它的判断有信任，再让它做更重的任务。新手要先建立「派出去也不会坏事」的经验，而不是第一天就让它自动改项目。

这个顺序很关键。很多人觉得 subagent 没发挥，是因为第一步任务太大。你让一个还没验证过的小助手改一堆文件，它当然让人不放心。先让它只观察、只总结、只提建议，慢慢增加责任，体验会稳定很多。

九、上下文隔离也有成本

Subagent 有自己的上下文，这是优点，也是成本。它一开始不一定知道主会话里所有细节，需要重新读取材料。任务太小的时候，派出去反而慢。任务太依赖上下文的时候，它可能漏掉主会话里你刚说过的细节。

所以派任务时要给它足够清楚的输入。不要只说「你去看看」。要说看哪个文件、检查什么、不要做什么、返回什么。你交接得越清楚，它越像一个好同事；你交接得越含糊，它就只能猜。

这点和真实团队一样。派活不是把麻烦扔出去，而是把任务切成别人能接住的形状。

如果你发现 subagent 回来的结果总是泛泛而谈，先别急着骂它。检查一下你给它的输入是不是也很泛。它知道你要看哪份文件吗？知道只输出问题还是要给方案吗？知道哪些动作不能做吗？这些都没说，结果泛是正常的。

还有一个新手容易忽略的边界：subagent 不能再派出自己的 subagent。也就是说，你不能指望一个小助手在里面又开一层小助手帮它干活。如果一件事确实需要多层分工，正确的做法是回到主会话，由主会话依次调度多个 subagent，而不是让某个 subagent 自己往下嵌套。理解这条，能帮你避免设计出跑不起来的「套娃」流程。

很多人觉得 subagent 不好用，根子不在模型，而在交接。同一个助手，给一句「你看看这个项目」，和给一份「看这三个文件、只检查这两类问题、不要改动、返回问题清单」，产出质量天差地别。把派活当成写一份清楚的工作交接单，而不是甩一个含糊的任务，这是新手阶段最该练的能力。

十、团队里怎么用

团队里用 subagents，最重要的是共享项目级配置。大家在同一个项目里看到同一批助手，才不会各用各的规则。

但共享之前先跑小范围。一个 subagent 至少经过几次真实任务验证，再放进项目。否则团队每个人都会被一个半成品助手影响。尤其是带写权限、发布权限、外部系统权限的助手，更要谨慎。

团队里最适合先落地的，反而是那些「不做事，只看问题」的助手。比如安全审查、文章复检、命名规范检查、变更摘要。这些助手能提高质量，又不容易直接造成损失。等团队习惯了，再考虑让某些助手参与执行。

我更推荐把团队 subagent 分成两类：低风险审查助手，可以早一点共享；高风险执行助手，必须经过明确验收。不要因为它叫「助手」，就忘了它可能真的会动项目。

十一、出问题时先看哪里

Subagent 没按预期工作，先看四处。

第一，看描述是不是太泛。它不知道什么时候该出场，就会不出场或乱出场。第二，看任务是不是太大。你让它做一堆事，它就很难收口。第三，看工具权限是不是过宽或过窄。过宽有风险，过窄做不了事。第四，看输入材料够不够。它没看到关键文件，当然只能猜。

不要一上来怪模型。Subagent 的问题很多时候是岗位设计问题。岗位说清楚、权限收窄、交付标准明确，表现通常会稳定很多。

你可以把每次失败记录成一句话：是描述没写清，还是权限给错，还是任务太大，还是材料没给够。记录几次以后，你会发现问题很集中。Subagent 不是一次写完就不管，它也需要像岗位说明一样迭代。

十二、把第一个助手调教稳：3 次真实任务再下结论

文章开头那份 article-reviewer 配置，就是我建议新手起步的第一个 subagent：只读文件、检查问题、返回清单、不直接修改。这一节讲的是配好之后，怎么把它从「能跑」调到「能信」。

调用它的时候，不要说「帮我优化这篇文章」，要说得更像一次交接：请用 article-reviewer 复检某个完整 Markdown 文件；只检查重复段落、AI 腔、代码比例和标题兑现度；不要修改文件；返回前 10 个最值得改的问题。这句话已经告诉它：看哪个文件、查什么、不做什么、输出多少。Subagent 的表现，很多时候就差在这几句话。

调教它有三条固定动作：如果它返回的结果太泛，就把检查项写得更具体；如果它漏了明显问题，就在 subagent 文件正文里补一条规则；如果它总想修改文件，就把「只读、不改文件」同时写进 description 和正文两处。不要指望第一次写完就稳定，subagent 也需要用真实任务调教。

决定一个助手留不留，我通常拿它做了 3 次真实任务再下结论，不靠第一次的印象。第一次给一篇短文，看它能不能按要求只列问题。第二次给一篇代码很多的教程，看它会不会把必要代码也误判成「代码过多」。第三次给一篇已经改好的文章，看它会不会为了显得有用而硬找问题。三次以后，你大概就知道它是稳定助手，还是只会泛泛挑毛病。

不少人在这一步踩过坑：第一次写完 description 就以为定稿了，急着把助手放进项目让全队用，结果它在别人手里频繁误判，反而被当成「不好用」弃用。先以为「写一次就稳」，实际跑几轮才发现 description 和检查项都要按真实反例改好几遍——这是 subagent 和写一段提示词最大的不同，它更像一个要持续调教的岗位，而不是一次成型的脚本。

稳定以后再考虑把它放进项目级配置，并写进团队说明。没稳定之前，它只是你的个人实验，不要让整个项目依赖它。

这就是我建议从只读助手开始的原因：它能暴露交接质量，又不会直接破坏文件。你先学会怎么派活，再学会让它动手。

十三、跑顺之后：还能再加几样东西

把第一个只读助手用顺、也试着派过几次别的任务之后，你会自然想知道：subagent 还能怎么收紧、怎么变省、怎么记住经验。这一节给你几个方向，新手不用一上来就配，但知道它们存在，能帮你判断什么时候该往深里走。

先回答一句：这些进阶能力解决的都是同一类问题——让助手更可控、更省、更专，而不是让它「更万能」。方向对了再配，才不会越加越乱。

第一个方向是用黑名单代替白名单收权限。前面那份 article-reviewer 用的是 tools 白名单，只给几样工具。反过来，如果你想让助手「几乎什么都能用，就是不能写文件」，用 disallowedTools 黑名单更省事——它继承主会话全部工具，只挡掉你点名的那几样。比如一个能跑命令、能查资料、但绝不许动文件的调研助手：

---
name: safe-researcher
description: 跑命令查资料的调研助手，能用除写文件外的全部工具。需要搜集信息、跑只读命令、汇总结论时使用。
disallowedTools: Write, Edit
---

你是调研助手。可以读文件、搜索、跑只读命令，但不要写或改任何文件，只返回结论。

白名单（tools）适合「只读助手」——你清楚它只该用哪几样；黑名单（disallowedTools）适合「能干活但要堵住某个危险动作」的助手——你说不全它要用什么，但很清楚它绝不能做什么。官方文档也提到，两者可以同时写，此时先按黑名单剔除、再用白名单筛选，同时出现在两边的工具会被移除。

第二个方向是给反复用的助手加一段记忆。默认每个 subagent 都是干净起步，不记得上次干过什么。如果你有个代码审查助手天天用，可以给它配 memory，让它把「这个项目常踩的坑、命名习惯」攒下来，下次审查更准。新手阶段不用急着开，等某个助手真的高频复用了再说。

第三个方向是给专项助手预装领域知识。如果一个助手总要先读同一份规范才能干活，可以用 skills 字段在它启动时直接把这份知识灌进去，省得它每次现查。

这三样我都不建议第一天就上。顺序应该是：先把「只读复检助手」用稳，再根据真实卡点决定加哪一样——发现总要堵某个动作，就上黑名单；发现某助手天天用且老忘事，就开记忆；发现它总要先补一段背景，就预装知识。能力是顺着痛点长出来的，不是一次性堆上去的。

十四、下一步怎么学

你现在只要带走三句话。

第一，Subagent 是小助手，不是多 Agent 魔法。它适合接明确、可验收的小任务。

第二，先项目级，先低风险，先点名使用。别一开始就全局、自动、高权限。

第三，描述比名字重要，边界比能力重要。一个职责清楚的小助手，比一个什么都能做的助手更可靠。

如果你继续学，可以先看 Claude Code Hooks 指南，再看 Claude Code MCP 工具配置 和 Claude Code 权限指南。Subagents 负责分工，Hooks 负责检查点，权限负责能做什么，三者一起看更完整。

外部参考：

• Claude Code 官方 Subagents 文档 —— 查 /agents、项目级与用户级路径、frontmatter 字段和工具权限。