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:

text
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:

text
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

For complex bugs, be specific about what you need analyzed:

text
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:

text
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

text
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 on an empty input to open the rewind menu. Pick a prompt to rewind to, then choose:

  • Code only (undo file changes, keep conversation)
  • Conversation only (keep code, undo the last turn)
  • Both (full reset to that point)
  • Summarize from here / up to here (compact transcript without losing the thread)

Debugging Prompts

  • Root cause: what are the possible root causes of this error?
  • 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

Related Reading

Continue with practice

You have finished the core ideas of Debugging with Claude Code.

If you want to turn the idea into something reusable, continue practicing on AgentWay.

Go to practice