Refactor Pilot Framework
A systematic, AI-assisted framework for safely refactoring legacy codebases.
Refactor Pilot Framework gives you a repeatable, four-phase process for using large language models (LLMs) to understand, test, transform, and verify code — turning weeks of manual refactoring into hours of guided, AI-accelerated work.
Whether you use Claude, ChatGPT, Copilot, Cursor, or any other AI coding tool, the prompts and scripts in this repo are designed to be tool-agnostic and copy-paste ready. If you use Claude Code, you can drop the included skills directly into your workflow for an even more integrated experience.
Why This Exists
Every codebase has that one corner nobody wants to touch. The authentication module that was "temporary" three years ago. The 2,000-line utility file where six different teams dumped helper functions. The styling layer where every other rule needs !important because the cascade became a war zone. Configuration files with flags nobody remembers setting, and entire directories that only one person (who left the company) understood.
Technical debt doesn't happen overnight — it accumulates one shortcut at a time until the cost of changing anything exceeds the cost of just building around it. And now you've got a codebase that works, but nobody can confidently modify it without breaking something unexpected.
AI changes the economics of this problem. What used to require a senior developer spending days carefully tracing dependencies and hand-rewriting modules can now be done in a fraction of the time — but only if you approach it methodically. Pasting your whole codebase into a chat window and asking "fix this" is not a strategy. You need structure: understand first, protect behavior with tests, transform with a plan, then verify everything. That's the process Refactor Pilot Framework gives you.
What You Get
- A four-phase methodology that mirrors how senior engineers refactor, augmented with AI at every step
- 17 ready-to-use prompt templates for codebase analysis, test generation, refactor planning, code transformation, and design pattern identification — including file-type-specific variants for components, configs, utilities, and stylesheets
- Automation scripts (Bash) for extracting project metadata, mapping file structures, capturing baselines, and analyzing code — zero dependencies, runs on any Unix system
- Claude Code skills with progressive disclosure (quick decision trees + reference docs) for a fully integrated refactoring workflow
- Strategy guides for model selection, code anonymization, and creating domain-expert skills
- Checklists and guardrails to keep AI-assisted refactoring safe and reviewable
Quick Start
Option 1: Install via Claude Code Marketplace (Easiest)
If you have Claude Code installed, you can add the Refactor Pilot Framework marketplace and install the plugin directly from your terminal:
# Add the marketplace
/plugin marketplace add GuilhermeVozniak/refactor-pilot-framework
# Install the plugin
/plugin install refactor-pilot@refactor-pilot-marketplace
That's it. All five skills (analyze-codebase, generate-tests, refactor-code, verify-changes, design-patterns) will be available in your Claude Code sessions. Updates are pulled automatically when the marketplace is refreshed.
Option 2: Use the Prompt Templates (Any AI Tool)
- Clone this repo
- Open the
prompts/ directory
- Start with
00-define-requirements.md to establish your refactoring goals
- Continue with
01-project-metadata.md — copy the prompt, paste it into your AI tool along with your project files
- Work through the prompts sequentially (01 → 09), feeding outputs from earlier steps as context for later ones
- Use the specialized
03a-03d prompts for deeper analysis of specific file types
Option 3: Use the Scripts + Prompts
- Clone this repo
- Run the analysis scripts against your project:
./scripts/analyze-project.sh /path/to/your/project
./scripts/map-file-structure.sh /path/to/your/project
./scripts/generate-file-summaries.sh /path/to/your/project
./scripts/capture-baselines.sh /path/to/your/project
- Feed the script outputs into the prompt templates for deeper analysis
Option 4: Install Claude Code Skills
Prerequisites: Claude Code must be installed on your system.
Recommended approach — clone the full repo alongside your project:
# Clone Refactor Pilot Framework somewhere accessible
git clone https://github.com/GuilhermeVozniak/refactor-pilot-framework.git ~/refactor-pilot-framework
GuilhermeVozniak