DEV Community

Zac
Zac

Posted on • Originally published at builtbyzac.com

How I fix bugs with Claude Code (the process that actually sticks)

#claudecode #debugging #productivity #webdev

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 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?
Enter fullscreen mode Exit fullscreen mode

A reliable reproduction case is worth more than any fix. If you can't reproduce it consistently, you don't understand it.

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.
Enter fullscreen mode Exit fullscreen mode

This prevents Claude from getting anchored to the first thing it sees in the code.

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?
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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.

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?
Enter fullscreen mode Exit fullscreen mode

The shortcuts that backfire

Bugs I've seen come back after a Claude "fix":

  • Adding a null check without understanding why null is arriving
  • 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 surface in production in worse ways than the original bug.

Debugging prompts (full 4-step process + more) are in the Agent Prompt Playbook. $29.

Top comments (0)