codex-construction

codex-construction — write a good brief, then let go

Treat Codex as a top-tier engineer: explain clearly why it's being done, what the result should look like, what matters most, how good it needs to be, and what taste is wanted, then let go. The main agent is also a top-tier engineer; this document only gives it principles and CLI facts that the model cannot infer.

Principles

• There are only two kinds of hard rules: the boundaries of irreversible actions (red lines), and the CLI-tested facts that startup, monitoring, and continuation depend on (including the end marker in the run conventions). Follow these two kinds.
• Everything else is judgment: how long the brief is, how to split batches, which tier to dispatch, how many rounds of review, when to cut losses — the main agent decides; how to design, implement, verify, and split commits — Codex decides. The specific practices in this document are all references.
• Loosen how it's done, write clearly what to do: the clearer the goal, scope, and completion conditions, the more you can let go.
• Constrain with reasons, not prohibitions: write the deviations you're worried about (such as over-engineering) as "explain why it's worth it", not as "don't".
• The user's explicit requirements take precedence over this skill.

Division of labor

• Main agent: fully grasp the goal, write the brief, split batches, dispatch work, accept the work, and hold on to decisions that need the user to make the call.
• Codex: design, implementation, and reversible trade-offs within a batch.
• If it messes up, re-dispatch with feedback; do not take over midway: taking over would make acceptance lose its independent reference.

Writing the brief

Like assigning a task to a top-tier colleague who wasn't in the earlier discussions: explain the goal and the bar clearly, without prescribing the approach. A good brief covers the five things below; they are a checklist, not a form, and the length follows the task — a few sentences are enough for fixing a small bug.

1. Background: what project, why it's being done, what value it brings to whom once done, and where things stand (repo path, branch, prior commits, design doc path). Explain the motivation clearly, and it can infer constraints that weren't written. The design doc should state the goal, the decisions and constraints already settled with the user, and not the implementation steps, so as not to use up Codex's design space in advance.
2. Deliverable: which behaviors can be verified, and under what data or scenarios they hold. These are the completion conditions.
3. Focus: the one or two things that really matter in this batch, what the user cares about most, where mistakes are most likely, and what this batch does not do. If everything is important, then nothing is.
4. Quality and resources: write the bar as a perceptible standard, for example "good enough that you'd be willing to sign your name to it"; authorize all means needed to reach the bar — reading any code, running local commands, refactoring the code involved in this batch, iterating repeatedly. Submitted tests should only guard places that will truly break, with scale referenced to neighboring tests; for reversible, low-impact changes, do not write tests that mirror the implementation. Give known good tools, ready-made data, similar implementations, and known pitfalls in the tone of "I think X is enough"; if it has a better way, use its way.
5. Style and taste: like the code this repo already had, favoring deletion and simplicity; point to one or two well-written files as references. New abstractions, config options, or compatibility layers may be introduced, but explain clearly why they're worth it; if you can't explain it clearly, it's usually over-engineering.

Fixed ending

• Red lines: Only write irreversible actions, expressed as concrete actions (push, deploy, production database, paid API). If none, write "none".
• Running conventions: Copy the following passage verbatim into the construction brief, replacing N with the batch number. Do not additionally require a plan first: a single-turn session ends once the plan is delivered.

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

Pre-dispatch self-check: Can someone who was not involved in the discussion, reading only this brief, state why it is being done, what counts as done well, what matters most, and what kind of code counts as tasteful? If not, supplement the brief. Whatever cannot be supplemented—usually priorities and taste—is in the user's head; ask the user first, do not make it up for them.

Example(medium-scale construction; running conventions omitted)

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

Tier

effort is the reasoning budget given to Codex; use the three tiers medium / high / xhigh : the more judgments to be made and the harder errors are to roll back, the more it should be given. When the user names a tier or model, follow the user's.

Reference: routine construction medium; design, investigating unknown root causes, review high; architecture finalization, money/concurrency/security cores, final-state adversarial review xhigh. Redispatch usually goes up one tier; retrying at the same tier mostly repeats the same mistake; the review tier is generally no lower than the construction tier.

Startup

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=$!"

• The model name is based on the local ~/.codex/config.toml ; to change the name, first use the codex exec -m <名字> "打印 ok" probe; 400 means invalid.
• Pass effort explicitly: omitting it silently falls back to the config default tier.
• The brief goes through stdin（- < FILE: putting it in argv exposes it to ps, and Codex may mistake its own process for another session and switch to monitoring instead of starting work.
• exec cannot be omitted: with it, $! is codex itself, and killing the process actually kills codex.
• --dangerously-bypass-approvals-and-sandbox grants full permissions and sets no approval; both exec and resume accept it; boundaries rely only on the red lines.
• -o LAST.md writes the final message separately to disk, named independently per batch; it must not already exist before startup.
• The startup call only dispatches in the background and returns immediately; the outer tool timeout will SIGKILL by process group, andnohup cannot stop it.
• After startup, look at the RUN.log header: note session id: for resumption, verify reasoning effort:。

Monitoring

Normally use kill -0 <pid> to check liveness; do not judge completion from the log; only look at the log when it seems stuck. After the process exits, look at LAST.md：

Final state	Judgment	Action
Complete	LAST.md last line STAGE N DONE or REVIEW DONE	Acceptance
Pending decision or blocked	LAST.md last line BLOCKED[批N]:	Resume after decision or unblocking
No delivery	Has LAST.md, no marker	Read it to determine the nature, resume to close it out or redispatch
Quota exhausted	No LAST.md，RUN.log tail ERROR: You've hit your usage limit … try again at HH:MM，exit 1	Resume when due: if there is progress, resume; if zero progress, rerun; not a failure, do not raise the tier
Crash	No LAST.md, log has no errors, stopped midway	Mostly killed by the outer group; resume or rerun

• Do not grep for the marker in RUN.log : when Codex starts it echoes the brief verbatim, and the marker text will match at the beginning.
• Repeatedly targeting codex's own pid in the logs kill -0 / ps, zero git commits, is a self-monitoring deadlock, kill and re-dispatch; it waiting on test or build subprocesses it started itself doesn't count.
• The process is alive but the logs have no new output for a long time, it may be stuck, judge in light of the task size;codex exec after BLOCKED it will necessarily exit, it won't sit there waiting.
• During construction don't run gates, switch branches, or modify files in the same worktree, it will interfere with its changes.

Acceptance

Accept against the brief, don't just look at "did it run":

• Delivery: the main agent personally runs the key gates and scenarios, actual results are authoritative.
• Focus: whether what the user cares about most was actually done, whether it got squeezed out by secondary work, whether the scope was quietly narrowed.
• Quality and taste: read the diff. For new abstractions, config options, compatibility layers, check whether the justification holds; tests that mirror the implementation don't count as coverage; code that doesn't look like this repo's needs to be changed.
• Independent judgment and incidental fixes: verify item by item. For incidental fixes you don't approve of, revert the corresponding commit; for judgments you disagree with, give reasons, not just swap in your own preference.
• If it doesn't pass, write specific feedback: if the problem is located, resume to fix; if the direction is wrong, change the brief and re-dispatch.

Batch

• A batch is a work package that can be independently accepted; how big to cut it is judged by the main agent: the bigger the batch, the more room Codex has to work; the smaller the batch, the easier the acceptance and the cheaper the rollback.
• Serialize within the same worktree, concurrent writes will overwrite each other; to parallelize, use separate worktrees, and the file sets must not overlap.

Change-review loop

ReviewUse a fresh session, only without construction context can you see problems the construction didn't think of. The review brief likewise covers five things: what this batch did, and why; a delivery problem list (severity, location, reproduction method); the risks most worth digging into; whether to report only problems you're sure of or cover as much as possible. The ending doesn't use the construction run conventions, replace with: unattended, review only don't change (don't modify files, don't commit), the final message is the problem list, write on the last line separately REVIEW DONE. You can switch models or switch agents for cross-review.

Fix roundContinue the original construction session:

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

• Use an explicit session id, don't use --last：--last only searches in the current cwd, if not found it will silently open a new empty session (exit 0, no warning). session id is valid across cwd.
• effort and permission flags are re-passed each time, resume doesn't inherit them.
• After resume, verify the log header session id: matches the original session.
• Long fix rounds are likewise started in the background per the startup section. For continuation use the bare CLI,/codex:* the plugin can't see sessions started by bare invocation.

How many review rounds depends on risk: reversible changes close out after one clean round; changes touching irreversible assets are reviewed until no new problems surface. If fixes don't converge for a long time or fixing A breaks B, it means the brief or the plan has a problem—rewriting the brief is more effective than adding rounds.