官方文档写了 subagent 什么时候别用,我把这四条和两个硬上限一起拆了

↑↑↑ 点击关注，了解AI干货！！！

subagent 现在被讲成了万能药：活多就开几个并行，上下文紧张就丢给它。

我这两天把官方 sub-agents 和 best-practices 两页逐条读完，发现文档里真正花力气写的，是反过来那一面——什么时候别开。

先说官方给的那条主线理由，它其实只有一条：

Since context is your fundamental constraint, use subagents to keep research out of it.

上下文是根本约束，所以拿 subagent 把调研挡在外面。同一页的「常见失败模式」里有条对应的：

The infinite exploration.

 You ask Claude to "investigate" something without scoping it. Claude reads hundreds of files, filling the context.

修法就是缩小范围，或者用 subagent。

注意这条理由的形状：它的收益来自「那些内容你不会再看第二眼」。 一旦你后面还要用，收益立刻变成损失。

这就引出了官方那四条「别用」。逐字抄过来：

• "The task needs frequent back-and-forth or iterative refinement"
• "Multiple phases share significant context, such as planning, implementation, and testing"
• "You're making a quick, targeted change"
• "Latency matters. A subagent that isn't a fork starts fresh and may need time to gather context"

第二条我觉得最容易踩。规划、实现、测试这三段共享大量上下文，很多人恰恰爱把它们拆成三个 subagent 跑——看着很工程化，实际上每一段都得重新把情况讲一遍，讲漏了就跑偏。

为什么会漏，得看隔离机制是怎么实现的。非 fork 的 subagent 看不到主会话历史。 它启动时手里只有：自己的 system prompt、Claude 写给它的那条委派消息、CLAUDE.md、某些情况下的 git status，以及 skills: 字段预加载的 skill。

所以委派消息的质量决定一切。 Claude 得在那一条消息里把情况重述一遍。你觉得"它应该知道吧"的那些事，它不知道。

干完活回传的也只有最终 summary，不是过程，而且是先回给 Claude，再由 Claude 决定怎么呈现给你。权限则从父会话继承。

官方还给了两个替代品，很多人不知道有这俩：

/btw 那个挺好用——它看得到全部上下文，但没有工具，答案也不进历史。查一句就走，不占地方。

再说两个硬上限，我搜了一圈没见人写过。

嵌套深度三层。 官方逐字：

a subagent can spawn subagents of its own, up to three layers below the main conversation. At the depth limit, Claude Code withholds the Agent tool from every subagent except a fork.

到底了就直接把 Agent 工具从它手里收走，不是报错，是没这个工具。还有一句更该注意：

Only the top-level subagent's summary returns to you.

只有最上层那个的 summary 会回到你这。 你在第三层挖出来的东西，得靠中间那层如实带回来。层数越深，信息损耗越大。

并发 20 个。 第 21 个用 Agent 工具起会失败，报 Concurrent subagent limit reached，而且错误信息里会直接告诉 Claude 别重试。两个上限分别有环境变量可调：CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 和 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS（后者要 v2.1.217+）。

配置层面有两个坑值得单独点名，都是写错了不报错那种。

一是 name 字段不能含冒号。冒号是插件标识符的保留字，含冒号的 agent 文件从 v2.1.218 起不加载。

二是 disallowedTools 写 specifier 没用。你以为写 Bash(git push *) 是禁掉这一条命令，实际上整个 Bash 工具都会被移除。想做精细控制得走别的路。

还有一条来自最佳实践页的，我觉得是全文最有意思的一句。官方建议收尾前让 subagent 在干净上下文里复核 diff，但紧跟着一句警告：

A reviewer prompted to find gaps will usually report some, even when the work is sound, because that is what it was asked to do. Chasing every finding leads to over-engineering.

你让它挑毛病，它就一定挑得出毛病来。 所以复核类 subagent 的 prompt 里必须写死一句「允许回答无阻塞项」，否则你会被自己造出来的问题牵着走，一路过度工程。

我把这四条「别用」、决策树、三层/20 并发的原文出处、frontmatter 全字段表（含 skills / memory / isolation 这些少见的），连同三份可直接抄的配置模板——省 context 的只读调研员、明确授权说「无问题」的对抗式复核员、官方给的显式调用句式——整理成了一份模板集。需要的话加我微信 bill_f001，备注「决策树」，我发你。不发广告，就是想认识真会去抠这些默认值的人。

一句话总结我读完的判断：subagent 不是并行工具，是遗忘工具。 它的全部价值在于把你不打算再看的东西挡在上下文外面。

所以开之前只问一句：这堆东西，我后面还要不要看？

要看——留在主会话。不看——丢出去。

顺带一个我没查到的：官方没说 fork 型 subagent 是否也算在那 20 个并发里。文档两处都只写 "subagents"，没区分。谁实测过的话评论区说一声。

上面那份决策树加三个配置模板，加我微信 bill_f001 备注「决策树」就能拿到。

本号每周实测 Claude Code 和新出的 AI 工具，关注我，别错过下一次把官方文档拆给你看。

⭐ 点赞、转发、在看三连，星标不错过⭐

15 年 Top 外企 IT，专做 AI 落地，边踩坑边记录。同路人，欢迎来。