Make the next change small enough to understand and verify. Modernization starts with a useful outcome and evidence about the behavior you are about to touch.
Protect the behavior
Characterization tests capture what the system does today. They do not prove it is correct, so review surprising behavior with the business owner, and keep an intentional bug fix separate from a refactor. Before extracting an invoice calculator, capture rounding, discounts and boundary cases, then move the calculation behind an interface and compare results.
Choose the slice
Choose one high-value boundary, define the expected result, and decide how to recover if the release misbehaves. Account for temporary adapters and duplicated paths, including when they will be removed.
Translate at the boundary
When the slice talks to an outside system, translate its concepts before they spread through your own model. An adapter reads a carrier’s status code D against that carrier’s contract and produces your DeliveryConfirmed, so domain code never repeats carrier-specific conditions. Send unknown codes to an explicit error path instead of guessing.
Agents in old code
An agent reads the code, not the history. Addy Osmani sorts an older codebase into zones before agents work in it:
- Green: well tested, modern and isolated. Agents work in tight loops.
- Yellow: mixed quality. Agents change code only after characterization tests pin today’s behavior.
- Red: billing, authorization, or anything only production understands. People lead; agents assist.
For yellow and red work, run a read-only research pass first and keep a short memo of the rules the code doesn’t state. Pin behavior in a separate pass, because tests written by the session that changes the code can encode what it just invented.
Related: Record the decision · Make architecture rules testable