Guides

A systematic debugging workflow with Claude Code

Claude Code will happily start editing the moment you describe a bug. Left unchecked, that's shotgun debugging with extra steps: change a plausible-looking line, rerun, repeat. Forcing a few named phases — reproduce, hypothesize, bisect — gets you to a real fix instead of an edit that happens to make the symptom go away.

1. Lock in a reproduction first

Don't paste a stack trace and ask for a fix. Ask Claude to reproduce the failure itself, and to say why it fails, before it touches any code:

Before proposing any fix:
1. Run `npm test -- path/to/spec` (or the exact command I give you) and paste
   the actual failure output.
2. Confirm you can reproduce it, not just read the trace I pasted.
3. Don't edit any files yet.

Enforce this structurally with plan mode, where Claude can read files and run read-only commands but can't edit until you approve a plan: press Shift+Tab mid-session until the status bar shows ⏸ plan mode on, or start with claude --permission-mode plan.

2. Turn the bug into a failing test

Write a test that reproduces this bug and fails for the actual bug, not for
some unrelated reason (typo, missing fixture). Do not write the fix yet.
Show me the test failing, and why.

This is the same loop as test-driven development with Claude Code, started from a bug report instead of a spec. You get a regression test for free once the fix lands.

3. Force ranked hypotheses, not a first guess

List every plausible cause for this failure, ranked by likelihood. For each,
name the single cheapest check (a log line, an existing test, git blame on
the relevant lines) that would confirm or rule it out — before changing any
implementation code. Run the cheapest checks first.

This is what stops an agent under pressure to "just fix it" from editing the first line that looks suspicious and hoping.

4. Bisect with git when it's a regression

git bisect start
git bisect bad                            # current commit is broken
git bisect good v1.4.0                    # last known-good tag or commit
git bisect run npm test -- path/to/spec   # your repro from step 2
git bisect reset

git bisect run needs a command that exits non-zero on a bad commit and zero on a good one; your repro test works directly, or ask Claude to write a wrapper if setup steps are needed first. If the bug only reproduces in a specific environment, run the bisect inside a worktree so your main checkout stays on a working commit.

5. Delegate competing hypotheses to subagents

Testing three hypotheses one at a time burns your main context on the dead ends. Delegate each to a subagent so only the verdict comes back:

Use subagents in parallel to investigate three hypotheses:
1. the race is in the connection pool
2. it's a stale cache read
3. the retry logic double-submits
Each should report back with evidence (file:line, a repro, or a failing
test) — not a guess. Don't let them edit files.

See the subagents guide for scoping tools so an investigating subagent can read and run commands but can't edit.

6. Recover safely when a fix attempt is wrong

Double-tap Esc with an empty prompt, or run /rewind, to open the checkpoint menu and restore code, conversation, or both to an earlier point. It's faster than asking Claude to undo its own edits by hand.

One gap matters here specifically: checkpoints only track edits made through Claude's own file-editing tools. If testing a hypothesis meant Claude ran a destructive Bash command — rm, a migration, an in-place mv — rewind won't restore it. Commit or stash first, per the git workflow guide, before letting Claude run anything destructive while chasing a hypothesis.

Block edits until the repro is confirmed

To enforce step 1 with something stronger than a polite ask, a PreToolUse hook on Edit|Write can refuse edits until your repro script has actually run and failed:

#!/usr/bin/env python3
# PreToolUse, matcher "Edit|Write"
import os, sys
if not os.path.exists(".claude/repro-confirmed"):
    print("Blocked: run the repro command and confirm the failure first.",
          file=sys.stderr)
    sys.exit(2)

Have your repro command touch .claude/repro-confirmed on a real failure, and delete it at the start of each debugging session. Build and test a rule set like this with the free hook builder, or see more patterns in hook examples.

Common mistakes

• Skipping the reproduction. A fix for a bug Claude never actually triggered is a guess with confident formatting.
• One hypothesis, no ranking. If Claude proposes a single cause, ask what else it would explain the symptom and how to tell them apart.
• Letting "confirmed" mean "compiles." A fix is confirmed when the failing test from step 2 goes green, not when the edit looks plausible.
• Losing the repro test. Keep it in the commit even after the fix works — it's the regression test that stops the bug coming back.