refactor-pilot

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)

1. Clone this repo
2. Open the prompts/ directory
3. Start with 00-define-requirements.md to establish your refactoring goals
4. Continue with 01-project-metadata.md — copy the prompt, paste it into your AI tool along with your project files
5. Work through the prompts sequentially (01 → 09), feeding outputs from earlier steps as context for later ones
6. Use the specialized 03a-03d prompts for deeper analysis of specific file types

Option 3: Use the Scripts + Prompts

1. Clone this repo
2. 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
   

3. 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