用 Subagents 拆分任务

基于官方 Codex Subagents 教程，面向新手讲清什么时候应该并行拆任务、什么时候不该拆，以及如何控制上下文、权限和成本。

Codex subagents 的作用，是把一个复杂任务拆给多个专门 Agent 并行处理，再把结果汇总回主回复。官方说明它特别适合高度并行的任务，比如代码库探索、复杂 PR 审查、多步骤 feature plan。

新手不要把 subagents 理解成“越多越强”。每个 subagent 都会消耗模型和工具资源，也会带来上下文污染、结果冲突和审批复杂度。真正有价值的是“拆得清楚”。

先理解：subagent 解决什么问题

单 Agent 适合线性任务：读上下文、做判断、改文件、验证。

Subagents 适合并行任务：安全审查、测试风险、文档事实核验、代码路径探索、迁移点盘点。这些子问题彼此独立，能同时推进，最后由主 Agent 汇总。

不适合拆的任务也很多。比如一个小 bug、一个单文件改动、一个需要持续同一上下文的调试过程，拆成多个 Agent 只会增加噪音。

怎么判断要不要拆

适合拆：

子任务之间可以独立完成。
每个子任务有清楚边界和交付物。
你需要同时看多个维度，例如安全、正确性、测试、文档。
主 Agent 能根据子结果做最终取舍。
即使某个子任务失败，也不会破坏主任务。

不适合拆：

任务很小，单 Agent 几分钟能做完。
子任务共享同一段易变上下文，拆开后容易互相误解。
你还没有定义清楚每个 Agent 的职责。
任务会产生大量文件改动，多个 Agent 可能互相踩写同一批文件。
你处在 non-interactive flow，无法处理额外审批。

最稳的判断是：能用一句话说清每个 subagent 只负责什么，并且它们不会同时修改同一文件，才适合拆。

内置 agent 怎么用

Codex 官方内置了 default、worker 和 explorer 这类 agent 类型。

explorer 适合只读代码库探索，目标是收集证据、定位路径、回答具体问题。

worker 适合执行明确改动，目标是实现或修复一个边界清楚的任务。

default 是兜底通用 Agent。

新手不要先写 custom agent。先用内置 explorer 做只读探索，再用 worker 做小范围改动。等你发现某类任务反复出现，再定义 custom agent。

权限和审批怎么理解

Subagents 会继承当前 sandbox policy。也就是说，如果主会话给了较大权限，子 Agent 也可能在同一权限边界里工作。

交互式 CLI 里，即使你正在看主 thread，也可能收到 inactive agent thread 的 approval request。审批界面会显示来源 thread，你需要确认这个请求到底来自哪个 Agent。

在 non-interactive flow 或无法显示新审批的环境里，需要新审批的动作会失败，并把错误返回给 parent workflow。

新手建议：subagents 初期全部 read-only。需要写文件时，把写入职责交给一个 worker，不要让多个 Agent 同时改。

Custom agent 什么时候值得写

Custom agent 适合长期重复任务，而不是一次性命名。它至少要有 name、description 和 developer_instructions，也可以设置模型、reasoning effort、sandbox、MCP 和 skills。

好的 custom agent 应该范围窄、立场清楚、工具面小。例如“只读 PR reviewer”“文档事实核验员”“迁移风险盘点员”。

不要写“万能高级工程师 Agent”。这类描述会让职责边界变模糊，最后和主 Agent 抢工作。

新手常见坑

为了并行而并行：任务不独立时，subagents 只会制造重复判断。
没有写清交付物：子 Agent 返回一堆自然语言，主 Agent 很难汇总。
多个 worker 改同一文件：最终 merge 冲突和行为冲突都难排查。
忘记 token 成本：每个 subagent 都会单独读上下文、调用工具、生成结果。
在 CI 里使用需要审批的子任务：审批无法展示时会失败。
自定义 Agent 太宽泛：description 不清楚，Codex 就不知道什么时候该 spawn。
让子 Agent 继续 spawn 子 Agent：递归 fan-out 容易失控，除非你非常清楚 max depth。

一个稳妥的 PR 审查拆法

先让 explorer 只读映射受影响代码路径。

再让 reviewer 只读找正确性、安全和测试风险。

如果改动依赖某个框架 API，再让 docs researcher 查官方文档。

最后由主 Agent 汇总 findings，按严重程度排序。需要改代码时，只派一个 worker 做最小修复，再统一验证。

这种拆法的重点是：探索、审查、事实核验、执行分开。

怎么验收

你能说清每个 subagent 的职责、输入和输出。

你能确认哪些 Agent 只读，哪个 Agent 可以写文件。

你能看到每个子结果如何进入主回复，而不是只得到一段混合总结。

你能在任务结束后关闭或清理已完成的 agent threads。

你能证明并行带来了更快或更全面的结果，而不是只增加 token 和噪音。