Writing better tasks for Codex

Who this is for

This is for developers who already have Codex set up and want better results from each task. By the end you can write a bug-fix prompt with a reproduction recipe, a review prompt, and a plan-first prompt, and you know which Codex features to use for each.

What a useful Codex prompt contains

The docs describe a prompt as a question, an instruction or a goal. You start in your own words, read the response, and use follow-up messages to adjust it.^[1] For bigger tasks, a prompt can cover four parts: the goal, the context, the output and the boundaries. Use only the parts that help.^[1]

For Codex in particular, a useful prompt does four things. It names the behavior you want. It points to the relevant code or the reproduction steps. It keeps the important constraints. And it says how to verify the change.^[1] Describe the result rather than a list of steps, and describe a process only when the process itself matters.^[1]

Boundaries are the few instructions that stop extra work or unintended actions, such as keeping approved figures unchanged.^[1]

Give it the context it needs

In the IDE extension, your open files are included as context. In the CLI you have to name the paths yourself, with @ for path autocomplete or /mention to attach a specific file.^[1] In the IDE you can select the lines that matter and choose "Add to Codex Thread" from the command palette.^[1]

For tests, point Codex at a named function. For example, you can write: Add a test for the invert_list function in @transform.ts. Cover the happy path plus edge cases.^[1]

Plan first, then set a goal

For a multi-step task, type /plan in the app composer so Codex investigates and proposes an approach before it edits anything. When Goal mode is available, use /goal after the plan to set a persistent goal.^[1]

Codex runs local commands in a sandbox that limits file and network access. If a task has to cross that boundary, Codex follows your approval policy before it continues.^[1] Keep this in mind when you write the boundaries, so the prompt does not ask for something the approval policy will block.

A bug-fix prompt

The bug-fix workflow starts Codex at the repository root with codex, then gives a reproduction recipe and constraints. Here is an example prompt:^[1]

Bug: Clicking "Save" on the settings screen sometimes shows "Saved" but doesn't persist the change.
Repro:
1) Start the app: npm run dev
2) Go to /settings
3) Toggle "Enable alerts"
4) Click Save
5) Refresh the page: the toggle resets
Constraints:
- Do not change the API shape.
- Keep the fix minimal and add a regression test if feasible.
Start by reproducing the bug locally, then propose a patch and run checks.

The reproduction steps and constraints matter more than a high-level description. Codex adds the things it discovers itself: command output, call sites and any stack traces its runs produce.^[1] After the fix, ask Codex to run lint and the smallest relevant test suite, and to report the commands and results.^[1]

Steer or queue while Codex works

In the CLI, press Enter while Codex is working to steer the current turn. Use it to change direction or add a detail you forgot. Press Tab to queue the message for the next turn, for a follow-up that should wait until the current work finishes.^[1]

Review code before you commit

To review your working tree, run /review in the CLI. You can add focus instructions after it, such as edge cases and security issues.^[1] Apply the fixes, then run /review again to confirm that the issues are resolved.^[1]

On GitHub, enable Codex Code review on the repository first. After that, comment @codex review on a pull request. You can add focus areas, such as security vulnerabilities.^[1]

Explain code and update docs

To learn an unfamiliar service, ask Codex to summarize each module's responsibilities, say what data is validated and where, and list one or two gotchas to watch when changing it.^[1] For documentation, name the scope and the check you need, such as verifying that every link is valid. Review the draft and iterate.^[1]

A checklist before you send

Before you send a task, check these points:

• Have you stated the result? Describe what you want first, and describe steps only when the process matters.^[1]
• Is the relevant code named? In the CLI, use @ or /mention; in the IDE, open the files or select the lines.^[1]
• For a bug, did you give a reproduction recipe? Reproduction steps matter more than a general description.^[1]
• Are the constraints written down, such as keeping the API shape unchanged and keeping the fix minimal?^[1]
• Have you said how to verify it? Ask Codex to run checks and report the commands and results.^[1]

For a multi-step change, start with /plan so you can correct the direction before any code changes. Use Enter to steer the current turn and Tab to queue a message for the next one.^[1]

Next steps

The Codex prompting examples in the official docs cover more workflows, including screenshots and cloud delegation.^[1]