A useful Codex prompt does not need to be long. It needs to remove the ambiguity that would change the result: what outcome you want, which evidence matters, what must stay untouched, and how you will decide the work is complete.
OpenAI’s current prompting documentation frames a larger task around four useful elements—goal, context, output, and boundaries—and recommends telling Codex how to verify a code change. This guide turns that advice into a compact workflow you can reuse for bug fixes, small features, tests, documentation, and read-only investigation.
Start with the outcome, not a script
Tell Codex what should be true at the end. Avoid prescribing every search, file read, or edit unless that exact process is a requirement.
Weak:
Open the components folder, inspect every button, edit some files, and improve accessibility.
Stronger:
Add an accessible name to the icon-only account menu button. Preserve its visual appearance and existing click behavior. Run the smallest relevant accessibility and component tests, then report the files changed and any checks you could not run.
The stronger version identifies one observable outcome. It also prevents a narrow task from quietly expanding into a site-wide audit.
Add only context that can change the answer
Useful context points Codex toward authority. Depending on the task, that may include:
- the exact error and reliable reproduction steps;
- the route, component, function, or test that is in scope;
- the project rules or design system that must be followed;
- an existing implementation that should be used as the pattern;
- the command or user flow that demonstrates success.
Do not paste an entire repository into the message. In the IDE, open or attach the most relevant files. In the CLI, name paths explicitly when they matter. If you do not know the right file, describe the behavior and ask Codex to locate the implementation before editing.
For an unfamiliar codebase, a safe first message is read-only:
Locate the code that renders the billing empty state. Do not modify files.
Explain the request flow, list the files you inspected, and identify the
smallest likely change point. Mark assumptions separately from facts found
in the repository.Define scope and boundaries
Boundaries matter when an otherwise plausible action would create risk or extra work. Use them for real constraints, not as a wall of repeated warnings.
Common boundaries include:
- keep the public API and stored data shape unchanged;
- preserve existing user changes and do not rewrite unrelated files;
- do not add dependencies, migrate data, deploy, or send messages;
- do not expose secrets, personal records, or production data;
- stop and ask before an action that is destructive or externally visible.
Be precise. “Do not change anything else” can be unrealistic when a test fixture or locale must change with the implementation. “Keep the change within the account-menu component and its existing tests” gives Codex a boundary it can apply.
Make completion verifiable
“Fix it” does not define done. A strong prompt names observable behavior and relevant evidence.
Use this pattern:
Done when:
- the reported behavior no longer reproduces;
- only necessary implementation and test files change;
- the regression test fails before the fix and passes after it;
- the relevant lint, type, and test commands have actually run;
- the final report separates passed, failed, and not-run checks.Ask for checks that the project really provides. Codex should discover commands from AGENTS.md, README.md, package scripts, CI configuration, or other project files instead of inventing them. A check that did not run may be an honest limitation; it must not be described as passed.
Use a five-part prompt template
For most coding tasks, the following structure is enough:
Outcome: [Describe the observable result.]
Context: [Name the relevant behavior, files, source of truth, or repro steps.]
Scope: [State what may change and what should stay outside the task.]
Constraints: [Preserve compatibility, user changes, security, or design rules.]
Verification: [Name the behavior and project checks that provide evidence.]You do not need every heading for a one-line change. Keep the smallest version that still makes the work reviewable.
Adapt the template to the task
Bug fix prompt
Fix the settings issue where Save reports success but the notification toggle
returns to its previous value after refresh.
Reproduce it using the existing local setup before editing. Keep the API shape
and persistence format unchanged. Add a focused regression test if the current
test structure supports one. Re-run the reproduction and the smallest relevant
test suite, then report the cause, changed files, and exact check results.Small feature prompt
Add a keyboard shortcut that opens the existing search dialog.
Reuse the current dialog and shortcut conventions. Do not add a second search
implementation or a new dependency. Preserve typing behavior inside form fields.
Update the relevant help text and tests. Verify keyboard access, focus placement,
and the existing close behavior.Read-only review prompt
Review the uncommitted changes for correctness, regressions, security issues,
and missing tests. Do not edit files. Prioritize findings by impact, cite the
affected file and line, explain the failure scenario, and say when no issue is
supported by the diff.Read-only language is important when you want analysis rather than a second round of edits.
Improve a weak prompt in one pass
Before sending a task, ask five questions:
- Can I state the expected behavior in one sentence?
- Did I identify the evidence or files that could change the answer?
- Is the allowed scope clear enough to notice unrelated work?
- Are the important compatibility, safety, or approval boundaries explicit?
- Can I verify completion without trusting a summary alone?
If one answer is “no,” add that missing detail. If all five are clear, more prose may only add noise.
After Codex responds, steer with specific corrections rather than restarting with a much larger prompt. For example: “Keep the existing translation keys, remove the unrelated refactor, and rerun only the component test.” This preserves useful context while narrowing the result.
Avoid common prompt mistakes
- Vague success: “Make it better” does not identify what should improve.
- No source of truth: A model may choose a pattern that conflicts with project rules.
- Unlimited scope: “Fix all related issues” makes review and rollback difficult.
- Process overload: Prescribing every trivial step can obscure the real requirement.
- Invented validation: Naming commands that do not exist creates false confidence.
- Conflicting instructions: Asking for a minimal patch and a broad refactor at the same time leaves the priority unclear.
- Trusting the final summary: Evidence comes from the diff, command output, and observed behavior, not confident wording.
For a complete beginner workflow, continue with the Codex getting-started guide. To turn verification into a repeatable review, use the guide to reviewing Codex changes. Repository-wide conventions belong in a maintained AGENTS.md file, not in every task prompt.
Frequently asked questions
Does every Codex prompt need the full template?
No. A tiny, well-understood change may need only an outcome and one constraint. Use more structure when ambiguity, risk, scope, or verification becomes important.
Should I tell Codex exactly which files to edit?
Name files when they are authoritative or when the scope is known. If you are unsure, describe the behavior and ask Codex to locate the implementation first. Incorrect file instructions can be worse than a short discovery step.
Should I ask Codex to plan first?
Planning is useful for unfamiliar, multi-file, or high-impact work. It is usually unnecessary for a trivial copy edit. Review the plan before editing when the approach itself carries risk.
Can I reuse one prompt for every repository?
Reuse the structure, not blindly copied constraints. Commands, architecture, permissions, and definitions of done should come from the current project.