# Codex Conductor

> 「Claude 当大脑、Codex 当手」的委派工作流——把实现类任务经 codex:codex-rescue agent 派给本机 Codex CLI，Claude 负责拆任务、写任务书、独立验收、合并提交。用户说「派 codex / 让 codex 干 / codex 实现」，或有成批实现任务需要委派时用。

- Skill: `garveyhu/codex-conductor` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add garveyhu/codex-conductor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/garveyhu/codex-conductor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: garveyhu (https://skillmd.com/u/garveyhu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/garveyhu/codex-conductor

---


# Codex Conductor（Claude 指挥 · Codex 实干）

把「Claude 编排 + Codex 实现」跑成稳定流水线的工作流。从一场真实战役（MediaStudio 插件体系 9 个工作包全部由 Codex 实现、Claude 验收合并）沉淀而来。

## 分工铁律

- **Claude（大脑）**：拆解需求 → 写任务书 → 派发 → **独立验收** → 亲自 commit / merge。
- **Codex（手）**：只按任务书实现，不参与验收自己的活。
- **验收权不下放**：Codex 的完工报告一律不作数——以 Claude 亲自跑出的验证门（build / test / lint 全绿）+ 逐提交 diff 审查为准。

## 前提

- 本机装有 openai-codex 插件（提供 `codex:codex-rescue` agent）+ codex CLI 已登录（`codex login status`）。
- 没配好时引导用户跑 `/codex:setup`，不要自造 auth 流程。

## 派发方式

用 Agent 工具派 `codex:codex-rescue`，任务书写进 prompt，路由旋钮附在末尾：

```
Agent(subagent_type: "codex:codex-rescue",
      prompt: "<任务书> --write --background",
      run_in_background: false)
```

| 旋钮（写在 prompt 里） | 作用 |
|---|---|
| `--write` | 要改文件就带上（不带 = 只读） |
| `--background` | 长任务让 Codex 后台跑，subagent 秒回 job-id，Claude 腾出手干别的 |
| `--resume` | 续上一个 Codex 会话（「继续 / 修掉刚才那个问题 / 再深挖」） |
| `--model <型号\|spark>` / `--effort <low…xhigh>` | 覆盖默认档；何时用什么组合见下方角色表 |

**模型与推理强度的「默认档」一律不传参**——继承用户 `~/.codex/config.toml` 里设好的慣用型号与强度；用户改习惯只动 config 一处，skill 与 prompt 永不硬编码型号。

长任务两种等法（选一）：prompt 带 `--background` 后用下方 companion 轮询；或 Agent 调用本身 `run_in_background: true`，等 harness 通知。

## 角色档位（派发前先选角色）

角色 = 「模型档 + effort + 读写 + prompt 姿态」的预设组合，由 Claude 派发时套进任务书。**选档规则：默认 builder；规格明确照图施工降 coder；机械活降 chore；吃不准范围先 scout；反复修不动升 detective；每波收尾必过 reviewer。**

| 角色 | 适用任务 | 模型 / effort | 读写 | 详规（任务书骨架 + 姿态细则） |
|------|---------|--------------|------|------|
| **builder** 主力实现 | 核心功能、成批工作包、重构（要做设计判断） | 默认档 / 默认档 | `--write`（+ `--background` + worktree） | [references/builder.md](references/builder.md) |
| **coder** 确定性编码 | 规格明确照施工图写：按既有模式补模块 / 接口 / 测试 | `--model gpt-5.6-luna` / 默认档 | `--write` | [references/coder.md](references/coder.md) |
| **chore** 机械杂役 | 批量替换 / 搬运 / 格式化 / 依赖跑腿（无需理解代码） | `--model spark` / `--effort low` | `--write` | [references/chore.md](references/chore.md) |
| **detective** 疑难侦探 | 反复修不好的 bug、深度根因勘探 | 默认档 / `--effort high` | 先只读诊断 | [references/detective.md](references/detective.md) |
| **scout** 勘探研究 | 大库摸底、方案调研、可行性验证 | 默认档 / 默认档 | 只读 | [references/scout.md](references/scout.md) |
| **reviewer** 对抗评审 | 波次验收、安全边界审查 | 默认档 / `--effort high` | 只读 | [references/reviewer.md](references/reviewer.md) |

**派发前先读对应角色的 reference 文件**，按其任务书骨架写 prompt。三层实现阶梯的直觉：builder（要设计判断）> coder（答案基本唯一）> chore（不用理解代码）——拿不准往上一档放。

角色可按需增设（加一行 + 建一个 reference 文件）；要调某角色的型号，只改该角色行与其 reference（型号只许出现在这两处，默认档永远指 config）。本机可用型号阶梯查 `~/.codex/models_cache.json`（sol 旗舰 / terra 均衡 / luna 快省 / spark 极速）。一次派发只套一个角色——又实现又自审 = 实现者自己验收，违反分工铁律。

## 任务书写法（实战沉淀）

1. **开头给锚**：仓库绝对路径、当前分支、必读文档（工程宪法 / 设计规范 / 契约文档的具体路径）。
2. **交付定义 + done-gate**：明确列「跑什么命令、什么算绿」。测试**攒一大批一起跑**，别让 Codex 每小步都测（会拖拉）。
3. **多任务并成波次**：一份大任务书列 N 个子任务、让 Codex 自排顺序，好过 N 次零碎派发。
4. **提交规矩写进任务书**：Angular commitlint（type 英文小写、subject 不许大写字母开头）、一任务一提交、scope 用包名。
5. **长写盘任务令其自开 worktree 干**，严禁在主目录切分支——真实事故：Codex 中途切走主目录分支，Claude 的提交落到错误分支上。
6. 项目有「用户把关门」（需要用户肉眼确认的节点）时，在任务书里标明停点。

## 验收协议（每波必做）

1. Codex 报完工 → Claude **亲自**跑 done-gate（turbo / test / lint），全绿才算数。
2. `git log` + `git show` 逐提交审查：范围有没有越界、有没有夹带无关文件（lint-staged 失败会把文件留在暂存区，最易夹带）。
3. Codex 在 worktree 干的 → Claude 亲自 merge 回主分支；**提交前先 `git branch --show-current` 确认所在分支**。
4. 有疑点：派 `/codex:review` 或 `/codex:adversarial-review` 交叉审，或 `--resume` 打回让 Codex 重修。

## 后台任务管理

主线程直接查 companion（路径含插件版本号会变，动态解析）：

```bash
COMPANION=$(ls -d ~/.claude/plugins/cache/openai-codex/codex/*/scripts/codex-companion.mjs | tail -1)
node "$COMPANION" status --all      # 看全部任务
node "$COMPANION" result <job-id>   # 取某任务结果
node "$COMPANION" cancel <job-id>   # 取消
```

**⚠️ rescue subagent 的「完成」≠ Codex task 完成（血泪坑）**：`codex:codex-rescue` 是纯转发器，它把 task 发到 companion 后台**就立刻返回并触发完成通知**——那一刻真正的 Codex task 才刚启动。别把这个 subagent 通知当审计完成。task 的真实终态**只能**靠 companion 主动查：拿它返回里的 `task-<id>`，轮询 `status --all` 到该行状态变 `completed`/`failed`，再 `result <id>` 取报告。

**轮询判定要认状态字段，别数任务条数**：`completed` 的 job 会从 `status --all` 的 active 列表里消失——所以「凑够 N 个且 running==0」这类计数判据永远不成立、必然假超时（本会话实测栽过两次）。正确写法：对**每个已知 task-id** grep 它那一行，命中 `completed|failed|cancelled` 或**整行消失**即判其结束；全部结束才收工。轮询用长间隔（30–60s）少打扰。

**看守要盯 log 增长、别只看 status（早警卡死）**：task 的 job log（`.../state/<repo>/jobs/<task-id>.log`）里 `Starting Codex Task → Starting task thread → Thread ready → Turn started → Running command…` 是真实心跳。健康任务几秒内就过 `Thread ready` 且 log 持续长；**卡死的任务会停在某行几十分钟不动而 status 仍显 running**（本会话真机：卡在 `Turn started` 41 分钟、log 4 行不长）。看守除查 status 终态外，加一条：`i≥6`（约 12min）时 log 仍 `≤5` 行 → 判卡死早退报警；log mtime 停滞 >15–20min → 判挂起。别再傻等 3 小时黑盒。

**`--resume` 的 turn 会挂起（血泪坑·区别于 broker 死）**：resume 一个上下文很大的会话时，log 能到 `Thread ready`+`Turn started` 但那个 turn **十几分钟零输出**（broker 是活的、socket 在——不是下面那种 broker 死）。这是 resume 机制本身卡。修法：取消卡死的 resume，**改派一个 fresh 任务**（把要续的规格/plan 直接内联进 prompt，不用 `--resume`）——fresh 任务不会挂。经验：大会话续跑优先内联重派而非 `--resume`。

**卡在 `Starting Codex task thread` 起不来 = 共享会话 broker 崩了（血泪坑·已实测修复）**：openai-codex 的「shared session」靠一个 **broker 进程**中介（companion task-worker ⇄ codex app-server），信息在 `…/state/<repo>/broker.json`（`endpoint`/`pidFile`/`sessionDir`/`pid`）。ChatGPT.app 重启等会让 broker 进程死掉，但 `broker.json` 仍死指着它 → 之后**每个新 task 都连死 socket、卡在 thread 启动、status 永远 running**。`companion setup` 只报 `connect ENOENT …/broker.sock` 不自愈。**修法**：确认 broker 死了（`ps -p <pid>` 无进程 / `broker.sock` ENOENT），`rm` 掉 stale `broker.json` + 其死 `sessionDir` 目录，再派任务——`ensureBrokerSession` 会自动拉起新 broker（`broker.json` 换成新 `sessionDir`+新 pid）。先派个极小 smoke（`task --background "print SMOKE_OK"`）验证越过 `Thread ready` 再重派真活。

## 禁止

- ❌ 把 Codex 的完工报告当验收结果直接汇报给用户（必须亲验）
- ❌ Codex 后台写盘期间在同一目录做 git 操作（commit / checkout / merge）
- ❌ prompt 里硬编码模型型号（默认档一律继承用户 config；型号只许出现在角色表里）
- ❌ 同一任务书混两个角色（又实现又自审 = 实现者自己验收）
- ❌ 几分钟能干完的小活也派 Codex（自己干更快）
- ❌ 替用户 push（对外操作，先确认）