Refactor with Claude Code without surprise scope creep. Copy-paste prompts for safe rename refactors, extract-function, dead-code removal, and large-scale migrations.
Most Claude Code refactor failures come from prompts that say "refactor X" without bounding the scope. Claude will helpfully also rename your variables, reformat your strings, and "modernise" three unrelated files. The prompts below box in the change to exactly what you wanted.
Rename [OLD_NAME] to [NEW_NAME] across this codebase.
Constraints:
- Mechanical change only — same logic, same control flow
- Update all references: definitions, imports, comments, docstrings, tests, README
- Do NOT touch any other code in the same files
- Do NOT reformat
- Do NOT remove "unused" imports flagged as a side effect
- After: run the test suite and confirm green
Output: unified diff, then test results.The "do not touch any other code" clause is the difference between a clean rename PR and a 40-file horror.
In [FILE], the function [FN_NAME] is doing too much.
Extract the section starting at line [N] (the [WHAT IT DOES] logic) into
a new function called [NEW_FN_NAME].
Constraints:
- Preserve exact behaviour (no logic changes)
- Pass all currently-used variables as explicit parameters
- Return value: [DESCRIBE]
- Add a one-line docstring explaining when it's called
- Update the call site only
- Do NOT extract anything else, even if it's tempting
After: list the parameters and return type of the new function.Identify dead code in [DIRECTORY]:
- Functions defined but never called
- Imports unused
- Exported names with zero importers
- Branches reachable only via deprecated flags
For each finding:
- file:line
- evidence (grep results showing zero callers)
- confidence (high / medium / low — what could you be missing?)
Do NOT delete anything yet. Output as a markdown table.
I'll review and tell you which to remove.Why the two-phase split? Claude's dead-code detection is good but not perfect — dynamic imports, reflection, and string-built names trip it up. Reviewing the table first lets you veto false positives before deletion.
Refactor [FN_NAME] in [FILE] to fix [SPECIFIC PROBLEM] with the smallest
possible diff.
Hard limits:
- Diff under 30 changed lines
- No renames anywhere
- No formatting changes
- No changes to functions called by [FN_NAME]
- No new files
- No new dependencies
If you can't fit it in 30 lines, propose a multi-step plan instead.I want to migrate [DIRECTORY] from [OLD PATTERN] to [NEW PATTERN].
Phase 1 (this prompt): plan only.
Output a 5–7 step migration plan where:
- Each step touches at most 5 files
- Each step leaves the codebase compiling and tests passing
- Each step has a single semantic theme (don't mix concerns)
- The last step removes the old pattern entirely
For each step: title, files touched, what changes, rollback if it goes wrong.
Do NOT write code in this prompt. Wait for "execute step 1".This is the right way to do refactors larger than a single PR. Sequential reviewable steps beat one giant change that's impossible to revert cleanly.
Convert callback-style functions in [FILE] to async/await.
Per function:
- Wrap callback-using internals with util.promisify or equivalent
- Convert the public signature to async (returning Promise)
- Update callers in the same file
- Do NOT update callers in other files — list them instead, I'll do separate PRs
Output:
1. Diff of [FILE]
2. List of external caller file:line that I need to update nextFunction [FN] in [FILE] has cyclomatic complexity of [N].
Reduce it to under 10 without changing behaviour.
Approach order:
1. Early returns / guard clauses
2. Extract nested conditionals to predicate functions
3. Replace switch/if-chain with a lookup map when the cases are pure data
4. Only if 1–3 don't suffice: split into multiple functions
Show the diff. Run tests. Confirm green.These refactor prompts are 7 of the 30 in the Claude Code Power Prompts pack. The PDF groups them by workflow (review, debugging, testing, architecture, docs, devops) with a TIP box per prompt. £3 launch price tonight (first 10 buyers), then £5. Paste into CLAUDE.md once, Claude reads it every session.