ClaudeDebuggingLevel 3: Workflows

What If Claude's First Bug Fix Doesn't Work?

Stop correcting, clear the session, and ask for two competing causes plus the one cheap check that tells them apart. Anthropic's Claude Code docs say that after two failed corrections, you should run /clear and write one better prompt. This is a good shape for that prompt.

Prompt to copy
Bug: [symptom]. It happens when [conditions]. It does NOT happen when [conditions]. Already tried: [each attempt and what happened].

Investigate [folder] without changing any code. Give me exactly two different causes that fit all of the above. For each, say what we'd observe if it were true.

Then name the single cheapest check that would confirm one and rule out the other. Run it if it's read-only, and otherwise tell me how to run it. Report the result and which cause survived. Don't propose a fix yet.
Cause Aan environment variable differs
  • Printed config differs between machines
  • Fix the variable
Cause Ba stale build cache
  • Printed config matches on both
  • Clear the cache and rebuild
A worked example: the two causes predict different results from one check, so running it rules one out.

Try it now

  1. 1Note what you've tried, because the prompt needs it. Then run /clear, so the failed attempts leave the conversation.
  2. 2Press Shift+Tab until the status bar shows ⏸ plan mode on, which blocks edits while Claude investigates.
  3. 3Send the prompt. Check that the two causes really predict different results. If one check can't separate them, ask for a different pair.
  4. 4Run the check. It worked if the result rules out one cause. Then press Shift+Tab to leave plan mode and ask for the fix.

Use it when

A bug with more than one believable cause: intermittent failures, code that works locally but breaks in production, caching, concurrency, or anything where Claude has already fixed the wrong thing once.

Skip it when

One obvious cause with a stack trace pointing at it. Don't invent a second theory for a missing import. If you can already reproduce the bug in a test, start there, because the test may settle it without any theorizing.

Why it works

It tackles two separate problems. Anthropic's docs say failed attempts stay in the conversation, where Claude keeps re-reading them, and /clear removes them. And its agent teams page says one agent tends to settle on the first believable explanation, and that later investigation then leans toward it. Asking for two theories and a deciding check works against that anchoring within a single session. You run one experiment instead of trying fixes until something appears to work.

Example

A feature works for you but fails for a teammate on the same branch. You send: it fails on their machine, it works on yours, and a reinstall didn't help. Claude might propose an environment variable difference or a stale build cache, and suggest printing the resolved config at startup on both machines. If the output differs, it's the environment. If it matches, the cache moves to the top of the list.

Going further

If it stays unsolved, try an agent team, which Anthropic lists as a strong use for debugging with competing hypotheses. It's experimental and off by default, so set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 first. The docs' prompt asks for five teammates who each investigate a different theory and try to disprove each other's, then update a findings doc with whatever consensus emerges. It uses significantly more tokens than one session, and enabling it changes ordinary delegation too, since a subagent Claude names may launch as a teammate. So turn it off again afterward.

Common mistakes

  • Leaving out where the bug doesn't happen. That's often your most useful fact, and Claude can't get it from the code.
  • Accepting a fix before running the check. Then you're back to guessing, with extra steps.
  • Asking Claude to think harder. Anthropic's docs say that's ordinary text. Use /effort high, or put ultrathink in that one prompt.
  • Telling Claude to write out all of its internal reasoning. Anthropic's Opus 5.5 guide says requests that push the model to reproduce it in the response might be declined. A short explanation of the answer is fine.

Sources

Checked 6 November 2026. Products change often, so confirm details with the vendor.

Related

Beyond the course