CX-08 Subagents 完整指南:App 中的多 Agent 协作
主要来源:OpenAI Codex Subagents、App Features、CLI Slash Commands 官方文档。
课程信息
⠀
-
作者:老金
-
GitHub:https://github.com/KimYx0207
-
公众号:老金带你玩AI
-
X(Twitter):老金带你玩AI
-
个人博客:https://aiking.dev
-
预计学时:2-3小时
-
难度等级:⭐⭐⭐ 进阶级
-
更新日期:2026年5月30日
-
信息来源:OpenAI Codex Subagents、App Features、CLI Slash Commands 官方文档
-
前置要求:已完成CX-01至CX-07,熟悉App基本操作
📚 本课学习目标
⠀
完成本课学习后,你将能够:
⠀
-
判断何时需要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
-
本系列上一篇:CX-07 Plugins 连接器
-
本系列下一篇:CX-09 Automations 后台任务
课程制作:老金
最后更新:2026年5月30日
许可:本课程采用CC BY-NC-SA 4.0许可
下一步
⠀
下一篇:CX-09 Automations:App 里的后台任务和周期检查。