# Fixing bugs with Claude Code (without losing your mind)

**Author:** Ivan Misic  
**Published:** 2026-01-27  
**URL:** https://ivanmisic.net/blog/ai-tools/fixing-bugs-without-losing-mind

**TL;DR**

Give Claude Code a reproducible bug: what you did, what you expected, and what happened. Let it inspect the relevant files and explain the proposed change, then test the same case again.

- For a visual problem, include the page, viewport, expected result, and a screenshot
- For a behavior problem, reproduce it in the browser console and copy only the relevant error and surrounding lines
- Remove tokens, email addresses, personal data, and private URLs before sharing logs
- Review the proposed cause and diff, then test the original case and nearby behavior after each change
- If the same approach fails twice, stop patching, ask for a new diagnosis, and keep a checkpoint, backup, or Git restore point before larger changes

When the navigation on my site overlapped the content on mobile, I pasted a screenshot into Claude Code and described what should happen instead. Claude found the CSS rule, but I still reviewed the change and tested several screen widths. I use the same loop for most bugs.

## The Bug-Fixing Workflow

My debugging loop has five steps:

1. **Describe** what's wrong
2. **Show** the problem (screenshot if visual)
3. **Let Claude investigate** and propose a fix
4. **Review** the proposed change
5. **Test** the fix

<figure>

![Five-stage debugging loop showing the reader describing a bug and supplying evidence, Claude investigating and proposing a change, and the reader reviewing and testing before either finishing or reporting the changed state](/images/blog/ai-tools/claude-code-debugging-loop.png)

<figcaption>The important split is responsibility. You supply the observed behavior and decide what to approve; Claude investigates and proposes. Testing closes the loop. If the result is partial, the changed state becomes the next bug report.</figcaption>

</figure>

Start with the broken state.

## Step 1: Describe What's Wrong

A good bug description has three parts:

- **What you did:** "I opened the about page on my phone"
- **What you expected:** "The text should be readable and properly spaced"
- **What actually happened:** "The heading overlaps the navigation and the text runs off the side of the screen"

Give all three. Claude can work with less, but more context means a faster fix.

### A useful description
```text
On the about page, when I view it on my phone (or narrow the browser
to phone width), the heading text is too big and overlaps the
navigation bar. The body text also runs off the right side of the screen.
```

### A vague description
```text
The about page is broken on mobile.
```

The first description gives Claude a reproducible case. The second makes it guess what "broken" means, so investigation usually takes longer.

## Step 2: Show the Problem

For visual bugs, take a screenshot of the broken page and paste it into Claude Code using the shortcut shown for your terminal:

```text
[pasted screenshot]
This is what the about page looks like on my phone. See how the
heading overlaps the nav? And the text goes off-screen on the right?
Fix this.
```

Add the page, viewport, expected result, and what looks wrong. The image reduces ambiguity, but Claude still needs to inspect the relevant HTML and CSS, and you still need to test the change.

## Step 3: Let Claude Investigate

Ask Claude to inspect the relevant files, explain the likely cause, and propose a change before editing. You may see something like:

```text
The issue is in css/styles.css. The heading font size is set to 4rem
which is too large for small screens. There's also no max-width on
the text container, so it can overflow.

I'll fix both issues:
1. Add a responsive font size for the heading on small screens
2. Add overflow handling to the text container

Allow changes to css/styles.css? [y/n]
```

Review what Claude wants to change. Does it make sense? If you're not sure, ask:

```text
Before you make the change, explain what this fix does in
plain English.
```

## Step 4: Test the Fix

After Claude makes the change, check it yourself:

- Refresh the browser
- Test the specific scenario that was broken
- Check that nothing else broke in the process

If the result is partial or creates another problem, report the new state before Claude makes another change:

```text
The heading is fixed but now the body text has too much space
on the left side. There's a big gap between the text and the
edge of the screen.
```

Another round. Describe what's still wrong. Claude adjusts. Test again.

## The Browser Console Trick

Sometimes bugs aren't visual. A button doesn't work. A form doesn't submit. Something that should happen when you click doesn't.

Your browser has a built-in error log called the Console. Open the browser's developer tools, choose Console, and reproduce the bug. Copy the relevant error and a few surrounding lines. Remove tokens, email addresses, personal data, and private URLs before pasting the log into Claude Code:

```text
When I click the submit button on the contact form, nothing happens.
Here's the error from the browser console:

[paste the relevant console error here]

Fix this.
```

The console error gives Claude a starting point. Ask it to trace the error to the code, explain the proposed change in plain English, and show how to test that the bug is gone.

## Common Bug Categories

Most bugs fall into predictable categories:

| Symptom | Likely Cause | What to Tell Claude |
|---------|-------------|-------------------|
| Things overlap or look wrong | CSS/styling issue | Screenshot + "these elements should be [how you want them]" |
| Links go to wrong page | Wrong URL in the HTML | "The About link goes to contact.html instead of about.html" |
| Page looks different on phone | Missing responsive styles | "This page looks broken on mobile" + screenshot |
| Something doesn't work when clicked | JavaScript error | Console error + "this button should [what it should do]" |
| Page loads slowly or not at all | Missing file or wrong path | "The page shows [what you see] instead of [what you expect]" |

## When the Fix Doesn't Work

The first fix may be wrong, so test the same case after every change.

```
That didn't fix it. It looks like this now:
[new screenshot]
The heading is better but the text is still overflowing.
```

Give Claude the new state after each attempt. If the same approach fails twice, stop patching and ask it to explain the cause or propose a different fix.

If you're going in circles (fix, break, fix, break), try a different approach:

```
Let's take a different approach. Instead of fixing the current CSS,
show me a simple, clean layout for this page that works on all
screen sizes. Replace the current styles for this section.
```

If two changes fail for the same reason, I would stop patching and ask for a simpler replacement for that section.

## Recovery: Save Before Big Changes

A snapshot does not prevent the bug, but it limits the recovery cost.

Claude Code takes a checkpoint before each prompt you send, so a recent mistake is usually one `/rewind` away. Run it, or press `Esc` twice with an empty input, pick the prompt from before the problem, and choose whether to restore the code, the conversation, or both.

That covers the last few steps of a session. It does not cover a whole afternoon, and it does not cover anything a shell command changed. Before a large change, ask for a copy you own:

```
Zip this project into a dated backup before we start the redesign.
```

The next chapter sets up Git, which replaces both of these with something better.

Claude can search the code and propose a change, but I still decide what correct means and verify the result.

> Next up: save a version you can restore, then publish the site.