Code Refactoring Prompts: Clean Up Legacy Code with AI

Legacy code is where teams lose the most time — but it is also where AI saves the most time, if you prompt carefully. The key rule for refactoring with AI is simple: behaviour must stay identical, only structure should change.

1. Introduction

Refactoring is the art of improving the shape of code without changing what it does. AI tools are dangerously good at producing "improved" code that subtly changes behaviour — renaming variables, dropping seemingly redundant checks, or replacing a custom utility with a library function that has slightly different semantics. This tutorial teaches you how to prompt for behaviour-preserving refactors, and how to verify the AI actually preserved that behaviour.

2. The Concept Explained

A refactor is a controlled transformation: you start with code that works, change its structure, and end with code that still works exactly the same way. The four common refactor goals are readability, testability, performance, and safety (e.g. extracting magic numbers, adding type narrowing). A prompt should pick one of these as the primary goal so the AI knows what to optimise for.

Imagine renovating a house: you do not knock down a load-bearing wall on a hunch. You plan, prop it up, take one wall down, check the structure, then move on. AI refactoring works the same way — small, verifiable steps beat a single mega-rewrite every time.

3. The Problem Without This Technique

The instinctive prompt is "clean this up". The AI interprets that as licence to rewrite everything, often inventing new function signatures, changing return types, or silently fixing what it considers a bug.

refactor this and make it cleaner

function processOrders(orders) {
  let total = 0;
  for (var i = 0; i < orders.length; i++) {
    if (orders[i].status == "paid") {
      total = total + orders[i].amount;
    }
  }
  return total;
}

4. The Solution

Language: JavaScript (Node.js 20, ESM, no TypeScript)
Goal of refactor: readability only — do NOT change behaviour, name, or signature.

Current function:

```js
function processOrders(orders) {
  let total = 0;
  for (var i = 0; i < orders.length; i++) {
    if (orders[i].status == "paid") {
      total = total + orders[i].amount;
    }
  }
  return total;
}
```

Refactor constraints:
- Keep the function name `processOrders` and its parameter name `orders`
- Keep the return value identical for every input (including empty arrays)
- Use `===` instead of `==` only if it changes no behaviour for the data shape:
  `[{ status: string, amount: number }]`
- Prefer Array methods over imperative loops
- No new dependencies
- No try/catch unless I ask
- Output: the new function, plus a short bullet list of every change you made
  and why each one is safe

5. Step-by-Step Breakdown

1. Pick one refactor goal. Readability, testability, performance, or safety. Mixing goals leads to sprawling rewrites.
2. Freeze the public surface. Name, parameters, return type — explicitly tell the AI these may not change.
3. Specify the language and runtime. Modern JS features behave differently across Node versions, browsers, and bundlers.
4. List allowed and forbidden changes. "May use Array.reduce" / "may not add libraries" / "do not add try/catch".
5. Demand a changelog. Ask the AI to list every change and justify each one — this is your audit trail.
6. Run your tests after applying. If you don't have tests for the function, write them before refactoring. AI-assisted refactor without tests is gambling.

Tip: For larger refactors, ask the AI to propose the steps first ("List 4–6 small refactors I can apply one at a time, each behaviour-preserving"). Then execute them one prompt at a time. Big-bang rewrites are where bugs hide.

6. Practice Exercises

7. Key Takeaways