The instinct when you hit a bug is to ask Claude "fix this." Sometimes it works. More often, Claude fixes the symptom and the real bug surfaces two days later in production.
Here's the debugging process that consistently produces fixes that actually stick.
Step 1: Reproduce before anything else
I have a bug. Before we look at code, help me write a minimal
reproduction case.
The bug: [describe what's happening]
Expected: [what should happen]
What's the minimum code or input needed to trigger this?A reliable reproduction case is worth more than any fix. If you can't reproduce it consistently, you don't understand it. And if you don't understand it, any fix is guesswork.
Step 2: Hypothesize before looking at code
Given this bug behavior, what are the three most likely root causes?
Don't look at the code yet — reason from the symptoms.This prevents Claude from getting anchored to the first thing it sees in the code. Forming hypotheses from symptoms first means you look at the code with specific questions rather than scrolling until something looks wrong.
Step 3: Check hypotheses against code
Here's the relevant code: [paste]
We hypothesized these causes: [list from step 2]
Which of these does the code actually support? What does the code
show that our hypotheses missed?Going from hypotheses to code, rather than code to hypotheses, means you're checking specific things instead of pattern-matching for anything that looks suspicious.
Step 4: Understand before fixing
Before you fix this, explain in plain English exactly what's
happening and why the bug occurs. If you can't explain it clearly,
we don't understand it well enough to fix it reliably.This is the step I skip when I'm in a hurry. It's also the step that, when skipped, leads to the bug coming back in a different form.
Step 5: Fix with constraints
Fix the bug. Constraints:
- Minimal change — don't refactor adjacent code
- Explain why this fix works
- What else could break from this change?
- What test would have caught this?The "what test would have caught this" question is retrospective but valuable. It often reveals that the fix is incomplete without a corresponding test change.
The shortcuts that backfire
Bugs I've seen come back after a Claude "fix":
- Adding a null check without understanding why null is arriving
- Swapping the order of operations without knowing why the original order was chosen
- Catching an exception without understanding what causes it
- Adding a retry loop to mask a timeout instead of fixing the timeout
All of these pass tests. All of them eventually surface in production in worse ways than the original bug.
When the bug is in someone else's code
Third-party library bugs get a different prompt:
This looks like a bug in [library]. Before I report it or work around it:
1. Is this documented behavior I'm misunderstanding?
2. Is there a known workaround?
3. Is there a version that fixes this?
4. If I need to work around it, what's the safest way?Claude knows a lot of library-specific quirks. Worth asking before assuming it's a bug in your code.
Debugging prompts, including the full 4-step process, are in the Agent Prompt Playbook. $29.