Set the Rule First: Reproduce Before You Change
The most common failure: a user reports a bug, Claude edits the code and hands back a "this looks right" fix that nobody ever verified against the real bug. The mindset fix is to make the tool reproduce first — force the problem out with a minimal input before talking about fixing.
When issuing instructions, say the context and expectation clearly: what environment, the input that errors out, expected vs actual. Being explicit matters more than knowing internally. If the project has a test framework, step one should be asking Claude to write a failing test that captures the current buggy behavior.
The three-part opening of a good prompt: reproduction steps, the concrete symptom you observed, and the system’s expected behavior. The more concrete each is, the fewer "auto-hallucinated" wrong fixes appear.
# Task instruction template for Claude Code
"Reproduce [BUG]: on the current branch, first write a test with input X that fails (red) today.
Write only the test, do not touch production code, and report back once the failing case runs."
# Expected: a red test (failing test) as hard proof of the bugPin the Expected Behavior with a Test, Then Make Code Pass It
With a failing test that reproduces, the fix becomes "make it green" rather than free play. Ask Claude to declare its diagnosis (root-cause hypothesis) before it makes any change, so you can judge whether the direction is sound before any edit lands.
Then instruct: touch only the minimal scope to pass the related tests, introduce no new dependencies, and do not touch unrelated files. Run the full suite to confirm all green, and keep the failing test as a regression guard.
The point is to have the tool give a diagnosis explanation first rather than output a patch directly. That distinguishes "diagnose correctly, then fix" from "blindly edit until tests pass".
# Follow-up instruction
"First give a root-cause diagnosis (one or two sentences), then make the test green with a minimal change.
Do not add new dependencies or touch unrelated files; run npm test when done and paste the results."Done Is Not Finished: Run a Review and Regression
After Claude edits, do at least one reverse review yourself: what changed, does it exceed the reported problem, and are there side effects and boundary cases not covered? A recommended move is letting the tool narrate its own diff via git diff and then reviewing manually.
Make the full suite and type check hard gates (pnpm test, pnpm typecheck), plus the linter if present. Then ask Claude to add a change note explaining why it fixed it this way, recording decisions rather than just piling up code.
In a real flow, review often catches concurrency, null-safety or backward-compat issues the AI underhandled, so do not skip this step.
claude "List all changes in this session with git diff and explain each one;
run pnpm test and pnpm typecheck and report whether they pass;
add a one-line change note (why, not what)."The Classic Miss: The Tool "Fixed" It and Broke Something Else
The most dangerous AI fix is not that it fails, but that it rewrites adjacent logic beyond recognition. This usually stems from an undefined scope — just saying "fix this bug" lets the tool expand the blast radius on its own.
The counter is to pin scope: whitelist which files/functions may be modified, explicitly list what is forbidden to touch, and target a minimal diff. When reviewing the diff, if you see unrelated refactors, suspiciously deleted logic, or formatting rewrites, revert and redo with tighter scope.
Also keep a baseline before it edits. Use version control diff/back or copy the original files to .bak so the tool has an escape route if it breaks things.
diff --git a/src/payment.js b/src/payment.js
# Review: only the fix target should change; revert immediately on unrelated refactors/deletes
# A fallback in case it breaks
cp src/payment.js src/payment.js.bak # Manually back it up before editingSettle: Write This Root Cause and Fix into Comments and Docs
The last step of the fix loop is not committing but settling. Ask Claude to add a one-line "why here" comment at the critical spot (explaining the pitfall, not restating the code), and record the root cause, trigger condition and solution in the project docs or the issue.
The value is that the next person — or AI — facing a similar problem can read the historical decision instead of re-treading the same trap. This converts a one-off fix into reusable knowledge and marks the line between firefighting and governance.
If the fix touches a shared convention (e.g. parameter validation or boundary handling), update the relevant CONTRIBUTING or README section as well, so rules and code evolve consistently.
// Fix-record example (write "why" in the comment, not a recap of what was done)
// Previously dateStr could be empty, making endDate invalid; guard against empty before parse
// See docs/bugfix/2026-09-outdated-enddate.md for the root cause
claude "Add a comment at this fix explaining the cause, and record the root cause in the corresponding docs file."