I used to dread production bugs. Not because they were always hard to fix, but because finding them felt like forensic archaeology. Grep through logs. Check git blame. Try to reconstruct what state the app was in when it broke. Two hours to find a three-line fix.
That changed when I started using Claude Code as an active debugging partner instead of just a code writer. The workflow I'll share here has cut my average time-to-diagnosis by more than half.
The Core Shift: Don't Ask Claude to Fix, Ask It to Understand
The biggest mistake I see developers make with AI-assisted debugging is jumping straight to "here's the error, fix it." This produces patches, not solutions.
What works better: make Claude understand the system first, then diagnose together.
The workflow has four phases:
- Orientation - get Claude up to speed on the relevant system
- Hypothesis generation - let Claude propose what could be wrong
- Evidence collection - gather data to test each hypothesis
- Root cause confirmation - confirm before fixing
This sounds obvious. Most people skip phases 1 and 2 entirely when they're under pressure.
The fastest path to a fix is a correct diagnosis. A correct diagnosis requires understanding the system. Don't skip orientation.
Phase 1: Orientation Without Overwhelming
The temptation when hitting a bug is to paste everything into Claude and ask it to find the problem. This works sometimes. More often, it produces generic suggestions that don't account for your specific system.
Better approach: orient Claude with three specific inputs.
Input 1: The error and immediate context
Here's the error that appeared in production:
[paste error + stack trace]
This happens in the order fulfillment flow, specifically when a customer
who has store credit tries to apply it to an order with a promotional discount.
Input 2: The relevant code path
Don't paste the whole codebase. Trace the execution path yourself first - what gets called when the error occurs? That's what Claude needs.
/read src/checkout/discount-calculator.js
/read src/checkout/credit-balance.js
/read src/models/order.js
Input 3: Recent changes
This is the one developers consistently forget, and it's often the most important.
git log --oneline -20 src/checkout/
Paste that output into the conversation. A recent change to the checkout directory is the first place to look.
Phase 2: Generating Hypotheses Before Collecting Evidence
Once Claude has the context, don't ask "what's wrong." Ask "what are the possible causes."
This distinction matters because it keeps you from anchoring on the first explanation that seems plausible.
I ask something like:
Based on this error and the code, what are the three most likely root causes?
Rank them by probability. Don't fix anything yet - I want to understand
the failure modes before we start looking at solutions.
A good response gives you a ranked list with reasoning. Something like:
- Race condition in credit balance check (probability: high) - the balance is read before the discount is applied, leading to stale state
- Integer vs float precision issue in the discount calculation (probability: medium) - the credit amount is stored as cents but the discount is calculated in dollars
- Missing null check for store credit when no active balance exists (probability: low) - stack trace shows the error before the null check would trigger
Once you have a hypothesis list, you have a debugging plan. Each hypothesis tells you exactly what evidence to collect.
Phase 3: Evidence Collection with Claude Code Tools
This is where Claude Code earns its place. The /run capability lets you execute diagnostic commands without switching contexts.
For the race condition hypothesis:
Can you write me a diagnostic script that:
1. Simulates the specific condition (store credit + promotional discount applied simultaneously)
2. Adds logging to show the exact state of the balance object at each step
3. Runs the scenario 50 times to see if the failure is intermittent
Claude writes the script. You run it. You feed the results back.
For the precision hypothesis:
/read src/utils/currency-helpers.js
Look at the divide and multiply operations. Are we consistently
working in cents or dollars throughout this flow? Show me every
type conversion.
The pattern: hypothesis generates a question, the question generates a search, the search generates evidence.
Don't move on until you've either confirmed or eliminated each hypothesis.
Phase 4: Root Cause Confirmation
Before writing a single line of fix code, I ask Claude to articulate the root cause in plain language.
Based on what we found, state the root cause in one clear sentence.
Then state what the correct behavior should be. Then state the minimal
change that would produce the correct behavior.
This forces clarity. If Claude can't state it clearly, you don't understand the problem well enough to fix it safely.
If the root cause is clear, you'll get something like:
"The store credit balance is read from the database before the promotional discount is calculated and applied, meaning the credit check sees the pre-discount total and authorizes an amount that will overdraw the balance when the discount reduces the final order value. The correct behavior is to calculate the final discounted total first, then validate the credit balance against that number. The minimal fix is to move the creditBalanceCheck() call to after applyDiscounts() in the checkout sequence."
That's a fix you can write with confidence.
Handling the "I Don't Know Where to Start" Problem
Sometimes the bug doesn't come with a clean stack trace. It's a behavioral issue - "orders placed on Tuesday afternoons sometimes show the wrong shipping estimate." No error. No obvious code path.
For these, I use Claude Code's grep tools for pattern discovery:
I need to find all the code paths that could affect shipping estimate calculation.
Start with /grep for "shipping_estimate" and "shippingEstimate" and "calculateShipping".
Build me a map of what calls what.
The output is a dependency graph of the feature. From there you can reason about where Tuesday-specific or time-specific logic might exist.
When you don't know where to start, start with grep. A dependency map of the broken feature almost always points to the problem area.
The Anti-Patterns That Kill Debug Sessions
Things I stopped doing that immediately improved my debugging speed:
Pasting enormous context and hoping. Claude can handle large contexts but large contexts dilute attention. Give the relevant code, not all the code.
Asking for a fix without a hypothesis. A fix without a diagnosis is a guess. Guesses require testing. A diagnosis requires confirmation. The diagnosis path is faster.
Accepting the first suggestion. Claude generates the most likely answer, not necessarily the correct one. Run the hypothesis through evidence before trusting it.
Not feeding results back. The debugging conversation is iterative. Each result changes what Claude knows. A one-shot prompt produces one-shot results.
The Repeatable Workflow
Here's the checklist I run through for every non-trivial bug:
- Collect: error + stack trace + recent git log for affected files
- Orient: read the relevant code path (not the whole codebase)
- Hypothesize: ask Claude for ranked root cause list before any fixing
- Plan: each hypothesis becomes a diagnostic question
- Evidence: use Claude Code tools to collect answers to each question
- Confirm: state root cause in one sentence before writing any fix
- Fix: minimal change that addresses confirmed root cause
- Verify: write a test that would have caught this
Step 8 is the one people skip. It's also the one that prevents you from debugging the same issue six months later.
Making This Stick
The workflow becomes natural after you use it five or six times. The hard part is using it when you're under pressure to fix something immediately.
My rule: if a bug has been open for more than 30 minutes and I don't have a confirmed root cause, I restart from step 1. Starting over feels slow. It's faster than continuing to debug without a theory.
Tools, templates, and a diagnostic prompt library for Claude Code debugging are at mynextools.com.
Drop your hardest debugging story in the comments - the bug that took forever to find and ended up being one line. I'll share mine if you share yours.
Follow me here for a new Claude Code deep-dive every week.