Refactoring Modernization Migration — Claude Code Guide

Three different modes of working with change

Refactoring changes internal structure without intentionally changing the external contract. Modernization improves or replaces parts of a legacy system, often keeping business behavior and integration boundaries stable. Migration moves a system or slice from a source state to a target state: another runtime version, framework, platform, API, format, or environment.

These modes can overlap, but they are not synonyms. A migration may require refactoring or modernization, but changing a version or platform alone does not prove that a rewrite or production rollout was completed.

Comparing scope and evidence

Mode	Primary goal	What we preserve	Key evidence
Refactoring	Fix internal structure	External behavior and contract	Diff, focused tests, characterization
Modernization	Reduce legacy constraints or update capability	Agreed business behavior and boundaries	Baseline, seams, risk gates
Migration	Move from source to target state	Compatibility, observable behavior, and data within scope	Version evidence, compatibility analysis, pilot checks

Discovery before a migration decision

name the source and target: versions, runtime, framework, build, or platform;
record which boundary is actually moving and what remains outside scope;
separate confirmed facts from assumptions and unknowns;
define which contract must remain stable and how to observe it;
do not call ordinary renaming or internal movement a migration without a source-to-target change.

When modes must not be mixed

If migration discovery finds a separate business requirement, bug fix, or broad cleanup, do not silently add it to the migration scope. Move the work into a separate decision so that compatibility analysis and behavior comparison remain understandable.

The migration brief in this guide is a documented example: it demonstrates a way of thinking and document fields, but does not describe an upgrade actually performed in a specific repository.