How to Migrate a Legacy Module with Augment Code
Augment Code is at its best on the kind of task that is too big for a chat window and too boring for a Friday afternoon: taking a legacy module and moving it to a newer framework, a newer language version, or a different ORM.
The trap is asking for the whole migration at once. That produces an enormous diff nobody can review and a regression nobody can locate. Below is a migration routine that keeps the work in reviewable pieces.
Step 1: ask for a dependency map, not code
First prompt: “List every file that imports or is imported by legacy/billing. For each, what does it use?”
The answer tells you the actual blast radius, which is usually two to three times bigger than the folder the module lives in. Files that reach in through a single function are easy; files that reach into private helpers are the ones that break.
Save that map. Every later prompt can reference it.
Step 2: write a characterisation test before touching anything
A characterisation test records what the code does today, bugs included. Ask the assistant to generate tests from the existing behaviour of the module’s public functions, using current outputs as the expected values — not what the behaviour should be.
Run them. If some fail on first run, those failures are undocumented behaviour and you now know where the risk is. Keep the test file untouched for the whole migration; it is your referee.
Step 3: convert in slices, one file at a time
Work through the map in dependency order — leaf files first. For each file:
- Ask for the conversion with explicit constraints: same public signature, same error types, no new dependencies.
- Run the characterisation tests.
- Commit. One commit per file, message naming the file.
Thirty small commits beat one 4,000-line commit, even if it feels slower. You can bisect thirty commits. You cannot bisect a diff that touches everything.
Step 4: keep the interface stable until the end
Resist the urge to improve names, split long functions, or fix inconsistencies during the conversion. Do the mechanical move first; cleanup is a separate pass once everything compiles and tests pass.
When you do the cleanup pass, ask for one change type at a time (renames, then extraction, then dead code removal). Mixed prompts produce mixed diffs.
What does it get wrong on migrations?
Error semantics. A converted function often raises the new framework’s exception where the old one returned a sentinel. Tests that check happy paths pass; error-path tests catch it, and only if you wrote them.
Async boundaries. Moving synchronous code to an async interface is where the model produces code that awaits in the wrong place and deadlocks under load. Load-test the migrated module with real concurrency before shipping.
Framework idioms it has seen less of. Rarely-used APIs get plausible-but-wrong treatment; verify against the current docs on anything unfamiliar.
When not to use AI for the migration
The people who wrote the legacy module usually know where the landmines are. If you have one of them available for two days of pairing, that beats a week of AI conversion on the parts that need judgement.
If the module has no tests and no one understands it, write tests first — either by hand or with the assistant — before converting a single line.
Quick Summary
- Start with a dependency map prompt, not a conversion prompt; blast radius is usually 2–3× the module folder.
- Write characterisation tests that capture current behaviour, bugs included, and never edit them mid-migration.
- Convert leaf files first, one commit per file, with public signatures held stable.
- Expect trouble in error semantics and sync-to-async boundaries; load-test before shipping.
- Defer all naming and structure cleanup to a separate pass.
