Claude Code Bug Fix Prompt — Smallest-Safe-Change Template

What this prompt does

Claude Code’s default behaviour on a “fix this bug” request is to refactor adjacent files, introduce a new abstraction, or swap your styling library while it is in there. That is not debugging — it is unsupervised rewriting. This prompt forces a smallest-safe-change diff: one hypothesis, one patch, one verification command. Drop it into the chat alongside the failing output and Claude Code stays inside the failing call site instead of redesigning your project. The parameterised version lives at /tools/ai-bug-fix-prompt-generator.

The prompt

# Goal
Fix the bug described below using the smallest safe change. First identify the
likely root cause from the failing output, then patch only the call site or
module that is genuinely wrong. Do not rewrite unrelated code.

# In-scope

- Files directly involved in the failing stack trace or build log
- The single failing assertion in tests/<file>.test.ts
- The exact import or type that the compiler rejects

# Out-of-scope

- New dependencies (do not run pnpm add)
- Renaming exports or changing public function signatures
- Moving files between folders or splitting components
- Restyling components or replacing CSS utilities

# Verification

Run `pnpm test --run path/to/affected.test.ts` and paste the output.
Run `pnpm build` and confirm exit code 0.
Re-run `pnpm dev` and reproduce the original failing path manually.

# Output format

1. One paragraph: likely root cause in plain English.
2. The diff (only changed files; full file contents are not required).
3. The verification commands you ran and their truncated output.
4. One sentence flagging anything you intentionally left untouched.

Why each section earns its place

The Goal block carries the three hard phrases the generator at /tools/ai-bug-fix-prompt-generator emits verbatim: “smallest safe change”, “do not rewrite unrelated code”, and “first identify likely root cause”. Anthropic’s published guidance treats CLAUDE.md as project-level context that applies to every conversation; this prompt is the per-task overlay that narrows scope further. In-scope and Out-of-scope explicitly contradict each other so Claude Code cannot interpret silence as permission — the model treats explicit prohibitions far more reliably than implicit omissions. Verification names a literal command (not “run the tests”) because Claude Code attaches its own confidence to commands it can invoke through its bash tool. The Output format section keeps the response short enough that a human can review the diff before accepting it.

Variants by bug type

Map the bug to the verification command Claude Code must run before declaring victory. Each row below mirrors the eight bug types the bug-fix generator parameterises.

The variant list matches the validator chain in scripts/validate-templates.ts so the generator’s output and this hand-authored page stay in sync. If you are debugging a TypeScript error, the verification command is the type-check alone — running the full build wastes thirty seconds on a problem tsc --noEmit answers in three.

When to use this prompt versus the generator

Use this page when you want to read the prompt, understand each section, and paste it once. Use /tools/ai-bug-fix-prompt-generator when you want a parameterised version with stack-aware verification commands, the bug type pre-filled, and optional toggles (verbose mode, attach-stack-trace, regression-test reminder). The page is the SEO entry point; the generator is the daily-driver tool. They emit semantically equivalent prompts — the same five sections, the same three locked phrases — so switching between them never requires retraining your muscle memory.

Common pitfalls when Claude Code debugs

Three failure patterns recur often enough to encode them as locked decisions in your project’s CLAUDE.md. First, Claude Code suggests CSS Modules in a Tailwind project — counter with a locked-decisions line that says “Styling: Tailwind v4 utilities only; no CSS Modules”. Second, it proposes adding a logging library to debug a null reference — counter with “No new dependencies during bug fixes; reproduce with console.log and remove before commit”. Third, it refactors an adjacent component while patching the bug — counter with “Bug fixes touch only files in the failing stack trace; sibling changes go in a separate commit”. For sibling tasks, see the Claude Code feature prompt and the Claude Code code review prompt.