2026/5/1大约 6 分钟
CX-08 Subagents 完整指南：App 中的多 Agent 协作
主要来源：OpenAI Codex Subagents、App Features、CLI Slash Commands 官方文档。
📚 本课学习目标
完成本课学习后，你将能够：
- 判断何时需要Subagents：任务可拆成独立子任务、多文件互不重叠时才用
- 设计安全的分工方案：写清总目标、子任务边界、文件所有权、是否允许写
- 掌握文件所有权规则：并行写代码时明确每个Agent负责的文件范围
- 组合Worktree和Subagents：用Worktree隔离工作区 + Subagents分工并行
- 正确合并Subagents输出：看证据、看冲突、看所有权、主线程整合
- 避免常见失败模式：多个agent改同一文件、主线程不知道进展、子任务太大
- 理解Subagents与Skills的配合：Subagent执行角色，Skill提供工作流方法
- 建立Review纪律：并行改动合并前统一Review，不直接相信总结
🗺️ 学习路径导航（先看这里！）
💡 根据你的情况选择学习路径：不用全看！
路径A：快速上手（⏱️ 15分钟）
适合人群：想快速知道什么时候该用Subagents
只看这些章节：
✅ 第1部分：Subagents解决什么问题（3分钟）
✅ 第2部分：App中什么时候用（5分钟）
✅ 第4部分：推荐分工模板（7分钟）路径B：完整学习（⏱️ 2-3小时）
适合人群：想系统掌握多Agent协作
学习顺序：从头到尾所有章节
1. Subagents 解决什么问题
Subagents 适合把一个任务拆成多个相对独立的子任务：
- 并行读不同模块。
- 一个实现、一个审查。
- 一个查官方文档、一个查代码。
- 前端、后端、测试分开推进。
它不是扩大单个上下文窗口，也不是让任务自动变聪明。它的价值是并行和分工。
2. App 中什么时候用
适合用：
这个重构涉及前端、API 和测试。请先制定分工计划，再并行处理互不重叠的部分。不适合用：
修一个拼写错误。判断标准：
| 条件 | 是否适合 |
|---|---|
| 任务可拆成独立子任务 | 适合 |
| 多个文件/模块互不重叠 | 适合 |
| 需要独立审查 | 适合 |
| 下一步必须等一个结果 | 先主线程做 |
| 单文件小改 | 不适合 |
3. App 中启动前要写清的内容
让 App 调 subagents 前，提示词至少要包含：
| 内容 | 示例 |
|---|---|
| 总目标 | “把认证模块迁移到新 SDK” |
| 子任务边界 | “前端只读 src/pages/login.tsx，后端只读 src/api/auth/*” |
| 文件所有权 | “Agent A 只改 docs，Agent B 只改 tests” |
| 是否允许写 | “先只读分析，不改文件” |
| 汇总方式 | “每个 agent 输出结论、证据、风险和建议动作” |
| 停止条件 | “遇到权限/测试/依赖问题先汇报，不自行扩大范围” |
不写这些，subagent 很容易变成多个不受控的普通对话。
4. 推荐分工模板
先给出 subagent 分工计划，不要立刻改文件。
目标：重构认证模块。
范围：src/auth、tests/auth。
约束：不要改数据库迁移，不要引入新依赖。
分工：
- Agent A：阅读现有 auth 代码，列出风险。
- Agent B：核对官方 SDK 文档。
- Agent C：审查测试覆盖缺口。
汇总后再决定是否执行。5. 文件所有权
并行写代码时必须明确文件所有权：
| Agent | 负责范围 |
|---|---|
| Frontend agent | src/pages/login.tsx、src/components/auth/* |
| Backend agent | src/api/auth/* |
| Test agent | tests/auth/* |
| Review agent | 只读 diff，不改文件 |
没有文件边界的并行开发很容易互相覆盖。
6. Subagents 与 worktree
| 能力 | 作用 |
|---|---|
| Subagent | 分工和并行思考 / 执行 |
| Worktree | 隔离 Git 工作区 |
| Review | 合并前看 diff |
大任务建议组合：
Worktree thread + Subagents + Review这样既能分工，又能降低污染主工作区的风险。
7. Subagents 与 Skills
Subagent 可以执行一个明确角色，Skill 提供工作流方法。
例子：
让一个只读 subagent 使用 $tutorial-verifier skill 核对这篇教程的官方来源。注意：不要假设所有 subagent 都自动拥有所有工具或插件。以当前 App 暴露能力为准。
8. Review 与合并规则
Subagents 返回后，主线程不要直接相信总结。按这个顺序合并：
- 看每个 subagent 的输出是否有证据。
- 看是否有互相冲突的结论。
- 看文件所有权是否被遵守。
- 由主线程整合方案。
- 执行或合并后用 App Review 看 diff。
- 运行验证命令。
如果两个 agent 给出相反建议，不要让其中一个继续硬改；先让主线程整理冲突点，再决定下一步。
9. 常见失败模式
| 失败模式 | 原因 | 修正 |
|---|---|---|
| 多个 agent 改同一文件 | 所有权不清 | 明确文件范围 |
| 主线程不知道进展 | 没有汇总点 | 要求阶段性汇报 |
| 子任务太大 | 拆分不够 | 缩小到模块级 |
| agent 自己发散 | 缺少目标和验收 | 写清停止条件 |
| 没有 Review | 并行改动难合并 | 合并前统一 review |
常见问题
Q1：Subagents 会自动更正确吗？
不会。它们只是并行执行单元。正确性来自清晰分工、约束和 Review。
Q2：什么时候不用 Subagents？
单文件小改、一步任务、目标不清楚的任务，都不应该先拉 subagents。
Q3：Subagents 能和 Automation 一起用吗？
可以，但自动化任务更要限制权限和范围。
📝 总结与检查清单
完成本课后，请确认以下所有项：
如果以上全部勾选，恭喜你掌握Codex Subagents！
附录
A. Subagents使用判断
| 条件 | 适合？ |
|---|---|
| 任务可拆成独立子任务 | ✅ |
| 多个文件/模块互不重叠 | ✅ |
| 需要独立审查 | ✅ |
| 下一步必须等一个结果 | ❌ 先主线程 |
| 单文件小改 | ❌ |
B. 分工提示词模板
先给出 subagent 分工计划，不要立刻改文件。
目标：[总目标]
范围：[目录/文件]
约束：[不能做的事]
分工：
- Agent A：[任务A]
- Agent B：[任务B]
汇总后再决定是否执行。C. 推荐学习资源
- Codex Subagents 官方文档：https://developers.openai.com/codex/subagents