How Do You Make Claude Fix the Real Bug?
Ask for a failing test that reproduces the bug before any fix. A test that fails, then passes unchanged, is your evidence that Claude found the real cause. Anthropic's Claude Code docs give this as their model prompt: "write a failing test that reproduces it, then fix it."
Users report [symptom] when [steps]. Expected: [what should happen]. Actual: [what happens]. It happens [every time / about 1 run in 10]. Start looking in [folder or file]. First write a failing test that reproduces this, run it with [test command], and show me the failure. Don't change application code yet. Then find the cause and make the smallest fix. It must work for all valid inputs, not just the test's input, so don't hard-code values. Don't edit the new test to make it pass. If you think the test is wrong, tell me. Finish by showing the test output before and after, and the cause in two sentences.
- 1Write the failing test
- 2Make the smallest change
- 3Run the same test
- 4Read the output
Try it now
- 1If this is code you didn't write, run
/effort highfirst. - 2Send the prompt with the real symptom and your test command.
- 3Read the first failure. It should fail for the reason you reported, not because of an import error or a bad fixture. If not, say so before it continues.
- 4After the fix, run
/diff. It worked if the application code changed, the new test didn't change after that first run, and the output shows it going from failing to passing.
Use it when
Any bug that isn't obvious: intermittent failures, wrong output, state that only breaks in combination. It works best in Claude Code, because Claude can run the test itself. In the Claude app, Claude can't reach your test runner, so you run the test and paste the failure back.
Skip it when
A typo or a missing import that a stack trace or language server already points at. And a bug you can't reach from a test, such as a layout problem or something tied to one environment. Use targeted logging there, or /verify, which has Claude build and run the app and look at the result.
Why it works
Anthropic's docs say Claude stops when the work looks done, and a test gives it a pass or fail to work against. It can make the change, run the check, read the output and try again. The failing test also pins the bug down before a fix exists, so you can see whether Claude understood your report. There's a trap to close, though. Anthropic's prompting docs warn that Claude can chase passing tests instead of a solution that generalizes, so tell it not to hard-code. Effort matters here too. Claude Code defaults to medium on Opus 5.5 and Sonnet 5.5, and the docs say to raise it for a bug in code you didn't write or a flaky test, so Claude checks more edge cases.
Example
Anthropic's docs use this one: users report that login fails after the session times out. You send look at token refresh in src/auth/, write a failing test that reproduces it, then fix it, adding your command, say pnpm vitest run tests/auth/refresh.test.ts. A good first result is a test that expires a session and fails on the refresh call, before anything in src/auth/ changes.
Going further
For an intermittent bug, tell Claude it's intermittent, which the docs' bug-fixing tips also suggest. Then ask it to run the new test many times in a loop before and after the fix, because one pass proves little for a flaky failure. That loop is a rule of thumb, not a vendor figure. If you keep correcting Claude and it's still wrong, stop. The docs say that after two failed corrections, you should run /clear and write one better prompt using what you learned, because the failed attempts stay in the conversation and Claude keeps re-reading them.
Common mistakes
- Typing
/debugto debug your app. It's for Claude Code itself: it turns on Claude Code's session debug logging and reads that log. - Accepting a test that fails for the wrong reason. A red test only helps if it's red because of your bug.
- Missing a hard-coded fix. If a change matches the test's exact input, it may only work for that input.
- Leaving out expected and actual behavior. Anthropic's docs say that naming the symptom and what fixed looks like usually saves a round of corrections.
Sources
- Best practices for Claude Code
- Common workflows, Claude Code Docs
- Prompting best practices, Claude Platform Docs
- Commands, Claude Code Docs
Checked 6 November 2026. Products change often, so confirm details with the vendor.