Why pasting the error is not enough
The most common debugging mistake with Claude Code: something breaks, you paste the error message, Claude generates a fix, the fix does not work, you paste the new error, Claude generates another fix. This loop goes three or four rounds and you are twenty minutes in and no closer. The problem is not Claude's ability to debug. The problem is that an error message without context is genuinely ambiguous - the same error can have three different root causes depending on how the code is structured.
The fix is simple: give Claude the context it needs to diagnose before asking for a fix. That means telling it what you expected to happen, what actually happened, and what you have already tried. Those three pieces of information narrow the possible causes from many to one or two, and Claude's first fix is right most of the time.
The three-step debug message
The three-step debug message is a format that consistently produces a correct fix in the first or second response. It takes under a minute to write. Here is the structure.
- Expected behavior: one sentence describing what should happen. 'Clicking the submit button should save the form data and redirect to the dashboard.' This tells Claude what correct behavior looks like, which is information it needs to know what to fix toward.
- Actual behavior plus the full error: what actually happened, then the complete error message. Do not trim the stack trace - the specific line number and file name in the trace is often the fastest path to the root cause.
- What you have already tried: a brief list of anything you have already attempted. This prevents Claude from suggesting the same fix you just tried and narrows the possibilities.
The explain-it-out-loud step
Before you send the debug message, write one sentence explaining what you think is causing the bug. Not a question - a hypothesis. 'I think the issue is that the auth token expires before the API call completes.' Write it in plain English without checking whether you are right.
This step does two things. First, it often reveals the answer. Forcing yourself to articulate a hypothesis makes you look at the problem from the outside, and bugs that seemed opaque suddenly become obvious. I have answered my own debug questions this way a significant portion of the time. Second, when you include the hypothesis in the message to Claude, it gives Claude a starting point that is often correct or adjacent to correct, and the first fix lands faster.
This is the rubber duck method applied to Claude Code. The rubber duck is the habit of explaining a bug out loud to an inanimate object before asking for help - the explanation is the diagnostic. Claude Code makes it productive: you explain the bug, and if you do not solve it yourself, you have a well-structured message ready to send.
When Claude's fix makes things worse
Sometimes Claude's fix does not work, or fixes the original bug and breaks something else. When that happens, tell Claude exactly what changed and what the new behavior is - not just the new error without context. The three-step format applies again: here is what you fixed, here is what I expected, here is what is happening now.
If you are on the third fix attempt and still broken, stop and ask Claude to explain its diagnosis of the root cause before trying another fix. 'Before you suggest another fix, tell me what you think is actually causing this and why the last two fixes did not work.' This forces a step back from the fix loop and often surfaces a different diagnosis that gets to the real issue.
Prevention: the pre-flight before every Claude Code session
The fastest debugging is the kind you never have to do. Before starting a new Claude Code session, commit any working code from the last session, note the current state in the CLAUDE.md, and tell Claude what is working and what you are about to change. This means if the new session introduces a bug, you can compare against a clean checkpoint rather than a sprawling set of uncommitted changes.
The other prevention habit: review Claude's diffs before accepting them. Not line by line on every change, but a scan for files that should not have been touched and logic that looks different from what you discussed. Claude occasionally touches files adjacent to the one you asked it to fix, and catching that in the diff review is faster than catching it when something else breaks later.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
Should I give Claude the whole file or just the error?
The right amount of context is the relevant function plus the full error message. Giving Claude the whole file when the error is in one function adds noise; giving it only the error without any code leaves it guessing at structure. Start with the full error plus the specific function or component where the error originates. If Claude asks for more context, give it the next-closest file.
What if I do not know which file the bug is in?
Paste the full stack trace and ask Claude to identify the file and line that is most likely the root cause. A stack trace names every file that was involved in the error, usually with line numbers. Claude is good at reading stack traces and pointing to the originating cause rather than the symptom. Once it identifies the file, use the three-step format from there.
Why does Claude sometimes give a fix that breaks something else?
Claude fixes bugs by changing code, and code changes can have side effects in connected parts of the project. The most common pattern is that a fix in one function changes the data shape or control flow that another function depends on. The prevention is the diff review: before accepting Claude's fix, scan the files it touched for changes that are not directly related to the bug you reported.
How do I debug a bug that only happens sometimes?
For intermittent bugs, give Claude the conditions under which it happens as specifically as you can. 'This happens when the user submits the form twice quickly' is more useful than 'this sometimes breaks.' If you can reproduce it under specific conditions, describe those conditions in the debug message. Claude can then look for race conditions, timing issues, or state that does not reset correctly between actions - the most common causes of intermittent bugs.
Last reviewed by Duncan Rogoff on August 1, 2026
