Claude Code Debugging Workflow
Claude Code's biggest debugging advantage isn't just answering questions — it's that it reads the full codebase before answering. It can trace a bug through 10 files in seconds, correlate a stack trace with the actual source, and suggest a root cause with the relevant code excerpts already in context. This page covers the prompts and workflows that get the most out of it.
The Core Debug Prompt
The single most effective debugging prompt gives Claude four things: the error, the trigger, the expected behavior, and a repro step.
Here is the error:
[paste full error + stack trace]
This happens when [one sentence of what triggers it, e.g., "a user submits the checkout form with a coupon code applied"].
I expected [what should happen, e.g., "the order to be created and the user redirected to /orders/:id"].
Reproduce it by running [exact command or test name, e.g., "npm test -- --testNamePattern='creates order with coupon'"].
Don't ask Claude to guess — give it what you know. The repro step is the most important part: if Claude can run the test, it will verify its fix before handing it back.
Stack Trace Debugging
Always paste the full stack trace, not just the top frame. Claude needs the originating call site to identify the root cause. Then let Claude read the files before asking for a fix.
# In Claude Code chat:
Here's the error from our production logs:
AttributeError: 'NoneType' object has no attribute 'stripe_customer_id'
File "src/services/billing_service.py", line 47, in charge_subscription
customer_id = user.stripe_customer_id
File "src/workers/billing_jobs.py", line 23, in process_renewal
result = billing_service.charge_subscription(user_id)
File "src/workers/billing_jobs.py", line 12, in run
self.process_renewal(job["user_id"])
This happens when the nightly billing job runs.
The job should charge all users with active subscriptions.
Can you find why user is None and fix it?
Claude will read billing_service.py, billing_jobs.py, and the user model to find where the lookup can return None, then propose a targeted fix.
Test Failure Debugging
Consistent test failure
This test is failing. Run it with pytest tests/test_auth.py::test_login_invalid_password -v and fix whatever is wrong. Don't change the test — the test is correct, something in the implementation is wrong.
The instruction "don't change the test" is load-bearing — without it, Claude might take the easy path of weakening the assertion.
Flaky test
This test fails intermittently. I've seen two failures: [paste output A] and [paste output B]. It passes about 70% of the time. Here's the test: [paste code]. Find the root cause and make it deterministic.
Common flaky test root causes Claude identifies quickly:
| Root cause | Signal |
|---|---|
| Shared mutable state | Passes in isolation, fails in suite |
| Time-dependent assertion | Fails near midnight or on slow CI |
| Async race condition | Failure is non-deterministic even on same machine |
| Port conflict | Fails when other tests run in parallel |
| File system ordering | Depends on os.listdir() or glob order |
Performance Debugging
Slow endpoint
GET /api/dashboard is taking 8 seconds for users with more than 500 orders. P99 in prod is 12s. Find the N+1 query or missing index. Start by looking at the route handler and the ORM queries it triggers.
Claude will trace through the route handler → service → repository layer, identify every database call, spot N+1 patterns, and suggest query optimizations with the exact Prisma/SQLAlchemy/ActiveRecord change.
Memory leak
Our Node.js worker process grows from 80 MB to 800 MB over 6 hours before crashing. It processes jobs from a Redis queue in a loop. Here is the job processor: [paste file]. Find what's accumulating and not being freed.
Production Incident Debugging
For production incidents where you have logs but need to find root cause fast:
# Paste log lines + context Here are 30 minutes of logs around the incident (2026-05-17 14:22 UTC). The symptom was: all checkout requests returned 500 for ~8 minutes. The incident resolved without a deploy — possibly a transient DB issue. [paste relevant log lines] Questions: 1. What was the root cause? 2. Is this likely to recur? 3. What should we add to prevent or detect this faster next time?
Debugging Workflow: Step by Step
- Give Claude the full error — paste the complete stack trace, not just the message
- Add one-sentence context — what were you doing when it happened?
- Give a repro step — a test name, a curl command, or exact UI steps
- Let Claude read first — don't immediately ask for a fix; let it read the relevant files
- Ask for a hypothesis before a patch — "what do you think the root cause is?" before "fix it"
- Verify the fix runs your tests — ask Claude to run the full test suite before accepting
What Claude Code Can't Debug
Claude Code has limits. Know when to reach for other tools:
- Runtime state inspection — Claude can't watch variable values as code executes; use pdb/gdb/Chrome DevTools
- Hardware/driver issues — GPU memory errors, kernel panics, network packet loss
- Bugs that only appear with real user data — Claude can analyze patterns but can't access prod data
- Heisenberg bugs — issues that disappear when you add logging or slow down execution
FAQ
How do I paste a stack trace into Claude Code?
Just paste the full stack trace directly into the Claude Code chat. Don't truncate it — Claude needs the full trace to identify the originating call, not just the top frame. Prepend with one sentence of context: what you were doing when the error happened.
What is the best prompt for debugging with Claude Code?
The most effective debugging prompt is: "Here is the error: [full error + stack trace]. This happens when [trigger]. I expected [expected behavior]. Reproduce it by running [exact command or test name]." Give Claude the error, the context, the expected behavior, and a repro step.
Can Claude Code debug production issues from logs?
Yes. Paste relevant log lines with 10–20 lines of context before and after the error. Include the request or event that triggered it. Claude will cross-reference with the source code to identify what state led to the error. For recurring issues, also include a count or timeline of occurrences.
How do I debug a flaky test with Claude Code?
Show Claude the test code, the two different failure modes you've seen, and the test output from at least two runs. Say explicitly: "This test fails intermittently — sometimes [error A], sometimes [error B]." Common root causes are shared mutable state, time-dependent assertions, and async race conditions.
Should I use Claude Code or a debugger for debugging?
Use both in order. Start with Claude Code to form a hypothesis about the root cause — it can cross-reference multiple files and identify patterns faster than a debugger. Then use a debugger to verify the hypothesis at runtime. Claude Code is especially useful for bugs spanning multiple files or involving subtle data issues.