子代理与协作执行

一个 PR 改了 30 个文件，涉及前端组件、后端 API、数据库迁移。你让 code-review 跑一遍，等了 10 分钟，结果出来了——但你总觉得它对数据库迁移那块看得太粗，因为到后面上下文已经很长了，注意力被前面的组件代码占满。

如果能把文件按职责分组，每组交给一个独立的审查员，各自专注自己那摊事，最后汇总结论呢？

这就是子代理（subagent）要解决的问题。

context: fork 的工作原理

在 SKILL.md 的 frontmatter 中设置 context: fork，Skill 就不再在主对话中执行，而是启动一个独立的子代理。

子代理有自己的上下文窗口，不共享主对话的历史。它只看到两样东西：自己的 prompt（SKILL.md 的内容）和通过 $ARGUMENTS 传入的参数。执行完毕后，结果汇总回主对话。

类比：主 Skill 是项目经理，子代理是团队成员。项目经理不会把所有会议纪要转发给每个成员，只会给一个明确的任务说明。成员干完活，交付物回到项目经理手里。

这意味着两件事：

1. 子代理的上下文更干净，不会被之前的对话污染
2. 你必须在 prompt 中给够信息，因为它看不到之前聊了什么

内置代理类型

Claude Code 提供三种内置代理，能力递增：

选哪个取决于你让子代理干什么。如果只是”看看这几个文件有没有安全问题”，用 Explore 就够了，能力越小越安全。如果需要子代理生成修复补丁，才用通用代理。

自定义代理：agents/ 目录

内置代理太通用？你可以在 Skill 目录下创建 agents/ 文件夹，放自己的代理 prompt。一个 .md 文件就是一个代理。

设计代理 prompt 要想清楚三件事：

职责边界——明确告诉它只做什么、不做什么。模糊的职责会让代理越界，比如分析代理跑去改代码。

输入输出约定——输入通过 $ARGUMENTS 传入，输出按什么格式返回。

错误处理——找不到答案时说”无法确定”，比瞎猜好一万倍。

一个完整的例子，agents/deep-analyzer.md：

你是一个代码问题深度分析师。
 
收到一个代码问题后：
1. 用 Grep 和 Read 追踪问题的根因（不只看当前文件，追踪调用链）
2. 判断问题的影响范围（还有哪些地方有类似问题）
3. 给出根因分析和修复方向
 
输出格式：
- 根因：[一句话]
- 影响范围：[受影响的文件列表]
- 修复方向：[具体建议]
 
只做分析，不做修改。如果无法确定根因，明确说"无法确定"而不是猜测。

注意最后一句。没有它，代理在追踪不到根因时会编造一个看起来合理的分析，你信了就完了。

主 Skill 与子代理的信息传递

数据流只有两个方向：

主 → 子：通过 $ARGUMENTS 传文本，或者通过文件系统。比如主 Skill 先把 PR diff 写到临时文件，子代理去读。

子 → 主：子代理的输出会被汇总后返回给主对话。主 Skill 拿到的是子代理的最终文本输出。

记住：子代理看不到主对话历史。如果你在主对话里和用户讨论了半天某个函数的设计意图，子代理一无所知。必须在传参时把必要的上下文带过去。

实战 1：并行审查

code-review v9，加入子代理并行审查能力。

在 SKILL.md 的审查指令中加入分组逻辑：

## 大 PR 处理策略
 
如果变更文件超过 15 个：
 
1. 按目录将文件分组（如 src/components/、src/api/、migrations/）
2. 每组启动一个 Explore 子代理，只审查该组的文件
3. 每个子代理按标准格式输出审查结果
4. 汇总各组结果，生成最终报告
 
分组原则：同一模块的文件放一组，跨模块的公共文件单独一组。
每组不超过 10 个文件——太多了子代理也顾不过来。

这样一个 30 文件的 PR，分成 3 组并行审查，总耗时大约等于 10 个文件的审查时间，而不是 30 个文件串行跑。更重要的是，每个子代理的上下文只有自己那组的代码，注意力更集中。

实战 2：问题深度分析

审查发现 Critical 问题后，有些问题光看当前文件看不出全貌。这时候启动 deep-analyzer 子代理追踪根因。

在 SKILL.md 中加条件触发：

## 深度分析
 
如果发现了 🔴 Critical 级别的问题，且问题涉及跨文件的逻辑（如数据流、状态管理、权限校验）：
 
启动 deep-analyzer 代理，传入问题描述和相关文件路径。
将深度分析结果附在对应问题下方，标记为"根因分析"。

子代理会沿着调用链往上追，找到真正的源头。比如一个 API 没有鉴权，deep-analyzer 会追到路由注册的地方，发现是中间件配置遗漏，而不只是报”这个接口没有权限检查”。

何时不该用子代理

子代理不是免费的。每个子代理都要消耗独立的上下文窗口和 token。如果任务本身不大（改了 5 个文件），串行处理就够了，别为了用而用。

判断标准：如果你发现一个 Skill 的上下文经常接近满载，或者任务天然可以按模块切分，子代理才值得引入。