Something broke, and you've asked your AI tool to fix it. Sometimes it nails it. Other times it rewrites half your project and the bug is still there. The difference is usually the prompt.
These recipes work in any AI coding tool, including Claude Code and Cursor, and in a chat window if that's all you have. Each one is a pattern you can paste and adapt. Words in [square brackets] are blanks for you to fill in.
Before you start: make an undo point
AI tools change files. Before a debugging session, save your current state so you can always get back. If you haven't used Git yet, our Git safety net guide takes about ten minutes and is the best habit you can build. In short:
git add -A git commit -m "Before debugging"
Now any fix attempt is reversible.
Recipe 1: Give the whole error, not a summary
"It's broken" gives the AI nothing to work with. The error message is the single most useful clue you have, so paste it in full.
I'm getting this error when I [what you did, e.g. click Save on the profile page]: [paste the full error text, including the lines that mention file names] Expected: [what should happen]. Actual: [what happens instead]. Read the files involved and explain the likely cause before changing anything.
Where to find the error:
- A website: open the browser's developer console (right-click the page, choose Inspect, then the Console tab) and copy the red text.
- A terminal command: copy the output from the line where it starts failing.
- No visible error: say so, and describe exactly what you see versus what you expected.
Screenshots help too, if your tool accepts images. Paste one of the broken page next to the text description.
Recipe 2: Ask for explanation first, then the fix
AI tools are eager to edit. Slowing them down often gives a better answer.
Don't change any code yet. Look at [the file or feature] and tell me: 1. What this code is supposed to do. 2. What could cause [the symptom]. 3. How you'd confirm which cause is real.
You read the answer, check it makes sense, and only then say "go ahead with the first option". This also teaches you how your own project works.
Recipe 3: Ask for several hypotheses, ranked
The first idea isn't always right. Asking for a ranked list stops the tool fixating on a wrong guess.
List the three most likely causes of [symptom], from most to least likely. For each one, tell me what evidence in the code supports it and a quick check that would rule it in or out.
Then run the quick checks yourself (or ask the tool to) before any fix is attempted. Often the check for hypothesis one is "add a line that prints the value", which takes a minute and tells you exactly where the problem is.
Recipe 4: Reproduce it first
A bug you can trigger on demand is a bug you can prove is fixed. Ask for the steps or a test that makes it happen:
Before fixing this, write the smallest test (or a short script) that reproduces the bug and currently fails. Run it and show me the failure.
Once the failing test exists, the fix has a clear target: make that test pass. You'll know it worked because a check turned green, not because the AI said so. If your project has no test setup, ask for a simple set of manual steps instead:
Give me numbered steps to reproduce the bug by hand, and what I should see when it's fixed.
Recipe 5: Ask for the smallest fix
Without a constraint, "fix the bug" can turn into a refactor. Tell the tool to stay small.
Fix this with the smallest change possible. Don't rename things, don't reformat other code, and don't touch files unrelated to the bug. Tell me which files you changed and why.
Small changes are easier to read, easier to review and easier to undo. If the tool says a bigger change really is needed, ask it to explain why before approving.
Recipe 6: Add a test so it stays fixed
After a fix works, lock it in:
Now add a test that would have caught this bug. Keep it short and follow the style of the existing tests in this project. Run the full test suite and report the result.
If something else in your project now fails, you've found a side effect early rather than in front of your users.
Recipe 7: Undo cleanly when it goes wrong
Sometimes the fix makes things worse. Don't pile more attempts on top. Go back to the undo point and try again with a better prompt.
To see what changed:
git status git diff
To throw away all uncommitted changes and return to your last commit:
git restore .
Be careful: that permanently discards your edits since the last commit, which is exactly why committing before you start matters. To undo changes to a single file only, use git restore path/to/file. Some tools also have their own undo or checkpoint features, but Git works everywhere.
Then restart with what you learned:
Last time you tried [what the AI tried] and it didn't work because [what happened]. Let's take a different approach. [Recipe 2 or 3 prompt]
A full example, start to finish
Imagine a signup form where the button does nothing.
- Undo point. You commit what you have.
- Recipe 1. You open the console, find
Uncaught TypeError: Cannot read properties of undefined (reading 'email'), and paste it with "I click Sign up and nothing happens". - Recipe 2. The AI explains the form handler reads
user.emailbeforeuserhas been set. - Recipe 4. It writes a test that submits the form and fails with the same error.
- Recipe 5. It adds a two-line check for the missing value and nothing else.
- Recipe 6. The test passes, and you ask it to run the whole suite.
- You commit with a message like "Fix signup crash when user is not loaded".
Each step is small and checkable, and at no point did you have to understand the entire codebase.
When the AI keeps getting it wrong
If you're three attempts in with no progress, change something rather than repeating the same request.
- Start a fresh conversation. Long chats collect wrong assumptions. Restart with a clean summary: the symptom, the error, what you've already tried.
- Narrow the scope. Point the tool to the specific file or function, rather than "the app".
- Add information. Version numbers, the exact steps you took, a screenshot, the relevant log lines.
- Ask what it needs. "What information would help you diagnose this?" is a legitimate prompt.
- Check for a project memory file. If the tool keeps making the same wrong assumption about your project, put the correct fact in CLAUDE.md (or your tool's equivalent) so it's remembered.
- Take a break. Seriously. Many bugs turn out to be a typo you'll spot after lunch.
Troubleshooting the prompts themselves
The AI changed lots of files. Use Recipe 5 next time, and restore with Recipe 7 this time.
It says it's fixed but the bug remains. You skipped reproduction. Use Recipe 4 so "fixed" is something you can verify.
It invents file names or functions. Ask it to read the file first: "Open [file] and quote the function before you suggest a change." Never accept edits based on code it hasn't looked at.
It suggests installing something new. Ask why that's needed and whether a smaller fix exists. New dependencies are worth questioning, especially in a project you don't fully understand.
Safety notes
Never paste passwords, API keys or customer data into a prompt. If an error message contains one, replace it with [REDACTED] first. Review what the tool changed before you commit it, and keep your undo point.
Recap
- Make an undo point first.
- Paste the full error plus what you did and what you expected.
- Ask for explanation, then ranked hypotheses, before any edits.
- Reproduce the bug, then ask for the smallest fix.
- Add a test, and undo with Git when an attempt goes wrong.
The same habits scale up: the more checkable each step is, the less you have to trust the AI blindly. Once the basics feel natural, try subagents for independent reviews, or hooks to run checks automatically.