Debug with AI, step by step.

To debug code with AI, give the agent a bug it can reproduce and the evidence around it, then ask for ranked hypotheses instead of a fix. Test one hypothesis at a time, fix the cause once the evidence points to it, and keep the failing test as a regression test.

The method matters more than the model. Ask an agent to “fix this error” and it will often make the error disappear without fixing what caused it. The five steps below turn debugging from a guessing game into a search.

01Why debugging code with AI goes wrong

An agent sees only what you show it and what it chooses to read. With a vague report, it fills the gaps with plausible guesses, and plausible is exactly what makes a wrong fix hard to spot. Developers feel this:

The fix is not to trust less. It is to make the agent work like a good debugger: from a reproduction, with evidence, one change at a time.

02Step 1: Reproduce the bug

A bug you cannot trigger on demand is a bug you cannot prove fixed. Before anyone changes code, get a reproduction the agent can run, ideally a failing test.

Before fixing anything, reproduce this bug: [what happens, the steps, and what should happen instead].
Write the smallest failing test or script that shows it, run it, and show me the failure.
If you cannot reproduce it, tell me what information you need. Do not guess at a fix.

Keep the reproduction small. A test that calls one function with one bad input beats a script that clicks through the whole app. If the bug only appears in production, start from the logs and try to rebuild the exact input locally. A wrong number with no error at all is often a bad SQL query; see our guide to writing SQL with AI for the classic traps.

03Step 2: Hand over the evidence

The agent can read your code, but it cannot see your screen, your production logs or your memory of what changed last week. Paste those in.

A few commands answer “what changed” quickly, and the agent can run them itself:

# Recent commits, and what changed since the last good release
git log --oneline -15
git diff v2.3.0 --stat

# Dependency changes hide in the lockfile
git diff v2.3.0 -- package-lock.json | head -50

04Step 3: Test one hypothesis at a time

This is where agents need the firmest hand. Ask for hypotheses, not a fix:

Here is the failing test and the evidence: [paste].
List up to three hypotheses for the root cause, most likely first. For each, give the evidence for and against it, and the cheapest check that would confirm or rule it out: a log line, an assertion or a small test.
Run the check for the first hypothesis only, then report back before changing any code.

When the evidence is thin, add some. Ask the agent to log the values that matter for the failing input, and to mark each temporary line with a tag such as DEBUG so they are easy to remove later.

Change one thing per run. If the agent edits three files and the bug disappears, you do not know which change fixed it, or what else the other two broke.

When an answer sounds certain, ask where it comes from. Models state guesses and facts in the same confident tone, which our guide on why AI makes things up explains.

05Step 4: Bisect when an older version worked

If the bug is new, the fastest route to the cause is often the commit that introduced it. git bisect runs a binary search through your history, so even a thousand commits take about ten tests. It is one of several git commands worth knowing well; our guide to git for beginners covers eight of them.

Point it at a known bad and a known good version, then let your reproduction test do the judging:

# Mark the bad version (HEAD) and the last known good one
git bisect start HEAD v2.3.0

# Test each midpoint automatically with the reproduction test
git bisect run npx vitest run tests/checkout-total.test.ts

# When it names the first bad commit, go back to where you started
git bisect reset

Two details make this work. Leave the new test uncommitted, so it stays in place while bisect checks out older commits. And know the exit codes: 0 means good, 125 means skip this commit because it cannot be tested, and most other failures mean bad.

Once bisect names the commit, give its diff to the agent. “Here is the commit that broke it” is the strongest evidence you can hand over.

06Step 5: Fix the cause and keep the test

With the cause confirmed, the fix is usually small. Ask for it in a way that rules out the common shortcuts:

The cause is confirmed: [cause].
Fix the cause, not the symptom. Do not add a try and catch that hides the error, do not weaken any check, and do not edit the failing test.
Keep the reproduction as a regression test. Run the full test suite and show me the result, then remove every temporary DEBUG line.

Then check the test itself. It should fail on the old code and pass on the new code. A regression test that passes either way proves nothing. Our guide to test-driven development with AI shows how to lock tests so an agent cannot quietly edit them.

07Traps: confident guesses and shotgun fixes

Bad AI debugging sessions tend to fall into a few recognizable traps. Each one has a simple counter.

The last one deserves emphasis. After two failed corrections, a long thread works against you. Write down what you know and what you ruled out, then start clean. The copyable prompts in our prompts for coding agents are a good starting point.

08FAQ

Next, learn to spot almost-right code in review, or set up an AI pair programming workflow that catches bugs before they ship.