Claude Code Refactoring Prompt: Plan Mode, Tests, Safe Steps
Paste into Claude Code with your target file, smell, test command and limits: get a read-only plan, a green baseline, small tested steps and a stop on red.
Prompt
Act as a staff engineer pairing with Claude Code on a refactor in a real repository. Your job in this session is to change the structure of the code without changing what it does, in steps small enough that each one can be tested and reverted on its own. Start read-only: map the code and propose a plan, and make no edits until I approve it. Inputs: - File, function or module to refactor: [Target] - What is wrong with it today (long function, duplication, mixed concerns): [Smell] - Command that runs the relevant tests: [TestCommand] - What must not change (public signatures, return values, files to leave alone): [Boundaries] - What done looks like: [DoneWhen] - Repo conventions to follow, or "see CLAUDE.md": [RepoRules] Generate: 1. Map (read-only): what Target does, who calls it (search the repo for usages), and which tests cover it today. 2. Coverage gaps: behavior in Target that no test checks. Propose characterization tests that pin current behavior, including any odd behavior, before any refactor step. 3. Baseline: run TestCommand and report the exact pass and fail counts. If anything fails before you start, stop and tell me. 4. Plan: numbered refactor steps, each small enough to review in one diff (extract a function, rename, move a block), with the risk of each step. 5. Execution rules once I approve: one step at a time; run TestCommand after every step; if tests go red, stop, show the failure and propose a fix or a revert; never edit a test to make it pass unless I agree. 6. After each step: a short summary of the diff and the test result. 7. Finish: confirm Boundaries held (signatures unchanged, callers untouched, protected files untouched), run TestCommand and any linter, and suggest one commit message per step. Rules: no behavior changes, even obvious bug fixes; list suspected bugs separately for me to decide. Do not install packages or change config without asking.
Instructions
Start the session in plan mode (claude --permission-mode plan, or press Shift+Tab until the status bar shows plan mode) so Claude Code reads and plans without editing; approve the plan, then switch modes to let it edit. Work on a branch and commit after each green step. Claude Code checkpoints let you undo edits with /rewind or Esc twice, but files changed only by Bash commands are not tracked, and checkpoints do not replace Git. Variation: for a JavaScript or Go codebase, change TestCommand and RepoRules; for a large module, ask for one subagent to map callers so the main context stays small. Review every diff yourself before merging. The billing module in the example is invented. Claude Code and Claude are Anthropic products; PromptDig is not affiliated with or endorsed by Anthropic.
Generated Output
This image was generated using the prompt above.

Examples
Example Input
Target: src/billing/invoice.py, the build_invoice() function (about 400 lines) Smell: one function computes line totals, applies discounts, calculates tax by region and formats the PDF data; three copies of the same rounding code TestCommand: pytest tests/billing -q Boundaries: build_invoice(order, customer) keeps its signature and return dict; do not touch src/billing/pdf_legacy.py DoneWhen: build_invoice under 60 lines, each extracted helper has its own tests, all billing tests green RepoRules: see CLAUDE.md (type hints on new functions, no new dependencies)
Example Output
PLAN (plan mode, no edits made) 1. MAP build_invoice() does four jobs in order: line totals, discounts, regional tax, and building the dict that pdf_legacy.render() reads. Callers (repo search): api/routes/invoices.py and jobs/monthly_billing.py. Both pass (order, customer) and read the returned dict. Tests covering it: tests/billing/test_invoice.py (end-to-end cases). No test calls the discount or tax logic on its own. 2. COVERAGE GAPS - Discounts: percentage and fixed discounts on the same order. No test. - Tax: the region fallback when customer.region is missing. No test. - Rounding: the three rounding blocks are not identical. Two round each line, one rounds the total. A test must pin the current result before we merge them. Proposed characterization tests (new file tests/billing/test_invoice_characterization.py): stacked discounts, missing region, and an order of three lines priced to show the rounding difference. Expected values: recorded from the current code, not computed by hand. 3. BASELINE Run: pytest tests/billing -q I will report the exact pass and fail counts here before any refactor step. If any test fails at baseline, I stop. 4. REFACTOR STEPS Step 1: add the characterization tests. Risk: low (tests only). Step 2: extract compute_line_totals(order) -> list. Risk: low. Step 3: extract apply_discounts(lines, order) -> Decimal. Risk: medium (stacking order). Step 4: extract regional_tax(subtotal, customer) -> Decimal. Risk: medium (region fallback). Step 5: extract build_pdf_payload(...) -> dict, keeping every key and its order as pdf_legacy.py expects. Risk: medium. Step 6: put the rounding in one helper ONLY IF the step 1 tests show all call sites can share it. Otherwise keep two helpers and flag it. Risk: high. Step 7: build_invoice() becomes a short function calling the helpers. Target under 60 lines. 5. EXECUTION RULES One step per turn. Run pytest tests/billing -q after each one. On red: stop, show the failing test and the diff, and propose a fix or a rewind. I will not edit existing tests. 6. PER-STEP REPORT Files changed, lines added and removed, a one-line summary, and the test result. 7. FINISH CHECKS build_invoice signature and return keys unchanged (diff against main). api/routes/invoices.py, jobs/monthly_billing.py and pdf_legacy.py untouched. Tests and linter pass. Type hints on every new function. Suggested commits: "test(billing): pin invoice behavior", then one "refactor(billing): extract <helper>" per step. SUSPECTED BUG (not fixed) Line totals and the order total round differently, so a total can differ by a cent from the sum of the lines. Decide separately whether to fix it.