AI Refactoring Prompt Pack
AI can rewrite a module in seconds. Without structure, it's often an unreviewable rewrite with silent behaviour changes.
Paste a messy file and ask “clean this up,” and the typical result is a redesign: new abstractions, wholesale renames, reformatting, maybe a dependency bump — and a logic tweak that reviewers miss because the diff is mostly noise. Ask “make it more maintainable” and you get architecture theatre. Green tests may only prove the new code agrees with itself, because nothing locked yesterday's behaviour.
AI Refactoring Prompt Pack gives you ready-to-paste prompts with roles, {{placeholders}}, a plan-before-code process, output contracts and hard rules, so Cursor, Claude Code, ChatGPT or Copilot Chat work like a disciplined refactoring partner. You get a ranked smell map, a characterization safety net, small behaviour-preserving slices, and a PR description that shows what was proven.
This is not an AGENTS.md / agent-workflow pack, not a PR-review pack, not a test-writing pack and not a debugging pack. It is only about refactoring and cleaning up code safely.
What you get
- 📘 PDF field guide (30 pages): why “clean this up” fails, the refactoring loop (map → safety net → small slice → prove → describe), every prompt explained, combining prompts with an illustrative worked example, team norms, prompt anatomy and follow-up prompts
- 🗂️ templates/: 8 prompts + 2 checklists + Cursor .mdc rule + README
- 🖼️ cover.png
The 8 prompts
- Code-smell map & refactor plan: inventory with locations, payoff vs risk vs size, ranked first slice with out-of-scope
- Safety net first: characterization tests: behaviour inventory, MUST-PRESERVE contracts, tests that pin today's quirks before edits
- Extract function/module: inputs/outputs/side effects, stepped extract, behaviour preserved, no drive-by churn
- Untangle a god class: responsibility map, leaf-first extraction, facade when API is frozen, backlog for later splits
- Large-scale rename / API migration: call-site inventory, expand/contract or shims, batch steps, no flag-day by default
- Dead code & dependency cleanup: HIGH/MEDIUM/LOW confidence grades, remove HIGH only, park the rest with next checks
- Strangler-fig legacy replacement: entrypoint map, seam, parity, rollback, next production-safe step only
- Refactor PR description + reviewer guide: behaviour contract, reading order, proof, residual risks, tailored checklist
Also included
- Refactor safety checklist: Must / Should / red flags before you merge an AI-assisted refactor
- When NOT to refactor / when to stop: freezes, missing safety nets, scope creep, test vandalism, and when profilers or humans beat another prompt
- Cursor rule (refactoring.mdc): goal before edits, safety net first, no drive-bys, strangler not big-bang, prove it
Who it’s for
- Developers using Cursor, Claude Code, ChatGPT or Copilot Chat who want cleanups that stay reviewable
- Engineers inheriting god classes or legacy modules who need a first slice, not a manifesto
- Teams that want shared refactor norms without a dedicated architecture guild
- Anyone migrating renames or APIs who has been burned by one giant replace PR
Who it’s not for
- People looking for an automated rewrite service or “AI architect” that redesigns the system unattended
- Anyone who wants AI to merge structural changes without human review
- Teams whose policy forbids pasting code into AI tools. This pack doesn't change that
How it works
- Pick the prompt that matches the situation
- Fill the {{placeholders}} with paths, goals, constraints and a real test command
- Review the plan / inventory before the model edits widely
- Add or confirm the safety net; then run the small slice
- Accept the PR only when it passes the checklist; a human decides what merges
Honest positioning
No fabricated testimonials, download counts, time-saved claims or benchmarks. The worked example in the guide is clearly labelled as fictional. Judge it by running prompt 01 on a messy module you already cleaned up, using only the original files and constraints.