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.
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.
- Printed config differs between machines
- Fix the variable
- Printed config matches on both
- Clear the cache and rebuild
Try it now
- 1Note what you've tried, because the prompt needs it. Then run
/clear, so the failed attempts leave the conversation. - 2Press
Shift+Tabuntil the status bar shows⏸ plan mode on, which blocks edits while Claude investigates. - 3Send the prompt. Check that the two causes really predict different results. If one check can't separate them, ask for a different pair.
- 4Run the check. It worked if the result rules out one cause. Then press
Shift+Tabto 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 putultrathinkin 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
- Best practices for Claude Code
- Orchestrate teams of Claude Code sessions, Claude Code Docs
- Choose a permission mode, Claude Code Docs
- Model configuration, Claude Code Docs
- Prompting Claude Opus 5.5, Claude Platform Docs
Checked 6 November 2026. Products change often, so confirm details with the vendor.