How to Prompt Codex for a Verifiable Bug Fix

A good Codex bug-fix prompt gives the coding agent a reproducible failure, a clear boundary for the change, and a way to prove the result. Before you begin, make sure you can run the project’s relevant tests or reproduce the bug yourself; otherwise, Codex may produce a plausible patch that you cannot confidently verify.

What You’ll Need

• A local checkout of the repository, with the project’s documented setup completed.
• A reliable description of the bug, including the expected and actual behavior.
• A reproduction case: steps, input, command, test, or error output that makes the problem observable.
• A way to check the affected area, such as a test command, lint command, build, or manual verification procedure.
• A clean or understood working tree. Check existing changes before asking Codex to edit files.

Step-by-Step

1. Confirm the failure before writing the prompt. Run the relevant command or follow the same steps that expose the bug. Record the exact input and result, and note whether the failure happens every time. If it is intermittent, include the frequency and conditions you have observed rather than presenting it as deterministic.
2. Describe expected versus actual behavior. State what should happen and what happens instead. Be concrete: “Submitting an empty search should show the existing validation message” is more useful than “search is broken.” Include relevant error text, but remove secrets, personal data, and unrelated log noise.
3. Give Codex the smallest useful reproduction. Include a failing test name, a short sequence of steps, a sample input, or a command and its output. If you do not yet have a test, say how you reproduced the issue and ask Codex to identify a focused regression test before changing implementation code. Do not invent a test result you have not observed.
4. Set the scope and constraints. Name the affected feature or files if known, and say what must remain unchanged. For example, ask for a minimal fix that preserves the public API and existing behavior for valid inputs. Mention relevant project conventions, supported environments, or compatibility requirements. Avoid prescribing a specific implementation unless you know it is necessary.
5. Ask for diagnosis before broad edits. A useful prompt asks Codex to inspect the relevant code, explain the likely cause briefly, and then make the smallest change that addresses it. Tell it not to refactor unrelated areas, add dependencies, or silence a failing check just to make the run appear successful.
6. Define verification up front. Specify the checks you expect: the targeted regression test, nearby tests, and any relevant lint or build command. Ask Codex to report the exact commands it ran and whether each passed. If a command cannot run because a dependency or service is unavailable, ask it to say so rather than imply success.
7. Use a structured prompt. Put the facts in a compact order so the problem is easy to evaluate. For example:
   Bug: [one-sentence summary].
Reproduction: [exact steps, input, or command].
Expected: [observable correct result].
Actual: [observable failure and relevant output].
Scope: Fix this behavior with a minimal change; preserve [constraint]. Do not change unrelated behavior or add dependencies.
Verification: Add or update a focused regression test. Run [targeted test command] and [other relevant check]. Report the commands and results, and flag anything you could not run.
8. Review the proposed change yourself. Read the diff and check that it fixes the stated cause rather than masking symptoms. Look for unrelated edits, weakened assertions, skipped tests, broad exception handling, changed interfaces, and generated files that should not be included. Run the verification commands in your own environment when possible.
9. Check the original reproduction again. After the tests pass, repeat the same input or steps that initially failed. Confirm both that the bug is gone and that an ordinary valid case still works. A passing test suite is useful evidence, but it may not cover the exact conditions you reported.

Common Mistakes

• Reporting a symptom without a reproduction: “It crashes sometimes” gives little basis for a reliable fix. Add the smallest repeatable case you can find.
• Combining several bugs: Separate unrelated failures into separate prompts or clearly label each one. Otherwise, it is hard to tell which change addresses which behavior.
• Demanding a particular patch too early: A proposed solution can distract from the actual cause. Describe the required behavior and constraints first, then let the agent inspect the code.
• Asking it to make all tests pass without context: This can encourage unrelated changes or weakened tests. Identify the relevant checks and require an explanation for failures outside the target.
• Accepting a claim of success without evidence: “Fixed” is not verification. Ask which commands ran, inspect their results, and independently rerun important checks.
• Sharing sensitive material: Remove credentials, private customer data, and secret configuration from prompts and logs. A minimal sanitized reproduction is usually enough.

Tips

• Include the project’s existing test command or point Codex to the relevant documentation rather than assuming it knows how the repository is configured.
• When the bug is hard to reproduce, describe what you tried, what changed between successful and failed runs, and what evidence would narrow down the cause.
• Ask for a regression test that fails before the fix and passes after it. If the project cannot easily express the scenario in a test, request a precise manual check instead.
• Keep the requested change small. A focused diff is easier to review and makes it clearer whether the original issue was addressed.
• Use a separate branch or commit your current work before handing over edits, especially if your working tree already contains changes.
• Do not treat a green test run as proof of every requirement. Match the checks to the reported failure and inspect edge cases that matter to the feature.

Troubleshooting

Codex cannot reproduce the bug: Verify that you supplied the same command, input, environment assumptions, and setup steps you used. Check that the repository is on the correct branch and that required services or fixtures are available. If the failure is intermittent, ask for instrumentation or a focused diagnostic step before requesting a speculative fix.

The tests pass, but the bug remains: The test may not represent the original conditions. Repeat your exact reproduction, compare it with the new test, and update the prompt with the difference. Ask Codex to explain why the existing test did not catch the behavior.

A test fails for an unrelated reason: Keep the output and distinguish pre-existing failures from failures introduced by the patch. Ask for the targeted test to be run separately, and do not ask Codex to delete, skip, or loosen unrelated tests. Confirm the baseline on the unmodified code if that is practical.

The patch is larger than expected: Review the diff and ask Codex to narrow it to the necessary files and behavior. If the broader change is genuinely required, have it explain why and identify the extra verification needed.

A command cannot run: Check the project instructions, installed dependencies, environment variables, and required services. Ask Codex to list the exact blocker and provide a manual check or alternative command only if the alternative tests the same behavior. Treat an unrun check as unverified.

Frequently Asked Questions

Should I ask Codex to write a test before fixing the bug?
Usually, yes. A focused regression test makes the expected behavior explicit and helps show that the fix addresses the original failure.

What if I do not know which file is responsible?
Describe the reproduction and observed behavior without guessing. Ask Codex to trace the relevant code, identify the likely cause, and keep the eventual change focused.

How many verification commands should I include?
Start with the narrowest test that covers the bug, then add nearby tests and a build or lint check when relevant. Prefer a few meaningful checks to an unexplained list.

Can I trust Codex’s report that the tests passed?
Use it as a summary, not a substitute for evidence. Review the reported output, inspect the diff, and rerun the important commands in your own environment when possible.

What should I do if the fix changes other behavior?
Point to the specific regression and provide a reproduction. Ask for a smaller change that preserves the stated constraint, then verify both the original bug and the affected existing behavior.

Related

• Best iPads for Christmas: Picks for Every Budget
• Cybersecurity’s Future: What It Means for People and Business
• 700 TOPS for On-Device AI: What It Really Means