You’re Prompting Codex Wrong: OpenAI’s Official Guide to Better Coding Agents

“Fix the login bug” sounds actionable, but it leaves reproduction, change boundaries, compatibility constraints and acceptance tests unresolved. Codex must make product decisions before it can make code changes. A fluent patch can still solve the wrong problem.

OpenAI’s guidance points toward a simpler mental model: give the agent a bounded job and a way to prove it is finished. A strong Codex prompt resembles a concise engineering ticket plus acceptance criteria—not a collection of magic phrases.

Codex prompts are work orders, not chat questions

A chatbot can finish when it produces an answer. Codex operates a loop: inspect files, run tools, edit, observe, repair and verify. “Tell me the answer” therefore matters less than “change this repository and demonstrate the outcome.”

Do not prescribe every implementation detail. Let Codex inspect existing patterns and choose the narrowest defensible approach. Do specify the product behavior, protected boundaries and evidence that only you can define.

• Outcome: the observable user-facing change
• Scope: what may change and what must remain stable
• Evidence: tests, builds, screenshots or benchmarks
• Stop condition: what to report when permission or information is missing

The seven parts of a reliable Codex prompt

Start with an observable result. “Improve settings” is weaker than “keep the save button visible at 320px without changing the desktop layout.” Add reproduction context, scope and non-regression constraints.

Then add an exploration rule, verification surface and reporting format. You do not need seven headings for a one-line change. Include the decisions whose wrong answer would be expensive.

• Read relevant code and existing tests before editing
• Preserve unrelated user changes in a dirty worktree
• Run tests proportional to the change and investigate failures
• Report the change, evidence and remaining risk

Turn a vague request into an executable brief

“Search is slow; optimize it and keep going” provides neither a target nor a correctness constraint. An agent could cache stale data or reduce results and still claim success.

A measurable threshold, named benchmark, preserved API contract and bounded file area let Codex choose experiments while keeping completion objective.

Outcome: reduce product-search API p95 below 350 ms.
Scope: change only the search service and related tests; preserve the public response schema.
Explore: reproduce the benchmark and identify the bottleneck before editing.
Verify: run npm run benchmark:search and the related integration suite.
Report: explain the change, before/after numbers, tests run and remaining risks.

Describe tool triggers, not tool enthusiasm

“Search if needed” is weaker than “check official documentation before making version-sensitive API claims.” “Test it” is weaker than “run the changed package tests, then run the full type check if a shared type changed.” Trigger conditions make tool use predictable.

Autonomy also needs a safe operating boundary. Codex may freely repeat a local test suite built on disposable fixtures, while deployment, production data and billable external calls still require explicit authority. Persistence is not the same as unlimited permission.

Better models need less inherited scaffolding

OpenAI recommends revisiting accumulated plans, repeated checklists and defensive language when moving to newer Codex models. Old instructions can conflict: one tells the agent to implement immediately while another demands approval after every plan.

Put each instruction in the right layer. The current deliverable belongs in the task prompt; repository-wide rules belong in AGENTS.md; reusable procedures belong in Skills; a multi-turn finish line belongs in a Goal. That separation is the architecture of this six-guide cluster.

A reusable Codex task template

Treat this as a menu, not mandatory ceremony. A tiny edit may need only outcome and verification. Riskier work benefits from reproduction steps, explicit boundaries and a final evidence report.

Replace “works correctly” with an inspectable surface: a test name, URL, viewport screenshot or performance threshold. External evidence prevents the agent from grading its own prose.

[Outcome]
Describe the final observable behavior.

[Context / reproduction]
State the current behavior, error and relevant path.

[Scope / constraints]
Name allowed areas and behavior that must not regress.

[Workflow]
Inspect relevant code first, follow existing patterns, implement and test.

[Verification]
List tests, builds, benchmarks or manual checks.

[Final report]
Summarize changes, evidence and remaining risk.

Frequently asked questions