Debugging Workflows with Claude Code

Claude Code debugging works best when you treat the tool as a systematic investigator, not a magic fix button. The core workflow is: reproduce the bug in a way Claude can observe, let it form and test hypotheses one at a time, and verify the fix against the actual failure, not just against a passing test suite. This article walks through the mechanics, from writing the first prompt to setting up hooks and subagents that make debugging sessions repeatable instead of ad hoc.

Most engineers who try Claude Code for debugging start by pasting a stack trace and asking "fix this." That works for shallow bugs. It falls apart on anything with a non-obvious root cause: race conditions, stale caches, environment drift, or bugs that only reproduce under specific data. This guide covers the workflow that holds up for both cases.

Why naive debugging prompts fail

When you give an AI coding assistant a vague prompt like "the login page is broken, fix it," you are asking it to guess at three things simultaneously: what "broken" means, how to reproduce it, and what the correct behavior should be. Claude Code will usually produce a plausible-looking patch, but plausible is not the same as correct. The model pattern-matches against common causes of login bugs (session expiry, cookie flags, CORS) and picks the one that best fits the vague description. If the actual cause is a race condition in a token refresh handler, that patch does nothing except add noise to your diff.

The fix is to separate observation from hypothesis from verification, the same discipline you'd use debugging manually. Claude Code is a fast, tireless research assistant for the first and third steps. It is only as good as the evidence you hand it for the second.

Step 1: give Claude Code a reproduction, not a description

Before opening a session, get the bug into a form Claude can run and observe directly. This is the single highest-leverage thing you can do for claude code debugging, and it's the step most people skip.

Concretely, that means one of:

• A failing test case (npm test -- --grep "login flow" or equivalent)
• A curl command that reproduces a bad API response
• A script that triggers the crash with a fixed seed or fixture
• Console/network output from the browser, captured and pasted in

If you don't have a reproduction yet, say so explicitly and ask Claude Code to help you build one before touching any fix code. A prompt like this works well:

The checkout flow throws "Cannot read properties of undefined (reading 'total')"
intermittently, maybe 1 in 20 attempts. I don't have a reliable repro yet.
Help me instrument the checkout handler so the next occurrence logs enough
context to diagnose it, then I'll paste the logs back.

This produces targeted logging instead of a guessed fix, and it keeps the session honest about what is actually known versus assumed.

Step 2: let Claude Code work in small, falsifiable steps

Once you have a reproduction, resist the urge to ask for "the fix" in one shot. Structure the session as a loop:

1. State the current hypothesis
2. Ask Claude Code to find the smallest piece of evidence that would confirm or rule it out
3. Run that check
4. Update or discard the hypothesis based on real output

This mirrors the superpowers:systematic-debugging pattern and it matters because Claude Code, like any LLM-driven agent, is prone to confirmation bias in long sessions: once it commits to a theory, it will keep proposing patches around that theory even when new evidence contradicts it. Forcing an explicit hypothesis-then-falsify loop breaks that pattern.

A concrete example. Suppose a background job silently stops processing records after a deploy. A bad prompt:

The worker queue stopped processing jobs after the last deploy, fix it.

A better prompt:

Background worker jobs stop processing about 10 minutes after startup,
no errors in the logs. Before proposing a fix: read the worker's
main loop and list every place it could exit or block silently
(uncaught promise rejection, exhausted connection pool, an await
with no timeout). Rank them by likelihood given "works for 10 minutes
then stops." Don't touch any code yet.

This gets you a ranked list of hypotheses grounded in the actual code, which you can then test one at a time: add a timeout, check pool metrics, add an unhandled-rejection handler. Each check either confirms a cause or eliminates it, and the session stays anchored to evidence.

Step 3: use `git bisect` style narrowing for regressions

If the bug is a regression (it worked before, broke recently), don't ask Claude Code to guess the cause from the current diff. Give it the commit range and let it narrow the search:

This test passed on commit a1b2c3 and fails on HEAD. Run
git log --oneline a1b2c3..HEAD to list the candidate commits,
then help me bisect: check out the midpoint, run the test, report
pass/fail, and narrow from there.

Claude Code can drive a manual bisect loop reliably because each step has a hard, checkable answer (test passes or it doesn't). This is far more reliable than asking it to read a 40-commit diff and "spot what broke it."

Step 4: verify against the original failure, not just the test suite

A patch that makes a test suite green is not the same as a patch that fixes the bug. This distinction matters more with AI-generated fixes than with hand-written ones, because an agent under pressure to "make it pass" has an easy escape hatch: loosen the assertion, mock away the failing path, or catch and swallow the exception that was the actual signal.

Always close the loop by re-running the original reproduction, not just the automated tests:

Before we call this done: run the original curl command that reproduced
the 500 error, and confirm the response is now correct, not just that
the unit tests pass.

If you're using Claude Code's verify skill or an equivalent project script, this step is exactly what it's for: exercising the actual runtime behavior the change is supposed to fix, rather than trusting a green checkmark.

Using hooks to catch regressions automatically

Claude Code supports hooks (configured in settings.json) that run shell commands at points in the session lifecycle, such as after a file edit or before a session ends. For debugging workflows, two hooks pay for themselves quickly:

Post-edit lint/typecheck. Run your linter or type checker after every edit so syntax or type errors surface immediately instead of after a dozen more edits have piled on top.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx tsc --noEmit" }
        ]
      }
    ]
  }
}

Pre-stop test run. Before Claude Code considers a task finished, run the relevant test file so a regression can't slip through because the session ended one message too early.

Hooks matter for debugging specifically because they remove the temptation to "eyeball" whether a fix is safe. The check runs every time, automatically, whether or not you remember to ask for it.

When to use subagents for debugging

Claude Code's subagent feature (via the Task/Agent tool, or the Explore agent in this environment) is useful when a bug spans more surface area than fits comfortably in one context window. Two patterns come up often:

Parallel investigation. If a bug could be in the frontend, the API layer, or the database query, and you're not sure which, dispatch one read-only investigation per layer in parallel rather than serially reading through all three yourself. Each subagent returns a short report; you synthesize.

Isolated review after a fix. Once a fix is in place, a fresh subagent with no memory of the debugging session can review the diff with an outside perspective, the same value a human code reviewer provides by not having anchored on the same wrong theory you did. This catches cases where the "fix" is a workaround rather than a root-cause correction.

Don't reach for subagents on a bug that's already narrowed to one file. The overhead of spinning up a parallel agent and reconciling its findings costs more than just reading the file yourself.

Common failure modes and how to avoid them

The model fixes the symptom, not the cause. This shows up as try/catch blocks added around the failing line, null checks that mask an upstream bug instead of preventing it, or a widened type that makes a type error disappear without addressing why the wrong type showed up. Counter this by asking explicitly: "before writing the fix, explain why this value could be null/undefined here in the first place." If Claude Code can't answer that, the patch it's about to write is a symptom fix.

Long sessions drift from the original bug. After 30+ tool calls, context can drift, and the session starts optimizing for "make the current error go away" rather than "fix the bug I described." Periodically restate the original symptom and reproduction command to keep the session anchored, or start a fresh session once the investigation phase is done and hand the confirmed root cause to a clean context for the fix.

Flaky reproductions get "fixed" by removing the flake, not the bug. If a test is intermittent, there's real pressure to just add a retry or increase a timeout. That can be the right call for genuinely environmental flakiness, but for a race condition, it just makes the bug rarer and harder to catch next time. Ask directly: "is this flakiness caused by a real race condition in the code, or by test environment timing? Show me the evidence either way."

Debugging production issues without production-shaped data. A bug that only shows up with real user data (large payloads, unusual unicode, specific locale settings) often won't reproduce with a small hand-written fixture. When you're stuck, ask Claude Code to help you build a fixture generator that matches the shape of production data (with any sensitive fields redacted or synthetic) rather than continuing to guess with toy inputs.

A working session template

For a nontrivial bug, this is a reliable prompt sequence:

1. "Here is the bug: <description + exact reproduction command/steps>.
   Do not write any fix code yet. Read the relevant files and list
   your top 3 hypotheses for the root cause, ranked by likelihood."

2. "For hypothesis #1, what's the smallest check that would confirm
   or rule it out? Run it."

3. [repeat step 2 for remaining hypotheses until one is confirmed]

4. "Now write the minimal fix for the confirmed root cause. Don't
   touch unrelated code."

5. "Re-run the original reproduction from step 1 and confirm the
   actual behavior is correct, then run the full test suite."

This template is slower than "just fix it" for trivial bugs, and that's fine, use your judgment and skip straight to a fix when the cause is obvious. But for anything that's already resisted a quick fix, the structure pays for itself by preventing the two most expensive failure modes: a patch that doesn't actually fix the bug, and a patch that fixes the bug today but reintroduces it in three months because nobody understood why it happened.

FAQ

Does Claude Code remember previous debugging sessions? Not by default. Each new session starts with a clean context unless you explicitly carry information forward, for example by writing findings to a file, a project CLAUDE.md, or a memory file the tool reads at session start. For a bug that spans multiple sessions, write down the confirmed root cause and ruled-out hypotheses before ending the session so you don't repeat the same investigation.

Should I let Claude Code run destructive commands while debugging, like resetting a database? Only with explicit, narrow permission, and generally not without a backup or a disposable environment. Debugging sessions often involve running scripts you haven't fully vetted; treat any command that mutates state (database writes, force pushes, deleting files) as something to review before it runs, not something to blanket-approve for the session.

How is this different from just using autocomplete-style AI suggestions in my editor? Autocomplete tools suggest the next few lines based on local context. A debugging workflow with an agentic tool like Claude Code involves multi-step reasoning: reading multiple files, running commands, checking their output, and revising a hypothesis, closer to how a human debugs than to line completion. The workflow described here (reproduce, hypothesize, falsify, verify) doesn't map onto single-suggestion autocomplete at all.

What's the fastest way to get a bad debugging session back on track? Stop, and restate the original bug and reproduction command in a fresh message, explicitly noting what's been ruled out so far. If the session has drifted through many unrelated edits, it's often faster to git diff to see what actually changed, discard anything that doesn't map to a confirmed hypothesis, and restart the investigation loop from a clean state rather than layering another fix on top.

Can Claude Code debug issues that only happen in production, not locally? Indirectly. It can't observe your production environment on its own, so you need to bring the evidence: logs, error tracking output, network traces, or a minimal script that reproduces the same conditions (data shape, concurrency, config). Once you hand it that evidence, the same hypothesize-and-falsify loop applies. Treat "reproduce it" as its own subtask if you don't have a reliable repro yet.

Is it worth writing a custom hook just for debugging, or is that overkill for a one-off bug? For a one-off bug, skip it and just ask directly for the checks you want after each edit. Hooks earn their keep when you're debugging repeatedly in the same codebase, a lint-and-typecheck hook after every edit, or a test run before the session ends, saves more time over a week of sessions than it costs to set up once.