上周接了个需求：给一个老项目加国际化支持，涉及 38 个文件、4 种语言。我估了一下，一个人干大概要两天。用 Claude Code 单线程跑，也得四五个小时——因为它得一个文件一个文件地改，改完一个才能看下一个。

然后我试了 SubAgent。

结果：47 分钟搞定。不是我在吹，是任务日志里白纸黑字写着的。

SubAgent 是什么

SubAgent 是 Claude Code 内置的子任务分发机制。简单说就是：主 Agent 可以把一个大任务拆成几个小任务，每个小任务交给一个独立的 SubAgent 去跑，它们之间互不影响，并行执行。

跟你开了几个终端窗口同时干活差不多，只不过每个窗口里都坐着一个 AI。

它不是什么新功能，Claude Code 从 2025 年底就支持了。但大多数人没用过，或者用了觉得效果一般。问题往往出在任务拆分的方式上，而不是 SubAgent 本身。

什么时候该用 SubAgent

不是所有任务都适合拆。我踩过坑，总结了一条判断标准：

任务之间有没有数据依赖？

• 没有依赖 → 拆。比如：翻译多个独立文件、给多个模块写单元测试、批量重构同一模式的代码
• 有依赖 → 别拆。比如：先建数据库表，再写 ORM，再写 API——这种链式任务拆了反而出错

还有一种灰色地带：部分依赖。比如 5 个文件里有 3 个互相引用。这时候把那 3 个放一组、剩下 2 个各自一组，分成 3 个 SubAgent。

实战：用 SubAgent 做国际化

回到开头那个例子。项目结构大概长这样：

src/
  components/
    Header.tsx
    Footer.tsx
    Sidebar.tsx
    ...（共 15 个组件）
  pages/
    Home.tsx
    About.tsx
    Settings.tsx
    ...（共 12 个页面）
  utils/
    format.ts
    validate.ts
    ...（共 11 个工具文件）

要做的事情： 1. 把所有硬编码的中文字符串提取成 i18n key 2. 生成 4 个语言包（中/英/日/韩） 3. 每个组件用 useTranslation hook 替换硬编码文本

第一步：在 CLAUDE.md 里配置 SubAgent 策略

# SubAgent 使用规范

## 并行任务拆分原则
- 按目录或功能模块拆分，每个 SubAgent 负责一个独立区域
- 共享类型定义和工具函数由主 Agent 先处理，再分发子任务
- 每个 SubAgent 完成后输出修改文件清单，主 Agent 做最终检查

## i18n 任务专用规则
- 所有 SubAgent 使用同一份 key 命名规范：{模块}.{组件}.{描述}
- 语言包由独立 SubAgent 生成，不要让改代码的 Agent 同时写语言包

第二步：让主 Agent 做前置工作

在 Claude Code 里输入：

先帮我做 i18n 的前置准备：
1. 安装 react-i18next 和 i18next
2. 创建 src/i18n/config.ts 初始化配置
3. 在 App.tsx 里引入 I18nextProvider
4. 创建空的语言包文件结构 src/i18n/locales/{zh,en,ja,ko}.json

做完这些之后，再分 SubAgent 处理各模块的文本提取。

Claude Code 会先把基础设施搭好，然后自动拆分子任务。

第三步：SubAgent 并行执行

Claude Code 拆出了 4 个 SubAgent：

每个 SubAgent 独立运行，互不阻塞。在终端里你能看到类似这样的日志：

[SubAgent #1] Processing Header.tsx... extracting 12 strings
[SubAgent #2] Processing Home.tsx... extracting 23 strings
[SubAgent #3] Processing Settings.tsx... extracting 18 strings
[SubAgent #4] Processing format.ts... extracting 7 strings

四个同时在跑。

第四步：主 Agent 收尾

SubAgent 全部完成后，主 Agent 自动执行： 1. 合并所有提取出的 key 到语言包 2. 检查有没有重复 key 3. 跑一遍 tsc --noEmit 确认类型没问题 4. 跑一遍 npm test 确认没有破坏现有功能

最后输出汇总：

完成 i18n 改造：
- 修改文件：38 个
- 提取字符串：247 个
- 新增 key：198 个（去重后）
- 语言包：4 个（zh/en/ja/ko，中文已填充，其余待人工翻译）
- 测试：全部通过
- 耗时：47 分钟

手动触发 SubAgent 的方法

除了让 Claude Code 自动拆分，你也可以手动指定：

用 SubAgent 并行处理以下 3 个任务：

任务 1：给 src/api/ 下所有接口函数加上 JSDoc 注释
任务 2：给 src/hooks/ 下所有自定义 hook 写单元测试
任务 3：检查 src/utils/ 下所有函数的错误处理，缺少 try-catch 的补上

关键是描述清楚每个任务的输入范围和预期输出。含糊的指令（"优化一下代码"）会让 SubAgent 不知道干什么。

5 个踩坑提醒

1. 别让 SubAgent 改同一个文件

两个 SubAgent 同时改 index.ts，后写入的会覆盖先写入的。解决办法：按文件分配，而不是按功能分配。

2. 共享配置先搞定

如果多个 SubAgent 都需要用到某个类型定义或配置文件，让主 Agent 先创建好，再分发子任务。不然每个 SubAgent 可能各自创建一份，命名还不一样。

3. SubAgent 数量不是越多越好

我试过把 38 个文件拆成 38 个 SubAgent，一对一。结果反而慢了——调度开销太大。实测下来，3-6 个 SubAgent 是效率和稳定性的平衡点。

4. 在 CLAUDE.md 里写清规范

SubAgent 不会自动读你脑子里的编码规范。你得在 CLAUDE.md 里写清楚命名规则、代码风格、import 顺序等。所有 SubAgent 都会读这份文件。

5. 留意 token 消耗

每个 SubAgent 都是独立的上下文，都会消耗 token。4 个 SubAgent 跑下来，token 消耗大概是单 Agent 的 2.5-3 倍（不是 4 倍，因为省掉了重复的中间等待）。

适合 SubAgent 的场景清单

不适合的场景：有严格执行顺序的任务、需要全局状态的重构（比如改数据库 schema）、文件之间强耦合的改动。

跟 Cursor、Windsurf 对比

Cursor 目前（2026 年 5 月）的 Agent 模式是单线程的，不支持原生 SubAgent 拆分。你可以手动开多个 Composer 窗口并行，但没有自动合并和冲突检测。

Windsurf 有 Cascade 模式，支持多步骤但也是串行执行。

Claude Code 的 SubAgent 目前是终端 AI 编程工具里唯一原生支持并行子任务的。这个差距在小任务上不明显，但任务规模一上来（20+ 文件），时间差距就很大了。

结尾

SubAgent 不是万能药。任务拆得不好，比单 Agent 还慢。但如果你的任务是"对一批独立文件做同一类操作"，那它能省掉大量等待时间。

我现在的习惯是：看到任务涉及超过 10 个文件，先想想能不能拆。能拆就拆，拆不了就老老实实单线程跑。

47 分钟和两天的差距，试一次就回不去了。