Prompting Codex effectively

Decomposition, precise scope, pointing at the file to copy, asking for a plan before code, and iterating with follow-ups rather than restating.

A task with a boundary

Weak:    "improve the checkout flow"

Better:  "Add a 10-minute reservation timer to the checkout page.
          - new component: src/components/ReservationTimer.tsx, following the
            pattern in src/components/CountdownBanner.tsx
          - show remaining time, switch to an expired state at zero
          - do not change the payment code or the API contract
          - add tests in src/components/__tests__/ReservationTimer.test.tsx
          - done when npm test passes and the component renders in Storybook"

Name the artefact, not the aspiration. "Add cursor pagination to the orders endpoint" is a task; "make the API better" is a wish.
Always name a file to copy the pattern from. A concrete example in the repository is worth more than a paragraph of description.
State what must not change. Without it, the agent resolves any ambiguity in whatever direction is easiest for the change it is making.
Define done as a command. If no command can decide whether the task is complete, the agent is guessing and so are you.

Plan first, then implement

# 1. ask for a plan and nothing else
codex --sandbox read-only "Read src/billing/ and propose how to add proration to
  plan upgrades. List the files you would change, the new functions, and the
  tests you would add. Do not write any code yet."

# 2. correct the plan in a follow-up rather than restarting
#    "Do not introduce a new decorator; extend the existing PlanChange model."

# 3. only then authorise the implementation, quoting the plan
codex "Implement the plan we agreed, exactly: modify src/billing/plan_change.py
  and src/billing/proration.py, add tests/test_proration.py. Stop when
  pytest tests/test_proration.py passes. Change nothing else."

Phase	Sandbox	What you are checking
Explore	read-only	Did it find the right files and understand the domain?
Plan	read-only	Is the approach one you would accept in review?
Implement	workspace-write	Does the diff match the plan and nothing more?
Verify	workspace-write	Do the tests pass, and do they fail if the change is reverted?

A plan is cheap to correct and a diff is expensive. Reviewing five lines of proposed approach catches the wrong abstraction before it is written in forty files.
Quote the plan back in the implementation prompt. It anchors the run and reduces drift, particularly on a long task.
Ask for the smallest version that proves the change. A working single-case implementation teaches you more about the agent's understanding than a comprehensive one.

Iterating well

Follow up with the specific thing that is wrong: "the cursor must be opaque and stable across deploys" beats "that is not right".
Do not restate the whole task. Repeating the brief makes the agent reconsider decisions you already accepted and often undoes work.
Point at the evidence: paste the test failure, name the file and line, quote the error. An agent with the real error message converges much faster than one asked to guess.
When a run goes wrong twice on the same point, stop and change the environment: add the rule to AGENTS.md, add the missing test, or narrow the task. A third attempt in the same conditions rarely helps.
Use the conversation to accumulate constraints, not to re-explain. The best multi-turn runs read like a code review rather than a series of fresh briefs.

Good follow-ups, in order:

"pytest fails: TypeError: plan_change() got an unexpected keyword argument
 'effective_from' at src/billing/plan_change.py:88. Fix that call site only."

"Keep the public signature of PlanChange unchanged; the upgrade path relies on it."

"Good. Now add the test for the downgrade case to the same file, then stop."

💡

The most reliable prompt is a repository that already contains the answer. If you have to explain a convention three times, encode it once: a small example file, a lint rule, or a line in AGENTS.md is more durable than another sentence in a chat.

FAQ

Should I ask for a plan every time?

For anything touching more than a couple of files or involving a design decision, yes. For a mechanical edit with an obvious shape, the plan step is overhead and the diff is quicker to review.

What do I do when it will not stop refactoring?

State a hard boundary: list the files it may modify and say explicitly that everything else is out of scope. Then verify with git diff --stat that only those files moved.

Using Codex in a real workflow Reviewing, applying and reverting changes

Last refreshed 2026-09-18.

Prompting Codex effectively

A task with a boundary

Plan first, then implement

Iterating well

FAQ

Related