5 Techniques to Debug Claude Code
When Claude loses the plot, the fix is usually you
I’ve been building with Claude Code daily for months now. The single most useful thing I’ve learned is this: when Claude is failing, the problem is context, not intelligence. Claude can’t see what you can see. Your job isn’t to tell Claude to try harder. Your job is to show Claude what it’s missing.
This isn’t a best practices guide for using Claude Code. It’s what I do when I’m stuck. When Claude is looping on the same error, when a fix breaks something else, when I’ve been going in circles for 20 minutes. These five techniques are how I get unstuck.
1. Feed Claude the Evidence
Terminal
The instinct when something breaks is to describe the problem. “the login page is broken.”
Don’t do this.
Point Claude at the evidence directly. Send Claude the terminal output, paste a screenshot, or let Claude check the browser itself with Claude in Chrome.
Claude is better at diagnosing real errors than hypothetical ones. Every layer of interpretation you add is a layer where information gets lost. It also costs you tokens. When Claude has to guess what’s wrong, it reads files, forms hypotheses, makes edits, runs into the same problem, and tries again. That’s expensive.
A vague prompt can burn through 10x the tokens of a specific one because Claude is doing detective work you could have skipped by sharing the evidence upfront.
Screenshots
Claude is multimodal. When the UI is broken, paste a screenshot with Ctrl+V. When a page layout is wrong, drag the image into the prompt. You’ll get a better response from “here’s what it looks like” than from “the sidebar is overlapping the main content on mobile.”
I use this more than anything else. It is incredibly useful and more efficient than describing every detail.
Claude in Chrome
The power version. Run claude --chrome and Claude can navigate your browser, click through your UI, read console errors, and take screenshots on its own. You stop being the middleman. Claude sees the problem directly, in your real browser with your real login sessions.
Install the Claude in Chrome extension, restart Claude Code, and run /chrome to connect it.
I use all three constantly:
- Terminal output for backend work
- Screenshots for quick UI bugs
- Claude in Chrome when I need Claude to see the browser for itself
Same instinct each time: give Claude the raw data, not my interpretation of it.
2. Build a Source of Truth File
The longest debugging sessions aren’t hard problems. They’re circles. Claude tries something, it fails, context compresses, and Claude tries the same thing again.
The fix is simple: make Claude write it down.
That file is now a persistent source of truth that survives context compression. When Claude starts going in circles, point it back at the file. It re-reads the spec, sees the failed attempts, and stops repeating them.
Files outlive context. Your conversation gets summarized and compressed as it grows. But a markdown file in the repo stays exactly as you wrote it. Claude can Read it fresh at any point and get the full picture back.
I keep these in docs/plans/ or just a NOTES.md at the project root. Cheap to create, saves hours of circular debugging.
3. Think Holistically
Claude solves the immediate problem you give it. You say something is broken, it finds the fastest path to making the error go away. Quick fix, move on.
But the fastest fix is often the wrong fix. It patches the symptom and breaks something downstream. Or it works today but doesn’t scale. Or it adds a special case where the real answer is fixing the abstraction.
Claude will tell you it’s fixed. The error might even go away. But the real reason it wasn’t working is still there, hidden under a patch.
This changes the output completely. Claude stops optimizing for the immediate error and starts considering the system. It reads more files. It thinks about side effects. It proposes solutions that actually hold up.
I say this to Claude constantly: “stop trying to fix this and think about it more holistically.” It’s the difference between a patch and an architecture decision.
4. Use Agent Teams
When a problem is big enough that one Claude session can’t hold it all, stop trying to make one session do everything. Spin up a team.
Agent teams are multiple Claude Code instances that coordinate through a shared task list and message each other directly. One session leads, the others work in parallel. Each teammate has its own context window, its own focus, and can challenge the others’ findings.
This is different from subagents, which report back to the main session. Teammates talk to each other. The auth investigator finds a session timing issue and messages the validation reviewer to check if the form handles it. The test checker finds missing edge cases and shares them with both.
The strongest use case for debugging: competing hypotheses. When you don’t know the root cause, spawn teammates to investigate different theories in parallel. Have them challenge each other’s findings. The theory that survives is more likely to be the real cause.
Agent teams are still experimental. Enable them in settings and start with research or review tasks before trying parallel implementation.
5. Build Skills for Repeated Problems
If you find yourself typing the same instruction to Claude more than twice, stop. You’re being the loop again.
Claude Code has a skills system. A skill is a markdown file in .claude/commands/ that turns a repeated workflow into a single slash command. Instead of typing “research best practices, check the docs, write a source of truth file” every time, you run /source-of-truth and it happens.
I built three skills from this article and open sourced them: /source-of-truth that builds the persistent plan file, /unstuck that breaks you out of debugging loops, and /review that reviews your diff with fresh eyes.
Install them globally and use them in any project:
git clone git@github.com:allierays/debugging-claude-skills.git
cp -r debugging-claude-skills/skills/* ~/.claude/skills/The best debugging skill is the one you don’t have to remember to use. Build it once, run it with a slash command, and move on to the actual problem.
The through-line across all five: debugging Claude is not about making Claude smarter. It’s about making the problem visible. Every technique here is a way of showing Claude something it couldn’t see, giving it data it didn’t have, or slowing down enough to find the right solution.
Debugging Claude is the same work, with one twist. Your partner in the investigation is also the system you’re investigating. You’re debugging with the thing you’re debugging.
That’s what makes it interesting. And once you stop treating Claude’s failures as frustrating and start treating them as informational, the whole experience changes. Claude looping isn’t Claude being broken. It’s Claude telling you it can’t see what it needs to see. Your job is to figure out what that is.