When Something Goes Wrong
Bugs always happen. Telling Claude exactly what happened is the fastest way through.
Bugs are normal
Every app has bugs, including apps built by engineers with many years of experience. A bug does not mean you did something wrong.
Claude does the fixing. Your part is to say exactly what happened. You do not need to work out the cause.
Four things to tell Claude
- Where — the app and the screen, and whether it is the screen Claude opened, the preview, or production
- What you did — which button you pressed, what you entered
- What happened — what you actually saw
- What you expected — what should have happened
If you found the bug in a change you have not merged yet (on the screen Claude opened, or in a preview), tell Claude in the same conversation where you asked for the change. In that case, leave out the last paragraph.
A bug in production is fixed the same way as in Small Changes. Claude fixes it and shows you the screen, you check it, and you merge the PR.
Be specific
Write numbers and dates exactly. The more specific you are, the faster Claude finds the cause.
| Hard to act on | Easy to act on |
|---|---|
| The total is wrong | I registered three items at 1,000 yen each. The total should be 3,000 yen but it shows 2,000 yen |
| The order is odd | It should be newest first, but the item from March 1 appears above the item from March 5 |
| The date is off | I entered March 5, but the list shows March 4 |
Paste messages exactly and in full
If red text or a message you cannot read appears on screen, copy all of it exactly as shown and paste it, even if you do not understand it. Putting it in your own words removes clues.
Paste a picture
For things that are hard to put into words, such as a broken layout, paste a screenshot into Claude Code.
If personal information such as a guest's name or contact details is visible, hide that part before you paste.
When the conversation with Claude is not going well
| What is happening | What to send |
|---|---|
| The explanation is too hard to follow | Please explain that again without technical terms |
| Claude stopped partway | Please continue |
| Claude changed things you did not ask for | Please go back to only the change I asked for, and undo everything else |
| You do not know what Claude is doing | Tell me what you are doing now and what you will do next |
| Claude says a skill cannot be found | Check that the algoritmi-sandbox-vibe-coding-platform folder is selected, then ask again in a new conversation |
Start over in a new conversation
If several attempts in the same conversation have not made things better, start a new conversation and explain from the beginning.
Do not try to fix it yourself
- Do not edit files directly on GitHub
- Do not run a command you do not understand
- Do not try to fix production data yourself
Fixes always go through Claude. What Claude cannot handle goes to an administrator.
When to talk to an administrator
- Claude has tried two or three times and it is still not fixed
- Colleagues cannot do their work in production
- Data has disappeared or been changed
- Words such as "migration", "permission", "secret", or "environment variable" appear and you cannot decide what to do
When to Ask an Administrator lists what to tell them.
Quiz
When you ask Claude to fix a bug, which way of telling it helps the most?