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 里的生产库。