Debugging with AI: reproduce, isolate and fix bugs with an agent

Debugging with AI works best when a coding agent runs your normal debugging process for you: reproduce the bug, isolate it, test hypotheses, fix the cause and verify. This guide covers that workflow, how to feed errors, stack traces and logs, copyable prompts, and the failure patterns to avoid.

How does debugging with AI work?

Debugging with AI works by running the same scientific loop good engineers use (reproduce, isolate, hypothesize, test, fix, verify) with a coding agent doing the reading, searching and typing. The AI is fast at scanning code, reading long stack traces and generating hypotheses. You stay responsible for the evidence and the judgment.

Two setups exist, and they behave very differently:

Anthropic's best practices for Claude Code describe the core constraint: "Claude stops when the work looks done. Without a check it can run, 'looks done' is the only signal available." In debugging, the check is a command that reproduces the bug. With it, the agent can loop until the bug is gone. Without it, every suggestion is a guess you have to test yourself.

Step 1: Reproduce the bug before you ask for a fix

Reproduction is the most valuable thing you can give an AI debugger. A reliable command that fails turns a guessing game into a loop the agent can close by itself.

The official common workflows guide gives three tips for fixing bugs:

• Tell Claude the command to reproduce the issue and get a stack trace.
• Mention any steps to reproduce the error.
• Say whether the error is intermittent or consistent.

Good reproductions, from best to acceptable:

1. A failing unit or integration test.
2. A single command: npm test -- auth.spec.ts, pytest tests/test_billing.py -k refund, curl against a local server.
3. A short script that triggers the bug.
4. Written steps for a UI bug, plus a screenshot.

If you don't have a reproduction, make that the agent's first job:

Users report that login fails after their session times out.Don't fix anything yet. First, write a failing test that reproduces this:log in, expire the session token, then make an authenticated request.Run it and show me the failure output.

That is almost word for word one of the "after" examples in Anthropic's best practices: "write a failing test that reproduces the issue, then fix it." The failing test becomes the definition of done, and it stays in the suite as a regression test. Our guide to writing tests with AI goes deeper on tests that check real behavior.

Step 2: Give the AI the right evidence

Paste raw evidence, not your interpretation of it. A paraphrased error ("it says something about undefined") throws away the file names, line numbers and values the model needs.

What to include, in order of value:

Feeding logs without drowning the model

Large logs fill the context window and bury the signal. Filter first, then pipe:

grep "req_8f2a" app.log | tail -200 | claude -p "This request returned a 500. Explain the failure path and the most likely root cause."

Claude Code accepts piped input in non-interactive mode (claude -p), which the official docs use for exactly this kind of log analysis. Inside a session, reference files with @ (for example @logs/error.log) instead of pasting huge blocks.

For UI bugs, paste a screenshot of the error or the broken layout; Claude Code accepts images by drag and drop or paste. For live web apps, Claude Code can also connect to Chrome to inspect a running page, as listed in the Claude Code overview.

A bug report prompt you can reuse

When you hand a bug to an agent, a fixed structure keeps you from leaving out the parts that matter. Fill in this template and paste it as the first message of a fresh session:

Bug: [one sentence, expected vs actual]Reproduce: [command or failing test]Error output:[full error and stack trace]Recent changes: [commits, PR or dependency updates]Constraints: don't change public APIs; keep the diff small.First reproduce the failure and show me the output, then propose hypotheses.

The "first reproduce" line matters: it makes the agent confirm it sees the same failure you do before it starts reasoning about causes. If it can't reproduce, that is a finding in itself, usually pointing to an environment difference.

Step 3: Isolate and form hypotheses

Ask for hypotheses ranked by likelihood, each with a way to test it, before any code changes. This stops the most common failure: an agent that "fixes" the first plausible cause and moves on.

Here is the failing test output and stack trace: [paste]Before editing code:1. List the 3 most likely root causes, ranked, with the evidence for each.2. For each, describe a quick check that would confirm or rule it out   (a log line, a print, a narrower test, a git command).3. Run the checks, then tell me which hypothesis survived.

Useful isolation techniques to ask for:

• Add targeted logging. "Add temporary logs that print user.sessionId and token expiry at each step of the refresh flow, run the test, show me the output."
• Narrow the input. "Find the smallest input that still fails."
• Compare working and broken. "This works on main and fails on this branch; diff the relevant files and explain which change could cause it."
• Bisect the history. git bisect uses a binary search to find the commit that introduced a bug. With a reproduction script, the agent can run git bisect run ./repro.sh and report the culprit commit.

For a large codebase, investigation can fill the context window with file reads. Delegate it: "use a subagent to investigate how token refresh works and report back." Subagents explore in their own context and return a summary, which keeps the main session focused on the fix.

Step 4: Fix the root cause, not the symptom

A good fix explains why the bug happened and changes the code where the cause lives. A bad fix makes the error message go away.

Anthropic's best practices give a before-and-after for this exact case:

The build fails with this error: [paste error].Fix it and verify the build succeeds.Address the root cause, don't suppress the error.

Red flags in an AI-generated fix:

• A new try/catch or except Exception: pass around the failing code.
• @ts-ignore, # type: ignore, eslint-disable or any added to silence a checker.
• The test changed to expect the wrong behavior.
• A null check added far from where the null value comes from.
• Retries or sleeps added to hide a race condition.
• Changes in many unrelated files.

When you see one, push back with specifics: "This hides the error. Why is user null at this point? Find where it should have been set."

Step 5: Verify the fix and prevent regressions

Verify by rerunning the reproduction, then the related test suite, then asking what else the change could affect. Ask the agent for evidence (the command and its output), not a statement that it works.

A verification checklist to paste at the end of a debugging session:

Before we finish:1. Run the original reproduction and show the passing output.2. Run the tests for the affected module and show the summary.3. Remove the temporary logging you added.4. Explain the root cause in two sentences for the commit message.5. List any other code paths with the same pattern that could have the same bug.

Item 5 often finds the bug's siblings. The same missing null check or wrong date conversion tends to appear in several places.

Which bugs is AI bad at debugging?

AI is weakest where it can't observe the failure. Expect to do more of the work yourself for:

• Timing and concurrency bugs. Race conditions and deadlocks may not reproduce on demand. Use logging with timestamps, stress loops and profilers to capture evidence, then bring that to the AI.
• Production-only bugs. If the bug depends on production data, traffic or configuration, the agent needs a faithful reproduction or real logs and traces.
• Infrastructure and environment issues. DNS, permissions, cloud configuration and network policies are often outside the agent's reach. Our guide to AI for DevOps covers safer ways to involve agents there.
• Bugs in code the model can't see. Closed-source dependencies, generated code and external APIs. Point the agent at the docs or the API's response.
• Misleading stack traces. Models sometimes misattribute frames, especially in async code. Treat their reading as a hypothesis and check the frame yourself; see AI hallucinations for why confident explanations can be wrong.

Common mistakes when debugging with AI

Most failed AI debugging sessions share a few patterns, and each has a simple fix.

The "correct it again" trap is worth naming. The Claude Code docs note that after repeated corrections, "the context is cluttered with failed approaches," and recommend clearing and starting over with what you learned. A fresh session with a precise prompt usually beats a long one full of dead ends. More patterns like this are in our list of AI coding mistakes.

Some bugs take hours of running and rerunning: flaky tests, slow integration suites, a bisect across hundreds of commits. Those are good jobs to hand to an agent and walk away from, as long as it keeps running. Orkio gives Claude Code an always-on cloud box for that kind of long investigation, so it keeps going after you close your laptop and you review the fix as a pull request.

A debugging-with-AI checklist

Keep this next to your terminal:

1. Write down expected vs actual behavior in one sentence each.
2. Get a reproduction: a failing test or a single command.
3. Collect the full error, stack trace, command output and recent changes.
4. Ask for ranked hypotheses and checks before any edits.
5. Isolate with logging, smaller inputs, diffs or git bisect run.
6. Fix the root cause; reject suppressions and test edits.
7. Rerun the reproduction and the module's tests, and remove temporary logs.
8. Keep the failing test as a regression test and note the cause in the commit message.

Frequently asked questions