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 "Reproduce the timeout from the issue, trace the data flow from the entry point to the network request, and explain the root cause and two possible fixes. List the files that would change and the validation commands. Do not modify files."codex -C /path/to/repo -s workspace-write -a on-request "Implement the approved minimal fix. Add a regression test first and change only the planned files. Run relevant tests and static checks. Fix root causes when checks fail; do not skip checks."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. Do not 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. Do not 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.
Issue: `src/auth/session.ts` returns 500 immediately after a token expires; the API contract requires 401.
Reproduce: run `<targeted-test-command>`.
Reference: see the error-mapping pattern in `src/api/errors.ts`.
Scope: change only the auth module and its tests; keep the public response shape.
Validate: targeted test, auth test suite, and typecheck.
Decision point: if the shared error protocol must change, explain the impact and wait for approval.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 "Fix the target failure. Then run the narrowest relevant test, the related module tests, and git diff --check. Continue until checks pass or a decision is required. Report every command and result, and do not claim an unrun check passed."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.
View documentation scope