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:
- Describe what's wrong
- Show the problem (screenshot if visual)
- Let Claude investigate and propose a fix
- Review the proposed change
- Test the fix
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
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
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:
[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:
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:
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:
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:
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.