codex-construction

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

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

原则

• 硬规则只有两类：不可逆的动作边界（红线），以及启动、监控、续接依赖的 CLI 实测事实（含运行约定里的结尾标记）。这两类照做。
• 其余都是判断：简报多长、批怎么拆、派哪一档、审几轮、何时止损，主代理定；怎么设计、实现、验证、切 commit，Codex 定。文中的具体做法都是参考。
• 放开怎么做，写清做什么：目标、范围和完成条件越清楚，越能放手。
• 用理由约束，不用禁令约束：担心的偏差（例如过度工程）写成「说明为什么值得」，不写成「不许」。
• 用户的明确要求优先于本 skill。

分工

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

写简报

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

1. 背景：什么项目、为什么做、做成了对谁有什么价值、走到哪一步（仓库路径、分支、前序 commit、方案文档路径）。动机讲清楚，没写的约束它能自己推出来。方案文档写目标、已和用户敲定的决定与约束，不写实现步骤，免得提前用掉 Codex 的设计空间。
2. 交付：哪些行为可以被验证、在什么数据或场景下成立。这就是完成条件。
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 的列和格式一个字节都不能变——财务有脚本在解析它。这批不碰导入功能。

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

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

红线：不 push、不部署、不连 .env 里的生产库。

档位

effort 是给 Codex 的推理预算，用 medium / high / xhigh 三档：要做的判断越多、错了越难回滚，给得越足。用户点名档位或模型时按用户的。

参考：常规施工 medium；设计、排查未知根因、审查 high；架构定型、资金/并发/安全核心、最终态对抗审 xhigh。重派通常升一档，同档重试多半重犯同样的错；审查档一般不低于施工档。

启动

nohup bash -c 'exec 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 & echo "pid=$!"

• 模型名以本机 ~/.codex/config.toml 为准；换名先用 codex exec -m <名字> "打印 ok" 探针，400 即无效。
• effort 显式传：漏传会静默掉回 config 默认档。
• 简报走 stdin（- < FILE）：放在 argv 会暴露到 ps，Codex 可能把自己的进程误认成另一个会话，转去监控而不开工。
• exec 不能省：有它 $! 才是 codex 本身，杀进程才杀得到 codex。
• --dangerously-bypass-approvals-and-sandbox 给完整权限、不设审批，exec 和 resume 都收；边界只靠红线。
• -o LAST.md 把最终消息单独落盘，每批独立命名，启动前不得已存在。
• 启动调用只后台派工并立即返回；外层工具超时会按进程组 SIGKILL，nohup 挡不住。
• 启动后看 RUN.log 头部：记下 session id: 供续接，核对 reasoning effort:。

监控

平时用 kill -0 <pid> 判活，是否完成不从日志判；疑似卡住时再看日志。进程退出后看 LAST.md：

终态	判定	处置
完成	LAST.md 末行 STAGE N DONE 或 REVIEW 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 开跑会回显简报原文，标记字样会在开头命中。
• 日志里反复对 codex 自己的 pid kill -0 / ps、git 零 commit，是自我监控死锁，杀掉重派；它在等自己起的测试或构建子进程不算。
• 进程活着但日志长时间无新输出，可能卡死，结合任务规模判断；codex exec BLOCKED 后必然退出，不会停着等。
• 施工期间别在同一工作树跑门禁、切分支或改文件，会和它的改动互相干扰。

验收

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

• 交付：主代理亲自跑关键门禁和场景，以实际结果为准。
• 重点：用户最在意的事是否真的做到，有没有被次要工作挤掉，范围有没有被悄悄缩小。
• 质量与品味：读 diff。新抽象、配置项、兼容层看理由是否成立；镜像实现的测试不算覆盖；不像这个仓库的代码要改。
• 自主判断与顺手修复：逐条核实。不认可的顺手修复撤掉对应 commit；不同意的判断给出理由，而不只是换成自己的偏好。
• 不过就写具体反馈：问题已定位，resume 修复；方向错了，改简报重派。

批次

• 一批是一个可独立验收的工作包，切多大由主代理判断：批越大 Codex 发挥空间越大，批越小验收越容易、回滚越便宜。
• 同一工作树内串行，并发写会互相覆盖；要并行就用各自的 worktree，且文件集不相交。

改-审循环

审查用全新会话，不带施工上下文才看得出施工没想到的问题。审查简报同样覆盖五件事：这批做了什么、为什么；交付问题清单（严重度、位置、复现方式）；最该挖的风险；只报有把握的问题还是尽量覆盖。结尾不用施工的运行约定，换成：无人值守、只审不改（不改文件、不 commit）、最终消息是问题清单、末行单独写 REVIEW DONE。可以换模型或换 agent 交叉审。

修复轮续上原施工会话：

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

• 用显式 session id，不用 --last：--last 只在当前 cwd 找，找不到会静默新开空会话（exit 0、无警告）。session id 跨 cwd 有效。
• effort 和权限旗标每次重传，resume 不继承。
• resume 后核对日志头部 session id: 与原会话一致。
• 长修复轮同样按启动一节后台起。续接用裸 CLI，/codex:* 插件看不见裸调起的会话。

审几轮按风险定：可逆的改动一轮干净就收口，触及不可逆资产的审到不再冒出新问题。修复迟迟不收敛或修 A 破 B，说明简报或方案有问题——重写简报，比加轮次有效。