Skip to main content
Debugging

Debugging with Claude Code

Use Plan Mode, file references, and targeted prompts to diagnose and fix bugs efficiently.

Start in Plan Mode

Press Shift + Tab twice to enter Plan Mode. Claude will explore your codebase read-only — perfect for diagnosis without accidentally changing anything:

I'm getting TypeError: Cannot read property 'id' of undefined
when the user clicks submit on the checkout form.
Trace the call chain from @src/pages/Checkout.tsx to find where
the user object could be undefined.

Once you have a plan, switch back to Normal mode to implement the fix.

Debugging Workflow

1. Reproduce & Share Context

Use @ file references to give Claude the exact code involved:

Bug: checkout fails for guest users
Expected: order is placed without login
Actual: TypeError on submit

Relevant files:
@src/pages/Checkout.tsx
@src/hooks/useAuth.ts
@src/api/orders.ts

2. Deep Analysis with Extended Thinking

For complex bugs, trigger extended thinking with the keyword ultrathink:

ultrathink: analyze the race condition between
@src/hooks/useAuth.ts and @src/api/orders.ts.
The order sometimes submits before auth state resolves.

3. Fix with TDD

Ask Claude to write a failing test first, then implement the fix:

Write a test in @src/__tests__/ that reproduces this bug:
guest users get TypeError on checkout submit.
Then fix the code to make the test pass.
Do not modify the test after writing it.

4. Prevent Recurrence

Now that we fixed the null user bug in Checkout,
are there similar patterns elsewhere in the codebase
where user could be undefined?

Undo Mistakes with Rewind

If a fix makes things worse, press Esc Esc to rewind. You can choose to restore:

  • Code only (undo file changes, keep conversation)
  • Conversation only (keep code, undo the last turn)
  • Both (full reset to the checkpoint)

Debugging Prompts

  • Root cause: what are the possible root causes of this error? ultrathink
  • Trace flow: trace how data flows from @src/api/users.ts to the component
  • Pipe logs: tail -f app.log | claude -p "summarize errors and suggest fixes"
  • Catch similar: find all places where we access .id without null checking

Why does context matter for debugging?

Effective debugging with AI is about narrowing the search space. The @ file references and Plan Mode directly control what enters the context window — a fundamental agent design pattern.

Learn about Prompts & Structured Output

Next Steps