codex-construction — 写好简报，然后放手

把 Codex 当成顶尖工程师：讲清为什么做、做成什么样、什么最重要、做到多好、要什么品味，然后放手。主代理也是顶尖工程师，本文只给它原则和模型推不出来的 CLI 事实。

原则

• 硬规则只有两类：不可逆的动作边界（红线），以及启动、监控、续接依赖的 CLI 实测事实（含运行约定里的结尾标记）。这两类照做。
• 其余都是判断：简报多长、批怎么拆、派哪一档、要不要独立验证、何时止损，主代理定；怎么设计、实现、验证、切 commit，Codex 定。文中的具体做法都是参考。
• 放开怎么做，写清做什么：目标、范围和完成条件越清楚，越能放手。
• 以运行结果为准：完成、通过、有问题，都要有一次真实运行作证——跑真实命令、走一遍改动的流程、读回写入的值。读代码推出来的意见不算证据：这类意见每一轮都能再挑出一批，照着改只会往代码里堆防御和抽象，过度工程多半由此而来。
• 用理由约束，不用禁令约束：担心的偏差（例如过度工程）写成「说明为什么值得」，不写成「不许」。
• 用户的明确要求优先于本 skill。

分工

• 主代理：吃透目标、写简报、拆批、派工、验收，把住需要用户拍板的决定。
• Codex：一批之内的设计、实现与可逆取舍。
• 做砸了带着反馈重派，不中途接管：接管会让验收失去独立的参照。

写简报

像给一位没参与前期讨论的顶尖同事交代任务：讲清目标和门槛，不规定做法。一份好简报覆盖下面五件事；它们是检查清单不是表格，篇幅跟着任务走，修个小 bug 几句话就够。

篇幅花在仓库给不了的东西上：为什么做、什么算完成、什么最重要、红线和品味只在用户和主代理心里，单轮会话里 Codex 没有机会问。仓库里查得到的，只给能省掉大量摸索的线索，例如已定位的故障入口、同类实现、已排除的方向。

1. 背景：什么项目、为什么做、做成了对谁有什么价值、走到哪一步（仓库路径、分支、前序 commit、方案文档路径）。动机讲清楚，没写的约束它能自己推出来。方案文档写目标、已和用户敲定的决定与约束，不写实现步骤，免得提前用掉 Codex 的设计空间。
2. 交付：写成能跑的检查——用什么命令、场景或数据，看到什么结果算成立。这就是完成条件，验收时跑的也是这几条。项目里有能驱动真实应用的 verify skill 就点名它和要走的功能。
3. 重点：这批真正要紧的一两件事、用户最在意什么、哪里最容易做错，以及这批不做什么。全都重要就等于没有重点。
4. 质量与资源：门槛写成可感知的标准，例如「做到你愿意署名」；达到门槛需要的手段都授权——读任何代码、跑本地命令、重构本批涉及的代码、反复迭代。提交的测试只守真正会坏的地方，规模参照相邻测试，可逆、低影响的改动不写镜像实现的测试。知道的好工具、现成数据、同类实现和已知的坑，用「我觉得 X 够用」的口吻给，它有更好的办法就用它的。
5. 风格与品味：像这个仓库原本就有的代码，偏好删减和简单，指一两个写得好的文件做参照。新抽象、配置项或兼容层可以引入，说清为什么值得；说不清的，通常就是过度工程。

固定结尾

• 红线：完整权限之外唯一的边界。只写不可逆或有外部代价的具体动作（push、部署、生产库、付费 API），附一句代价——这在仓库里看不出来，写明了它也认得出同类动作。没有就写「无」。
• 运行约定：施工简报照抄下面这段，把 N 换成批号。不要另外要求先交计划：单轮会话交完计划就会结束。

这是无人值守的单轮会话，没有人会回答问题，提问只会卡住整批工作。设计、实现、验证方式和可逆的取舍都由你决定，不必请示；遇到歧义，按简报和仓库代码最直接支持的理解去做，把假设写进验收包。
妨碍本批交付的问题从根因修掉。路上发现的其它问题，小而明确、不碰简报排除的部分、不影响简报要守的行为的，顺手修掉并单独 commit，方便验收时单独撤回；大的、有风险或需要取舍的，写成后续建议。交付里的每一项都实现、并按用户使用它的方式真正跑过（真实命令、改动的流程、读回写入的值）才算完成；编译通过、测试全绿不等于跑过，只交出初版、或以「下一步我会……」收尾都不算。
只有推翻简报前提、需要不可逆的决定、要越过红线，或遇到本会话排除不了的阻塞时才停下，停下前先做完不依赖它的部分。
最终消息是验收包，只写在消息里，不另存进仓库——过程记录对之后读代码的人是噪音：目标 / diff 摘要 / 删除项 / 验证证据（每项交付跑了什么命令、关键输出，含预期 RED）/ 自主判断与理由 / 顺手修复 / 后续建议 / 未验证项。末尾单独一行：完成写 `STAGE N DONE <commit hash>`；需要裁决或受阻写 `BLOCKED[批N]: <原因>`。

派工前自检：没参与讨论的人只读这份简报，能不能说出为什么做、做成什么样算好、什么最重要、什么样的代码算有品味？说不出来就补简报。补不上的那段——通常是重点和品味——在用户心里，先问用户，别替用户编。

示例（中等规模的施工；运行约定省略）

背景：shop-api 的订单导出每次全量拉库，大客户导出要 10 分钟，经常超时，客服每周都在帮客户手工拆单。这批把导出改成流式分页。方案在 docs/plans/export-streaming.md，先通读；上一批已在 feat/export 分支合入游标 API（a1b2c3d）。

交付：用 scripts/seed-large.ts 生成的 50 万单数据集，真实调用导出接口：1 分钟内完成、进程内存平稳，导出的 CSV 与旧实现逐字节一致（diff 为空）；旧的全量路径删除。

重点：用户最在意的是导出不再超时。CSV 的列和格式一个字节都不能变——财务有脚本在解析它。这批不碰导入功能。

质量与资源：做到你愿意署名为止。先读懂现有的分页和鉴权代码再动手，压测不达标就继续迭代；导出模块里需要重构的就重构。测试守住游标边界、空结果和中途断连。我觉得项目里已有的 pg-cursor 够用，你有更好的办法就用你的。

风格与品味：读起来像这个仓库原本就有的代码，src/export/invoice.ts 是写得不错的同类实现。偏好删减；要加新抽象或开关，说清为什么值得。

红线：不 push、不部署——push 会触发 CI 自动上线；不连 .env 里的库，那是生产库。

档位

effort 是给 Codex 的推理预算，用 medium / high / xhigh 三档：要做的判断越多、错了越难回滚，给得越足。low 撑不起无人值守的施工；max / ultra 多花的钱换不来相应的提升，只在用户点名时用（CLI 都接受）。用户点名档位或模型时按用户的。

参考：常规施工 medium；设计、排查未知根因、独立验证 high；架构定型、资金/并发/安全核心 xhigh。重派通常升一档，同档重试多半重犯同样的错；已在 xhigh 还不行，问题多半在简报。

启动

主代理的工具能后台运行命令、并在命令退出时唤醒主代理（如 Claude Code Bash 的 run_in_background）时，把命令直接交给它，退出即收到通知，不用轮询；要中止就停掉这个后台任务。后台任务的寿命要覆盖整批施工：Claude Code 在终端、桌面应用、VS Code 里的本地会话不限时；无人值守会话（-p、Agent SDK、CI、云端）默认 30 分钟、最长 2 小时，-p 以文本传 prompt 时默认 10 分钟，可用 BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS 调高。工具没有这种能力、寿命覆盖不了，或主代理会话可能先结束时，改走 nohup 回退，启动、判活和中止都按那份文件。

codex exec -m gpt-6-astra -c model_reasoning_effort="medium" \
  --dangerously-bypass-approvals-and-sandbox -o LAST.md - < BRIEF_FILE > RUN.log 2>&1

卡死的 Codex 不退出，也就没有通知，所以同时起一个看门狗后台任务，盯这一次调用的日志和 -o 文件（续接轮换成 RUN2.log / LAST2.md）：日志超过 N 分钟没动就退出，唤醒主代理去看日志；-o 文件出现时自己退出。N 按任务规模和档位定，高档位长时间推理时日志也会静默。Codex 退出后停掉看门狗。

until [ -f LAST.md ] || [ -n "$(find RUN.log -mmin +20)" ]; do sleep 60; done

启动要点（nohup 回退同样适用）：

• 模型默认 gpt-6-astra，每次显式传 -m：~/.codex/config.toml 里的默认模型和档位是给交互用的，各机不同。用户点名换模型时先用 codex exec -m <名字> "打印 ok" 探针，400 即无效。
• effort 显式传：漏传会静默掉回 config 默认档。
• 简报走 stdin（- < FILE）：放在 argv 会暴露到 ps，Codex 可能把自己的进程误认成另一个会话，转去监控而不开工。
• --dangerously-bypass-approvals-and-sandbox 给完整权限、不设审批，exec 和 resume 都收；边界只靠红线。
• -o LAST.md 把最终消息单独落盘，每批独立命名，启动前不得已存在。
• 启动后看 RUN.log 头部：记下 session id: 供续接，核对 reasoning effort:。

监控

等退出通知，卡死靠看门狗唤醒。是否完成不从日志判，疑似卡住时再看日志。进程退出后看 LAST.md：

• 额度耗尽的等待也交给后台任务：算出到点的秒数，后台跑 sleep <秒数> 当定时器，到点被唤醒后续接（有进度 resume，零进度按启动一节重跑），看门狗随之一起起。
• BLOCKED 要用户拍板、而用户可能已经离开时，用工具的推送通知叫回用户（如 Claude Code 的 PushNotification），别让整批工作停着等人发现。
• 别在 RUN.log 里 grep 标记：Codex 开跑会回显简报原文，标记字样会在开头命中。
• 日志里反复对 codex 自己的 pid kill -0 / ps、git 零 commit，是自我监控死锁，杀掉重派；它在等自己起的测试或构建子进程不算。
• 进程活着但日志长时间无新输出，可能卡死，结合任务规模判断；codex exec BLOCKED 后必然退出，不会停着等。
• 施工期间别在同一工作树跑门禁、切分支或改文件，会和它的改动互相干扰。

续接

裁决 BLOCKED、收口无交付、额度耗尽或崩溃后接着做、修复轮，都续上原施工会话：

codex exec resume <session-id> -m gpt-6-astra -c model_reasoning_effort="<effort>" \
  --dangerously-bypass-approvals-and-sandbox -o LAST2.md - < FIX_FILE > RUN2.log 2>&1

• 裁决或修复要求同样走 stdin；每轮的 -o 文件和日志都用新名字，上一轮的留着备查。
• 用显式 session id，不用 --last：--last 只在当前 cwd 找，找不到会静默新开空会话（exit 0、无警告）。session id 跨 cwd 有效。
• effort 和权限旗标每次重传，resume 不继承。
• resume 后核对日志头部 session id: 与原会话一致。
• 续接同样按启动一节后台起、配看门狗。续接用裸 CLI，/codex:* 插件看不见裸调起的会话。

验收

对照简报验收，不只看「跑通了没有」：

• 交付：主代理亲自跑简报里的检查和验收包给出的命令，以实际输出为准。验收包里的证据是线索不是结论，CI 全绿也只是输入：它们都没有像用户那样把改动跑起来。
• 重点：用户最在意的事是否真的做到，有没有被次要工作挤掉，范围有没有被悄悄缩小。
• 质量与品味：读 diff 是为了做减法：说不清为什么值得的新抽象、配置项、兼容层，不像这个仓库的代码，都要改。测试用两个设想的改动检验：把行为改坏，它该失败；只重构内部、行为不变，它该照常通过。做不到的测试只是负担，删掉或重写。
• 自主判断与顺手修复：逐条核实。不认可的顺手修复撤掉对应 commit；不同意的判断给出理由，而不只是换成自己的偏好。

不过就写具体反馈——失败的命令和输出，或该删的那段代码。问题已定位，按续接一节开修复轮，要求结尾照用运行约定；方向错了，改简报重派。修完由主代理重跑那几条失败的命令，确认转为通过，再跑一遍门禁。修复迟迟不收敛或修 A 破 B，说明简报或方案有问题——重写简报，比加轮次有效。

独立验证：作者只会检查自己想做的东西。改动面大、碰到用户最在意的路径，或主代理自己驱动不了那个表面（要长时间运行、要搭环境）时，值得再让没写代码的全新会话把改动跑一遍；要做时读 references/verification.md，里面是验证简报的结尾、发现的裁定和什么时候值得再验一次。可逆的小改动，主代理亲自跑过交付就够了。

批次

• 一批是一个可独立验收的工作包，切多大由主代理判断：批越大 Codex 发挥空间越大，批越小验收越容易、回滚越便宜。
• 同一工作树内串行，并发写会互相覆盖；要并行就用各自的 worktree，且文件集不相交。每批各起一个后台任务，各自退出各自唤醒，到一批验收一批。
• 本 skill 不依赖任何项目准备：没有 verify skill，交付照样写成能跑的检查（命令、接口、测试、数据）。补验证能力是额外的一批，主代理可以提议，用户同意才做，不要自己插进计划。值得提议的情形：项目没有脚本化的方式驱动真实应用，每批都要人去点，用 app-verification skill 补上，之后每批的交付和独立验证都照同一种方式跑；并发、重试、锁与租约、状态机、解析器这类核心出错代价高，坏掉的那种交错又很少被测试或一次运行撞上，用 formal-verification skill 给它一个形式化检查，比加验证轮次或升档更能兜住。