# Codex Construction

> 主代理出方案、Codex 裸调施工的轻量任务编排：分批派工、按档派 effort、后台监控、分阶段验收、改-审循环。用户说「安排 codex 施工/干活/审」或调用 /codex-construction 时使用。

- Skill: `shengyy/codex-construction` (Agent Skill)
- Install (CLI): `npx skillmds@latest add shengyy/codex-construction`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shengyy/codex-construction/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: shengyy (https://skillmd.com/u/shengyy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shengyy/codex-construction

---


# codex-construction — 轻量派工编排

编排的价值在**分工、边界、验收**，不在过程管控。不替 codex 写码，不给实现细节；给合同、给全权、给对得上的档位，验收结果。

## 分工

- **主代理**：出方案与施工合同、拆批、定档、派工、监控、验收、终审。
- **Codex**：一批之内全自主——读合同、实现、跑门禁、分阶段 commit、写验收包。
- 互不越界：主代理不中途接管施工，codex 跑砸了重派而不是主代理替写；codex 不做产品级裁决。

codex 独干的系统性偏差是**过度工程**（含过度测试），所以主代理只在三处介入：合同定稿时杀复杂度、验收时拒收合同外机制、BLOCKED 快裁快回。

## 档位

effort 只用三档：`medium` / `high` / `xhigh`。档位跟**合同留给 codex 的裁量空间**和**出错代价**走，不跟任务「重要性」走。

| 档位 | 用于 | 判据 |
|---|---|---|
| `medium`（施工默认） | 常规功能施工、按合同写测试、机械收尾、根因已知的定点修复、审查已定位问题的修复轮、收口核验 | 合同已写明「做什么」，codex 只定局部「怎么做」；做错门禁或 diff 能抓住，返工不出本批 |
| `high` | 骨架批、跨模块重改动、根因未知的排查、全批次审查、medium 拒收/BLOCKED 后的重派 | 合同留了设计空间，或任务是「找问题」而非「做事」 |
| `xhigh` | 架构重构定型批、资金/并发/安全核心、最终态全面对抗审、high 重派再失败的最后一轮 | 错了要回滚多批，或要找上一轮 high 没找到的问题 |

- **用户点名优先**：用户指定了档位或模型就按用户的；没指定才按本表。
- **升档，不同档重试**：某档拒收、BLOCKED 或无交付，重派升一档；xhigh 仍不过 → 熔断回方案层。
- **审 ≥ 施工**：审查档不低于被审批次的施工档。
- **不降档区**：xhigh 项不因额度降档，额度不够等窗口。
- **省额度靠合同和批次，不靠降审查档**：批拆细、合同写到「做什么」才派 `medium`；合同还留着设计题的批，先在方案层把题做掉，或派 `high`。
- 启动和 resume 都**必须显式传 effort**，漏传静默掉回 config 默认档。

## 启动

```bash
nohup bash -c 'exec codex exec -m gpt-6-astra -c model_reasoning_effort="medium" \
  --dangerously-bypass-approvals-and-sandbox -o LAST.md - < PROMPT_FILE' > RUN.log 2>&1 & echo "pid=$!"
```

- 模型名以本机 `~/.codex/config.toml` 为准；换名先用 `codex exec -m <名字> "打印 ok"` 探针验证，400 即无效。
- `--dangerously-bypass-approvals-and-sandbox`：关沙箱和审批，不依赖 config，exec / resume 都收。没有兜底，边界全靠 prompt 写明。
- `-o LAST.md`：最终消息落盘，终态只看它。每批独立命名，启动前不得已存在。
- **合同必须走 stdin（`- < FILE`），不许 argv `"$(cat FILE)"`**：argv 会把合同泄进 `ps`，codex 会把含本合同的进程认成别人的施工会话转去监控它，轮询自己零开工（2026-08-15：5 小时 0 commit）。
- 合同开头**角色钉死**：你就是施工者本人，收到即开工；ps 里含本合同文本的进程就是你自己。
- **启动调用必须秒回**：同一次 Bash 里不得再带耗时前台命令——外层超时按进程组 SIGKILL，`nohup` 挡不住。
- 运行中的日志不要 truncate。
- **启动后立刻记下日志头部的 `session id:`**（修复轮靠它续接），顺手核对 `reasoning effort:` 是所选档。

## 监控：先等进程，再读 LAST.md

`echo $!` 拿到的 pid 就是 codex 本身——靠的是 `bash -c` 里那个 `exec`；漏掉它 `$!` 就是 bash 包装进程，codex 是其子进程，`kill -0` 仍能判活，但杀它不会杀到 codex。**进程还在就是在跑，不解析日志**；进程消失后看 `LAST.md`：

| 终态 | 判定 | 处置 |
|---|---|---|
| 完成 | `LAST.md` 尾部 `STAGE N DONE` | 进验收 |
| 主动阻断 | `LAST.md` 尾部 `BLOCKED[批N]:` | 裁决后 resume |
| 无交付 | 有 `LAST.md`，两个标记都没有 | 读它定性，resume 收口或重派 |
| 额度耗尽 | 无 `LAST.md`，`RUN.log` 尾部 `ERROR: You've hit your usage limit … try again at HH:MM`，exit 1 | 到时刻后续接：有进度 resume，零进度重跑。不算一轮，不升档 |
| 崩溃 | 无 `LAST.md`，日志无错误行、停在半途 | 多为外层组杀，重跑或 resume |

- **别在 `RUN.log` 里 grep 标记**：codex 开跑会回显 prompt 原文，合同里的标记字样会在日志开头命中。
- 日志反复对同一 pid `kill -0` / `ps` 轮询且 git 零 commit = **自我监控死锁**，立杀重派，别等终态。
- 进程活着 + 日志静默 20 分钟 = 卡死告警，不是「停在阶段边界等裁决」——`codex exec` 是单轮进程，BLOCKED 后必然退出。

## Prompt 五要素

各要素一个 XML 块，块内只写事实和边界，不塞方案正文、历史对话、无关日志：

1. `<site>` **现场**：仓库路径、分支、前序进度。
2. `<contract>` **合同**：指向方案文档路径让 codex 自己通读。
3. `<scope>` **范围**：本批做什么、明确不做什么。
4. `<redlines>` **红线**：只写真红线，用具体动作边界表述（push / 部署 / 生产库），不写抽象绝对句，不写实现细节。
5. `<delivery>` **交付**：分阶段 commit + 验收包作为最终消息；完成时末尾单独一行 `STAGE N DONE` + commit hash，需裁决时末尾 `BLOCKED[批N]: <原因>` 停在阶段边界。

**自主权条款（必写）**：这是无人值守的单轮会话，没人会回答问题——按最合理的低风险解释继续做，不停下来问；施工中发现的真实问题在范围内自行根因修复并记入验收包；只有推翻合同前提或触碰红线才 BLOCKED。

**测试边界（必写）**：可逆、低影响的改动不写镜像实现的测试；合同要求的测试过了就停，只有新改动、新失败或未解决的疑虑才扩测或重测。

**不要求中途汇报、不要求先出计划**：会让模型中途停。只要最终消息。

验收包骨架：目标 / diff 摘要 / 物理删除项 / 测试状态（含预期 RED）/ 未验证项。

## 批次

- 同一工作树**串行**；并行只允许各自独立 worktree 且文件集不相交。
- 一批 = 一个可独立验收的工作包，验收后才放行下一批。
- 大工程默认三段：骨架（含 RED 测试，`high`；架构定型 `xhigh`）→ 重改动（`medium` 起，跨模块 `high`）→ 机械收尾（`medium`）。
- codex 施工中不要并行跑门禁、切分支或改同树文件。

## 改-审循环

审查用**全新会话**保独立性，prompt 写明只审不改、结论走 `-o`；可换模型或换 agent 交叉审。修复轮才续上下文：

```bash
codex exec resume <session-id> -m gpt-6-astra -c model_reasoning_effort="<medium|high|xhigh>" \
  --dangerously-bypass-approvals-and-sandbox -o LAST2.md "<裁决或修复指令>"
```

- 长修复轮同样按启动一节后台起（nohup + exec + `-o`），不在前台等。
- 审查从 `high` 起步；触及不可逆资产的最终态对抗审用 `xhigh`。修复轮按问题定档：审查已定位 → `medium`；审查指出的是设计问题 → `high`。
- **必须用显式 session id，不要用 `--last`**：`--last` 只在当前 cwd 找，找不到就静默新开空会话（exit 0、无警告），修复轮零上下文重跑。session id 跨 cwd 有效。
- **effort 和权限旗标必须重传**：resume 不继承，漏传静默掉回 config 默认。
- resume 后核对日志头部 `session id:` 与原会话一致，不一致就是没续上。
- 续接一律用裸 CLI，不要改用 `/codex:*`——插件看不见裸调起的会话。
- 默认**单路**：首轮无阻断即收口；有阻断则修复后换新会话复审，一轮干净即可。触及不可逆资产或反复冒新阻断，才用 until-dry（连续两轮无新发现）。
- **主代理必须抽验**：自己重跑关键门禁，不信验收包里的 "passed"。
- **熔断**：阻断性修复超 3 轮不收敛，或修 A 破 B 振荡，立即停——方案错了，回方案层重裁，不是加轮次。