AdvancedAI Coding Assistants · Lesson 9 of 10 · Updated ·
Refactoring Legacy Code with AI — Characterization Tests, Small Steps and Behaviour Checks
Every company has legacy code: old, working code that nobody wants to touch because it is messy and has no tests. AI assistants are very good at producing cleaner versions of such code. The danger is that a "cleaner" version can behave differently, and the difference only shows up for a few inputs that nobody tried. This lesson shows a safe method you can use in internships and jobs.
1. What refactoring means
Refactoring means changing the structure of code without changing its behaviour: same inputs, same outputs, same errors. Renaming variables, extracting functions and removing duplication are refactors. Fixing a bug or adding a feature is not a refactor; it is a behaviour change, and it should be a separate step.
Keeping these apart matters with AI. If you ask "clean this up", a model may also "fix" things it thinks are wrong, and you can no longer tell which changes were intended.
2. Step 1: pin the current behaviour (characterization tests)
Here is a real-looking legacy function from a college fee system. It is ugly, but the accounts office has used it for years:
def fee_legacy(cgpa, sports, hostel, late_days):
total = 60000
if cgpa >= 9.0:
total = total - total * 50 // 100
else:
if cgpa >= 8.0:
total = total - total * 25 // 100
if sports == True:
total = total - 10000
if total < 0:
total = 0
if hostel:
total = total + 40000
if late_days > 0:
late = late_days * 500
if late > 5000:
late = 5000
total = total + late
return total
print(fee_legacy(9.2, False, True, 0))
print(fee_legacy(8.0, True, False, 12))
70000
40000
A characterization test (also called a golden master test) does not ask "is this right?". It records what the code does today, for many inputs, so that any change in behaviour is detected. Choose inputs around every boundary you can see in the code: just below, at and just above each threshold, plus odd values such as negative numbers.
from itertools import product
CGPAS = [6.0, 7.99, 8.0, 8.5, 8.99, 9.0, 9.5, 10.0] # around both thresholds
LATE_DAYS = [-2, 0, 1, 9, 10, 11, 30] # around the Rs 5000 cap, plus a bad value
cases = list(product(CGPAS, [False, True], [False, True], LATE_DAYS))
print(len(cases), "cases")
print(cases[:3])
224 cases
[(6.0, False, False, -2), (6.0, False, False, 0), (6.0, False, False, 1)]
224 combinations take a fraction of a second to run. You would never write 224 hand-made unit tests, but you do not need to: the old function provides every expected answer.
3. Step 2: ask for a refactor, then compare
Suppose an AI assistant was asked to "make this function clean and Pythonic" and produced the version below. It looks better and passes a quick glance. The golden master compares it with the old one on every case:
from itertools import product
def fee_legacy(cgpa, sports, hostel, late_days):
total = 60000
if cgpa >= 9.0:
total = total - total * 50 // 100
else:
if cgpa >= 8.0:
total = total - total * 25 // 100
if sports == True:
total = total - 10000
if total < 0:
total = 0
if hostel:
total = total + 40000
if late_days > 0:
late = late_days * 500
if late > 5000:
late = 5000
total = total + late
return total
def fee_ai(cgpa, sports, hostel, late_days): # the AI's "clean" version
discount = 0.5 if cgpa > 9.0 else 0.25 if cgpa >= 8.0 else 0.0
total = 60000 - (10000 if sports else 0)
total = int(total * (1 - discount))
total += 40000 if hostel else 0
total += min(late_days * 500, 5000)
return max(total, 0)
CGPAS = [6.0, 7.99, 8.0, 8.5, 8.99, 9.0, 9.5, 10.0]
LATE_DAYS = [-2, 0, 1, 9, 10, 11, 30]
cases = list(product(CGPAS, [False, True], [False, True], LATE_DAYS))
diffs = [c for c in cases if fee_legacy(*c) != fee_ai(*c)]
print(f"{len(diffs)} of {len(cases)} cases changed")
for case in [(9.0, False, False, 0), (8.5, True, False, 0), (6.0, False, False, -2)]:
print(case, "old:", fee_legacy(*case), "new:", fee_ai(*case))
116 of 224 cases changed
(9.0, False, False, 0) old: 30000 new: 45000
(8.5, True, False, 0) old: 35000 new: 37500
(6.0, False, False, -2) old: 60000 new: 59000
Three separate behaviour changes, each hiding in a line that "looks the same":
- Boundary:
cgpa > 9.0instead of>= 9.0. A student with exactly 9.0 loses half her scholarship and pays ₹15,000 more. - Order of operations: the AI subtracts the ₹10,000 sports concession before the percentage discount, so sports students get less concession than before.
- Bad input: for negative
late_daysthe old code added nothing; the new code subtracts ₹1,000.
Was the old behaviour "correct"? Maybe the sports rule really should apply first. That is a question for the accounts office, not something a refactor should change silently. A refactor must reproduce the old behaviour exactly; any fix is a separate, deliberate, reviewed change.
4. Step 3: a refactor that passes
Feeding the three failing cases back to the AI (inputs, old output, new output) gives a version that keeps the readability and the behaviour:
from itertools import product
def fee_legacy(cgpa, sports, hostel, late_days):
total = 60000
if cgpa >= 9.0:
total = total - total * 50 // 100
else:
if cgpa >= 8.0:
total = total - total * 25 // 100
if sports == True:
total = total - 10000
if total < 0:
total = 0
if hostel:
total = total + 40000
if late_days > 0:
late = late_days * 500
if late > 5000:
late = 5000
total = total + late
return total
BASE_FEE, HOSTEL_FEE = 60000, 40000
SPORTS_CONCESSION, LATE_FEE_PER_DAY, LATE_FEE_CAP = 10000, 500, 5000
def scholarship_percent(cgpa):
if cgpa >= 9.0:
return 50
if cgpa >= 8.0:
return 25
return 0
def fee_refactored(cgpa, sports, hostel, late_days):
total = BASE_FEE - BASE_FEE * scholarship_percent(cgpa) // 100
if sports:
total = max(total - SPORTS_CONCESSION, 0) # concession after scholarship, as before
if hostel:
total += HOSTEL_FEE
total += min(max(late_days, 0) * LATE_FEE_PER_DAY, LATE_FEE_CAP)
return total
CGPAS = [6.0, 7.99, 8.0, 8.5, 8.99, 9.0, 9.5, 10.0]
LATE_DAYS = [-2, 0, 1, 9, 10, 11, 30]
cases = list(product(CGPAS, [False, True], [False, True], LATE_DAYS))
diffs = [c for c in cases if fee_legacy(*c) != fee_refactored(*c)]
print(f"{len(diffs)} of {len(cases)} cases changed")
0 of 224 cases changed
Zero differences. Notice the improvements that are safe to make: named constants instead of magic numbers, a small scholarship_percent function that can be unit-tested on its own, and a comment recording the order rule that the first attempt broke. Also notice what was kept: integer arithmetic (// 100), because switching to floats could change results by a rupee through rounding.
5. Prompts and habits that keep refactors safe
A good refactoring prompt states the goal, the constraint and the proof:
Refactor fee_legacy for readability. Constraints:
- Behaviour must stay IDENTICAL for every input, including odd ones (negative late_days).
- Keep integer arithmetic. Do not fix anything you think is a bug; list it separately instead.
- One change at a time: first extract constants, then the scholarship rule.
I will compare old and new outputs on 224 cases before accepting.
| Safe to hand to AI (with the golden master) | Needs a human decision |
|---|---|
| renaming, extracting functions and constants | changing a rule that "looks wrong" |
| removing duplicated code | changing rounding or number types |
| replacing nested ifs with clearer structure | changing how bad input is handled |
| adding type hints and docstrings | anything the business or users depend on |
Habits that help:
- Small steps, one commit each. If the golden master fails, you know which step broke it, and
git revertis easy. - Read the diff, not just the new file. Agentic tools may touch other files too.
- Keep the characterization tests after the refactor. Later, replace them gradually with clear unit tests that state the intended rules.
- For code with side effects (database writes, emails), record the calls made, not just the return value, or run against a test database.
Common mistakes
- Asking for "clean up and fix bugs" in one step, so refactor and behaviour changes are mixed together.
- Testing the refactor on two or three happy-path inputs only.
- Choosing test inputs far away from the thresholds (8.5 and 9.5, but never exactly 8.0 or 9.0).
- Accepting a change because the new code "obviously" does the same thing.
- "Fixing" old behaviour that other systems or people rely on, without asking the owner.
Quick recap
- A refactor changes structure, never behaviour; bug fixes are separate steps.
- Characterization (golden master) tests record what the code does today for many inputs.
- Choose inputs at, just below and just above every boundary, plus invalid values.
- Compare old and new outputs on every case; any difference is a failed refactor until a human approves it.
- Small steps, one commit each, and always read the diff.