AI Debugging Prompt: Make Your Agent Start From a Failing Test

TL;DR: A reliable AI debugging prompt gives a coding agent the command that reproduces the bug, has it write a test that fails for the same reason, and stops there so you can check the test. Then you freeze that test, let the agent fix the cause, and accept the fix only when the new test and the full suite pass with the output shown.
Paste a bug description into a coding agent and you'll usually get a confident patch back. Sometimes it fixes the bug. Sometimes it fixes something nearby, or adds a guard that hides the symptom, and you find out later. What often decides it is whether the agent had a way to tell that the bug was gone.
This how-to is for agentic coding sessions where the agent can run your tests: one workflow, one prompt to copy, and the checks that catch a fix that only looks right.
Why a description isn't enough
An agent stops when the work looks finished. Claude Code's documentation puts it plainly: "Claude stops when the work looks done. If it has nothing to run that tells it whether the work actually is done, 'looks done' is all it has to go on. In practice that makes you the test suite" (Claude Code best practices).
A bug report in prose has no pass or fail in it. The agent forms a theory, edits code to match it, and reports success. If the theory was wrong, nothing in the session says so.
The same docs give a before and after that is the whole idea of this article. Instead of "fix the login bug", they suggest: "users report login fails after the session times out. look at token refresh in src/auth/, write a failing test that reproduces it, then fix it." The second prompt names the symptom and the place to look, and it defines "fixed" as a test going from red to green.
SWE-bench judges a fix the same way. The benchmark, built from real GitHub issues, keeps only task instances with "at least one test where its status changes from a fail to pass," and counts a task as solved only "if all tests across FAIL_TO_PASS and PASS_TO_PASS pass," meaning the new tests now pass and the old ones still do (Jimenez et al., arXiv 2310.06770). Our SWE-bench paper digest covers the benchmark in more detail. You can hold your own agent to that same standard.
The workflow, step by step
1. Get a reproduction you can run
Before the agent touches code, you need a command that shows the bug. Claude Code's own bug-fixing tips are to "Tell Claude the command to reproduce the issue and get a stack trace," "Mention any steps to reproduce the error," and "Let Claude know if the error is intermittent or consistent" (Common workflows). Paste the real error output instead of a summary.
If you can't reproduce it yet, make finding a reproduction the first task, with no code changes.
2. Have the agent write the failing test, then stop
Ask for one test that reproduces the bug through the code's public interface, run it, show you the failure, and stop. It's the step people skip, and it's the one that catches a wrong test.
Check two things. First, the test should fail on an assertion that describes the bug, such as "expected a refund of 40.00, got 0.00." A test that fails on an import error, a typo or a missing fixture proves nothing about the bug. Second, it should express what the code is supposed to do, so it would still be right after a fix. Our guide to test generation prompts that produce tests worth keeping covers how to keep tests from mirroring the code they test.
In pytest, running just that test looks like this (pytest usage docs):
pytest tests/test_refunds.py::test_refund_after_partial_capture
3. Freeze the test
Once you agree the test is right, commit it on its own. Now any later change to it shows up in git diff, and the agent's job is narrow: make that test pass without changing it. Say so in the prompt. Agents do take the shortcut of changing the test: the ImpossibleBench paper found that an agent with access to unit tests "may delete failing tests rather than fix the underlying bug," and it documents cases of agents editing the tests. A separate commit makes any change to the test easy to spot.
4. Find the cause, then make the smallest fix
Ask the agent to state the root cause before it edits anything, because a stated cause is something you can disagree with. Then ask for the smallest change that fixes it. A large rewrite inside a bug fix mixes two kinds of change and makes review harder.
5. Prove it with output
Run the new test, then the whole suite. The new test going green is the fail-to-pass half. The full suite staying green is the pass-to-pass half, and it's what tells you the fix didn't break something else.
Ask for the commands and their output. The Claude Code docs make the same point: "ask Claude for evidence: the command it ran and its output," because "'All tests pass' on its own tells you very little." Our piece on gating completion on disk evidence goes further with this for long-running agents.
The prompt
Bug: <what happens, and what should happen instead>.
Reproduce with: <exact command>
Output:
<paste the real error and stack trace>
Work in this order, and stop after step 2 so I can check the test.
1. Find where this behavior comes from. Tell me which files and
functions are involved before you change anything.
2. Write one test that reproduces the bug through the public
interface. Run it. Show me the command and the failure output.
It must fail on an assertion that matches the bug, not on an
import error, a typo or a missing fixture.
After I confirm the test:
3. Do not edit, skip, or loosen that test.
4. State the root cause in one or two sentences, then make the
smallest change that fixes it.
5. Run the new test, then the full suite with <suite command>.
Show both commands and their output.
6. If you can't make the test pass without changing it, stop and
explain why instead of working around it.
Why this works: The reproduction command and real output give the agent facts instead of your interpretation. The stop after step 2 puts a person between "I think I understand the bug" and "I changed the code," which is where a wrong theory is cheapest to catch. Steps 3 and 6 close the easy exits, and step 5 asks for evidence you can read in seconds.
Keep the test commands where the agent always sees them: Claude Code's docs suggest keeping "the exact test, typecheck, and lint commands, and how to run a single test file" in CLAUDE.md. For agents that read an AGENTS.md file, the same lines belong there, and our AGENTS.md linter checks the file.
When you don't know which change caused it
If the bug is a regression, git can find the commit for you with the failing test. git bisect run runs a command at each step and reads its exit code. The git docs say the command "should exit with code 0 if the current source code is good/old, and exit with a code between 1 and 127 (inclusive), except 125, if the current source code is bad/new," and that 125 "should be used when the current source code cannot be tested," which skips that revision (git-bisect).
pytest exits with 1 when tests fail and with 2 to 5 for other problems, including 5 when "No tests were collected" (pytest exit codes). Map those other codes to 125 so an untestable commit is skipped instead of being marked bad:
git bisect start
git bisect bad
git bisect good v1.4.0
git bisect run sh -c 'pytest tests/test_refund_regression.py; rc=$?; if [ "$rc" -le 1 ]; then exit "$rc"; else exit 125; fi'
git bisect reset
Put the regression test in its own new file and run this before you commit it. Git leaves an untracked file in place as it checks out older commits, so every step runs the same test. If you've already committed it, copy the test to a new untracked file first. Then hand the agent the commit bisect found, along with the test, so it starts from a small diff.
When the agent goes in circles
If you've corrected the agent twice and it's still wrong, stop correcting. The Claude Code docs advise "after two failed corrections run /clear and write a better prompt instead of a third," because a third correction adds to a conversation that "already contains two failed attempts for Claude to keep re-reading." Start the new session with the frozen test and what you learned, such as "the cause is not in the cache layer."
The same docs suggest raising effort "when getting it right depends on cases that are quick to overlook," and the examples they give include "a bug in code you didn't write" and "a flaky test."
What to check in the diff before you accept it
Even with a passing test, read the change. Look for:
- Any change to the frozen test, a new skip marker, or a looser assertion.
- A broad exception handler that catches the error instead of fixing what raises it.
- A special case for the exact input in the test.
- Unrelated edits that came along with the fix.
For a second reader, a reviewer in a fresh session sees the diff without the reasoning behind it. Our article on agentic code review prompts has prompts for that step. For more, see the Development pillar.
Frequently asked questions
How do I use AI to debug code?
Give the agent the exact command that reproduces the bug and the real error output, then ask it to write a test that fails for the same reason before it changes any code. Check that test, keep it fixed, and accept a fix only when that test and the full suite pass with the output shown.
What is the best prompt for debugging with AI?
One that includes the reproduction command, the actual error and stack trace, what should happen instead, and a definition of done that the agent can run. Asking the agent to stop after writing the failing test, so you can check it, catches a wrong theory before any code changes.
Why should the test fail before the fix?
A test that fails first and passes after the change shows the change fixed the behavior the test describes. A test written after the fix may only confirm the new code does what it does. SWE-bench uses the same fail-to-pass rule to decide whether a model resolved an issue.
What if the bug can't be captured in a unit test?
Use any check that comes back pass or fail. Claude Code's docs list a build's exit code, a linter, a script that diffs output against a fixture, and a browser screenshot next to the mockup as checks an agent can run.
Can an AI agent find which commit introduced a bug?
Yes, with git bisect run and a failing test. Git checks out commits between a known good and a known bad version, runs your test at each commit it picks, and uses the exit code to narrow down the first bad commit.
Terms in this article
From the library
Rather have someone set it up for you?
That's a fair call. LTFI, the agentic business operating system from Kief Studio, can set up the work these guides describe and run it with you. No website yet? Kief Studio will build you one for free.

