Fixing Bugs | Claude Code Guide

Something broke. The page that looked fine yesterday now has overlapping text. The contact form doesn't do anything when you click submit. The navigation link goes to the wrong page. The layout falls apart on your phone. Don't panic. This is normal. Things break. What matters is having a systematic way to fix them. ## The Bug-Fixing Workflow Every bug fix follows the same pattern: 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 Let's walk through each step. ## 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. **Good 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. ``` **Less useful description:** ```text The about page is broken on mobile. ``` Both will eventually get fixed. The first one gets fixed in one round. The second might take three rounds of back-and-forth. ## Step 2: Show the Problem For visual bugs, screenshots are your best friend. Take a screenshot of the broken page. Paste it into Claude Code (Ctrl+V or Cmd+V): ```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. ``` Claude sees the screenshot, identifies the visual problems, and can fix them accurately. Visual context eliminates guesswork. ## Step 3: Let Claude Investigate After you describe the problem, Claude investigates. It reads the relevant files, identifies what's causing the issue, and proposes a fix. You'll 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 fix works, great. Move on. If it partially works or created a new problem: ```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. To open it: 1. Open the broken page in your browser 2. Press **F12** (or right-click anywhere and choose "Inspect") 3. Click the **Console** tab at the top 4. Look for red text. Red text means errors Copy the red error text and paste it 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 red text here] Fix this. ``` Claude reads the error message, understands what went wrong in the code, and fixes it. You didn't need to understand the error. You just needed to find it and share it. ## 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 Sometimes the first fix doesn't solve it. That's okay. ``` That didn't fix it. Here's what it looks like now: [new screenshot] The heading is better but the text is still overflowing. ``` Give Claude the new state. Each attempt gives Claude more information. Most bugs get fixed within two or three rounds. 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. ``` Sometimes starting fresh on the problematic part is faster than patching. ## Prevention: Save Before Big Changes The best time to fix a bug is before it happens. Save a snapshot (Module 4, Chapter 18) before making big changes: ``` Save the current state before we make design changes. Message: "Working version before layout redesign." ``` If the changes create bugs you can't fix, you can always rewind to this save point. ## How I Fix Bugs Navigation was overlapping content on mobile. I took a screenshot, pasted it into Claude Code, said "fix it." Claude found the CSS issue and fixed it in about ten seconds. That same bug would have taken me twenty minutes to track down and fix manually. The bug itself was simple, but CSS debugging means reading lots of code to find the one line causing the problem. Claude reads all of it instantly. The workflow is always the same: show the problem, describe what should happen instead, let Claude find and fix the cause. Your expertise is knowing what "right" looks like. Claude's expertise is knowing how to make it happen. > Next up: making Claude Code work on bigger projects. What changes when your project grows from 5 files to 50.

Fixing Bugs with Claude Code (Without Losing Your Mind)

The Bug-Fixing Workflow

Step 1: Describe What's Wrong

Sign In to Unlock

Check Your Email