Direct answer
A prompt does not need to be long. It needs enough clarity about scope, constraints, evidence and decision boundaries for Codex to stay on course.
What this guide helps you solve
Improve the Codex CLI prompt and split complex coding tasks
Define a task contract with five elements
A reliable engineering prompt describes the target behavior, current evidence, allowed scope, mandatory constraints and verification method. Stopping conditions matter too: require Codex to ask before resolving protocol ambiguity, changing dependencies or performing destructive operations.
Do not present an unproven implementation as a requirement. Reproduction steps and user-observable behavior let Codex investigate the existing design before choosing an implementation that fits the repository.
- Goal: Which user behavior or engineering outcome needs to change.
- Evidence: bugs, failed tests, logs, or related files.
- Scope: Modules that are allowed to be modified and those that are explicitly prohibited from modification.
- Constraints: compatibility, dependencies, performance, security and coding conventions.
- Verification: Commands that must run and criteria that determine success.
Separate exploration from implementation
Use the read-only sandbox first when the root cause is unknown. Codex is required to locate the entry point, track the data flow, reproduce the problem and list candidate solutions, and then start the writable session after confirming the plan.
This split will not guarantee that the plan is correct, but it will allow humans to detect scope miscalculations, protocol violations, and missing information before files are changed.
codex -C /path/to/repo -s read-only "复现 issue 中的超时问题，追踪从入口到网络请求的数据流，说明根因和两种修复方案。列出会修改的文件及验证命令，不要改文件。"codex -C /path/to/repo -s workspace-write -a on-request "按已确认的最小方案实现。先补回归测试，只改计划列出的文件；运行相关测试和静态检查，失败时修复根因，不要跳过检查。"Split complex tasks by decision boundaries
Do not split work mechanically into a "front half" and "back half." A more reliable sequence is to establish facts, confirm contracts, complete the smallest vertical path, cover failure paths, verify and review. Each stage needs its own deliverable and exit criteria.
Pause when a step requires the user to select an API, database migration, or new dependency. Don’t let the model make irreversible decisions for the business owner.
- 01Establish factsLocate existing entry points, call chains, tests, and constraints without modifying files.
- 02Confirm the contractDefine inputs, outputs, error behavior, and compatibility boundaries.
- 03Minimal implementationComplete an end-to-end path and add corresponding tests.
- 04Cover boundariesHandle failures, cancellations, timeouts, permissions, and rollbacks.
- 05Independent reviewRun the full set of necessary checks and review the final diff.
Provide navigation clues instead of dumping context
Clarifying file paths, symbol names, reproduction commands and existing examples can reduce irrelevant file reading. Don't paste the entire log or code base at once; keep the minimum reproduction first and then allow Codex to read it on demand.
The long-term repository facts are placed in AGENTS.md, the special process is placed in Skill, and the acceptance criteria of the current task are placed in prompt. Cramming everything into one prompt adds conflict and drains context.
问题：`src/auth/session.ts` 在 token 刚过期时返回 500，而接口契约要求 401。
复现：运行 `<targeted-test-command>`。
参考：错误映射模式见 `src/api/errors.ts`。
范围：只改 auth 模块与对应测试，不改公共响应结构。
验证：目标测试、auth 测试组、类型检查。
断点：如果必须修改共享错误协议，先说明影响并等待确认。Write verification into the same task
“Tell me when you fix it” leaves quality judgment to natural language summarization. Better prompts specify the checks that Codex can run, and ask for the command, exit status, and parts that remain unverified.
Provide comparable screenshots for interface tasks, fixed input and output for data conversion, and stress or race testing for concurrency issues. The clearer the verification signal, the more autonomously the agent can iterate.
codex -C /path/to/repo "修复目标失败。完成后运行最窄测试、相关模块测试和 git diff --check；若检查失败，继续修复直到通过或遇到需要我决策的阻塞。最终列出每条命令及结果，不要声称未运行的检查已通过。"Use short feedback to correct deviations in time
Stop expanding the scope immediately when deviations are detected, point out specific nonconformities and restate constraints. Do not add multiple new requirements in a row on the wrong solution.
After the task, move recurring repository facts into AGENTS.md, but do not make a temporary choice permanent without review. Effective prompts improve through corrections grounded in real failures.
- Indicate which observation or hypothesis is wrong.
- Request to return to the last verified state.
- Redefine file and interface boundaries.
- Re-enter read-only investigation if necessary.
Official sources and verification scope
This guide is based on public official documentation. Commands and configuration may change between client versions, so verify the linked sources before use.
Read the verification methodology