第一次使用 Subagents 做只读评审

第一次使用 Subagents 做只读评审

这一篇正式使用 Subagents。

但我们依然不让它们改代码。 第一次练习只做：

多个子代理并行只读评审项目，然后由主会话汇总结果。

这是一种很稳的入门方式。 它能让你看到 Subagents 的价值，又不会因为多个代理同时改文件而产生冲突。

前置教程：Subagents 是什么
如果你还不能说清楚 Subagents 适合什么、不适合什么，先看前置教程。

依据来源：OpenAI Codex 官方手册中 Subagents、Subagent concepts、/agent、sandbox controls、approval request、built-in agents 和 custom agents 等章节。

本篇目标

完成后你应该能做到：

• 明确告诉 Codex 使用 Subagents。
• 把任务拆成 3 个只读方向。
• 要求所有子代理不修改文件。
• 用 /agent 查看子代理线程。
• 识别子代理是否偏题。
• 遇到权限请求时不盲目批准。
• 等所有子代理完成后，看懂主会话汇总。
• 把评审结论转成下一步任务，而不是让多个代理乱改。

第一次练习为什么只读

因为 Subagents 的优势是并行。 并行最适合“互不干扰”的工作。

只读评审天然适合并行：

• 一个子代理看项目结构。
• 一个子代理看文档步骤。
• 一个子代理看构建和脚本说明。

它们互相不抢文件。 最后只要把发现汇总回来即可。

并行改代码则不同。 多个子代理可能同时改同一个组件、同一个配置、同一份文档。 新手第一次就这么做，很容易把工作流搞乱。

准备工作

开始前确认 4 件事：

• 你已经在 Codex CLI、桌面版或支持 Subagents 的入口里打开了一个项目。
• 当前项目没有未保存的重要临时文件。
• 你知道本次练习只是评审，不做修改。
• 你能接受 Codex 为并行子代理消耗更多 token。

如果你不确定当前项目是否适合练习，先问 Codex：

请只读检查当前项目是否适合做第一次 Subagents 只读评审练习。

要求：
1. 不要使用 Subagents。
2. 不要修改任何文件。
3. 检查当前目录是否像一个正常项目。
4. 检查是否存在 README、package.json、docs、src、配置文件等常见结构。
5. 告诉我是否适合做“项目结构、文档完整性、构建脚本说明”三个方向的只读评审。

预期结果：

• Codex 会先判断项目是否足够完整。
• 如果项目太小，它会建议换一个更合适的练习项目。
• 它不会启动 Subagents。

第 1 步：发出第一次 Subagents 任务

复制下面这段给 Codex：

请使用 Subagents 并行只读评审当前项目。

任务目标：
我想练习第一次使用 Subagents。请不要修改文件，只做并行分析和汇总。

拆分方式：
1. 子代理 A：只评审项目结构是否清晰，包括目录分层、入口文件、主要模块是否容易理解。
2. 子代理 B：只评审文档是否喂饭级，包括 README、docs 或项目说明是否缺步骤、缺前置条件、缺验收方式。
3. 子代理 C：只评审构建和脚本说明是否清楚，包括 package.json、脚本命令、构建方式、测试方式和常见失败点。

限制：
1. 所有子代理只读分析，不修改任何文件。
2. 不要提交 Git。
3. 不要安装依赖。
4. 不要删除、移动、重命名文件。
5. 不要联网。
6. 如果任何子代理需要权限，请先解释原因，不要默认批准。
7. 请等待所有子代理完成后再汇总。

汇总格式：
1. 先给总体判断：这个项目对新手是否容易理解。
2. 再分别汇总 A/B/C 三个方向，每个方向最多 5 条发现。
3. 每条发现必须带文件路径或证据。
4. 最后给出 3 个最小改进建议，但不要执行。

这段提示词里最重要的是：

• 明确说“使用 Subagents”。
• 明确拆成 3 个子代理。
• 明确每个子代理只负责一个方向。
• 明确只读。
• 明确等待所有子代理完成后汇总。

第 2 步：观察 Codex 有没有真的启动子代理

Codex 收到任务后，应该会开始调度子代理。

你要观察这些现象：

• 是否出现多个 agent thread。
• 是否每个子代理都有自己的方向。
• 是否主会话说明会等待所有结果。
• 是否没有立刻开始改文件。

如果 Codex 没有启动子代理，而是自己单线程分析，你可以追问：

我这次练习的目标是使用 Subagents。
请显式派出 3 个子代理：
1. 项目结构评审代理。
2. 文档完整性评审代理。
3. 构建脚本说明评审代理。
每个子代理只读分析，不修改文件。请等待全部完成后再汇总。

如果 Codex 说当前入口不支持或看不到 Subagents，不要硬做。 记录下来：

请告诉我当前入口是否支持 Subagents。
如果当前入口不支持，请告诉我应该切换到哪个 Codex 入口继续这个练习。
不要修改任何文件。

第 3 步：用 /agent 查看子代理线程

在 CLI 里输入：

/agent

这个入口用于查看或切换 agent thread。

你第一次使用时，只需要检查 5 件事：

• 有没有主会话。
• 有没有多个子代理线程。
• 子代理名称或描述是否能对应 A/B/C 三个方向。
• 有没有子代理还在运行。
• 有没有子代理已经完成。

如果你看不懂 /agent 页面，可以直接问 Codex：

请解释我在 /agent 里看到的线程列表。

要求：
1. 告诉我哪个是主会话。
2. 告诉我哪些是子代理。
3. 告诉我每个子代理负责什么方向。
4. 告诉我哪些已经完成，哪些还在运行。
5. 不要修改文件。

第 4 步：检查子代理有没有偏题

第一次练习最重要的不是“跑完”，而是看子代理是否守范围。

你可以问主会话：

请检查当前运行中的子代理是否都在本次任务范围内。

本次范围：
1. 项目结构评审。
2. 文档完整性评审。
3. 构建脚本说明评审。

限制：
1. 子代理只能只读分析。
2. 不要修改文件。
3. 不要安装依赖。
4. 不要联网。

请告诉我是否有子代理偏题，如果有，请建议如何停止或纠正。

如果发现某个子代理偏题，比如开始研究部署、数据库或业务逻辑，你可以说：

请停止偏题的子代理。

原因：
它已经偏离本次只读评审范围。

要求：
1. 不要让它继续执行命令。
2. 不要让它修改文件。
3. 保留它已经产生的有用结论。
4. 最终汇总时标注该子代理已停止。

这一步的目的，是让你学会控制并行任务。

第 5 步：遇到权限请求时怎么处理

Subagents 会继承当前会话的沙盒和权限策略。 如果某个子代理触发权限请求，你可能会在当前界面看到提示。

不要顺手批准。

先复制这段问 Codex：

请解释这个权限请求。

要求：
1. 说明请求来自主会话还是哪个子代理。
2. 说明它想执行什么。
3. 说明为什么需要这个权限。
4. 判断它是否违反“只读评审，不修改文件，不联网，不安装依赖”的限制。
5. 如果不批准，是否仍然可以完成本次只读评审。
6. 给出建议：批准、拒绝，还是让它改用只读方式。

一般来说，第一次只读评审不应该需要高风险权限。

如果它请求：

• 删除文件。
• 写文件。
• 安装依赖。
• 推送代码。
• 联网下载。
• 读取密钥。

直接拒绝，并让 Codex 改用只读方式：

拒绝这个权限请求。
请让相关子代理改用只读方式继续分析。
如果无法继续，请让它停止，并在最终汇总里说明原因。

第 6 步：等待主会话汇总

不要在子代理还没完成时就急着让 Codex 下结论。 你可以问：

请告诉我当前 3 个子代理是否都已经完成。
如果没有，请继续等待。
如果都完成了，请按原定格式汇总。

最终汇总应该包含：

• 总体判断。
• 项目结构方向发现。
• 文档完整性方向发现。
• 构建脚本说明方向发现。
• 每条发现的证据。
• 3 个最小改进建议。
• 明确说明没有修改文件。

第 7 步：验收汇总质量

不要只看“有一大段总结”。 要看它是不是可用。

复制这段验收提示词：

请自查这次 Subagents 只读评审结果是否合格。

验收标准：
1. 是否真的使用了 3 个子代理。
2. 3 个子代理是否分别对应项目结构、文档完整性、构建脚本说明。
3. 是否全程只读，没有修改文件。
4. 每条发现是否有文件路径或明确证据。
5. 是否有不确定但被当成事实的内容。
6. 是否给出了 3 个最小改进建议。
7. 是否适合进入下一步单代理修改。

请按“通过 / 不通过 / 需要补充”的格式输出。

如果它的结论太虚，比如只有：

项目结构还可以，文档可以优化，脚本建议完善。

这不合格。

让它补证据：

这次汇总太笼统，不符合喂饭级要求。
请重新汇总，每条发现必须带文件路径、具体问题、为什么影响新手、建议怎么改。
不要修改文件。

第 8 步：把评审结果变成下一步任务

Subagents 只读评审完成后，不要立刻让所有子代理一起改。

正确做法是：

请根据刚才 Subagents 的只读评审结果，帮我选择一个最小、最安全、最值得优先做的改进任务。

要求：
1. 只选一个任务。
2. 说明为什么先做它。
3. 列出预计修改哪些文件。
4. 写出验收标准。
5. 暂时不要执行。

然后再让一个 Codex 会话执行这个任务。 不是让多个子代理同时改。

如果你确定要修改，可以继续：

请执行刚才选出的最小改进任务。

要求：
1. 只修改你刚才列出的文件。
2. 不要扩大范围。
3. 修改后自行检查 diff。
4. 如果项目有明确构建或检查命令，请按项目规则执行。
5. 最后用中文总结修改内容、验收结果和风险。

这一步已经不是 Subagents 练习本身。 这是把并行评审结果转成单线程改进任务。

常见失败分支

Codex 没有启动 Subagents

可能原因：

• 当前入口不支持 Subagents。
• 你的提示词没有明确说“使用 Subagents”。
• 任务太小，Codex 判断没必要拆。

处理方式：

请明确告诉我：当前会话是否支持 Subagents。
如果支持，请按我指定的 3 个方向派出子代理。
如果不支持，请告诉我应该换到哪个入口继续。
不要修改文件。

子代理开始修改文件

立即叫停：

请立即停止所有正在修改文件的子代理。
本次任务只允许只读评审。
请汇总已经产生的只读结论，并列出是否有文件被修改。
如果有修改，请先不要继续，告诉我修改了哪些文件。

子代理结论互相矛盾

这是正常现象。 不同子代理从不同方向看问题，可能会有不同判断。

让主会话做仲裁：

请对比各子代理结论中互相矛盾的部分。

要求：
1. 列出矛盾点。
2. 分别说明各自证据。
3. 判断哪一边证据更强。
4. 如果无法判断，标注为待人工确认。
5. 不要修改文件。

汇总没有证据

让它补：

请给每条发现补充证据。

要求：
1. 每条发现必须带文件路径。
2. 如果没有文件路径，也要说明证据来自哪里。
3. 删除没有证据支撑的判断。
4. 不要新增猜测。

本篇验收标准

完成本篇后，你应该拥有：

• 一份发送给 Subagents 的只读评审提示词。
• /agent 中看到的子代理线程状态。
• 一份权限请求处理记录，如果本次没有权限请求，可以记录“未出现权限请求”。
• 一份主会话最终汇总。
• 一份“通过 / 不通过 / 需要补充”的自查结果。
• 一个从评审结果中选出的最小后续任务。

只要你能做到这些，就说明你已经跑通了第一次 Subagents 工作流。

下一步可以继续学习“自定义子代理”，或者先用这套只读评审方法去审查一个真实项目。