Recover Hidden Business Rules, Build a Verification Harness, and Modernize Critical Systems Without Breaking Production

Get the book on Leanpub

Now available on Leanpub

Modernize the system without guessing what it does.

Legacy modernization rarely fails because a team cannot generate enough new code. It fails because nobody can prove which behaviour matters, who still depends on it, or whether a replacement is safe to operate.

Claude Code for Legacy Modernization gives architects, engineering leaders, and modernization teams an evidence-led method for changing critical systems without pretending the repository is a complete specification.

Get the book on Leanpub Get the two-book bundle

Cover of Claude Code for Legacy Modernization by Thomas De Vos

The problem this book solves

The dangerous part of modernization is not writing the replacement. It is deciding what the replacement must preserve.

The behaviour that matters may be spread across source code, data, scheduled jobs, operational workarounds, downstream consumers, undocumented exceptions, and the knowledge of people who have kept the system alive for years. Asking an AI assistant to rewrite that system before recovering the evidence only makes the guesswork faster.

This book shows you how to put evidence before code.

What you will learn

You will learn how to:

  • recover business rules from code, data, runtime flows, side effects, and operational knowledge;
  • establish a trustworthy baseline before asking Claude Code to change anything;
  • build characterization tests, reviewed golden masters, contract tests, invariants, and differential comparisons;
  • find or introduce a safe implementation seam;
  • create a reversible strangler path rather than attempt a high-risk rewrite;
  • compare legacy and replacement behaviour before cutover;
  • define acceptance criteria and rollback triggers in advance;
  • cut over under named human authority; and
  • retire the old path without losing the evidence trail.

What Claude Code does—and does not do

Claude Code can accelerate repository discovery, prepare tests, implement bounded changes, compare old and new behaviour, check contradictions, and assemble evidence for review.

It does not decide which behaviour is correct. It does not decide which risk the business should accept. It does not authorize a production cutover. Those decisions remain with architects, domain owners, security reviewers, operational leaders, and accountable change authorities.

That boundary is not a limitation of the method. It is what makes AI-assisted modernization usable in serious environments.

Follow one modernization slice from discovery to retirement

The book follows Northstar Settlements, a fictional financial-services system, through one complete modernization thread. You will see how the team discovers hidden behaviour, establishes a baseline, introduces a verification harness, exposes a replacement mismatch, controls the migration, and preserves the evidence behind the decision.

The companion lab lets you reproduce that work rather than merely read about it.

What is included

  • more than 790 pages of practical guidance;
  • 26 connected modernization chapters;
  • 86 architecture, workflow, and evidence diagrams;
  • a runnable GitHub exercise repository;
  • synthetic fixtures, a retained golden master, and differential tests; and
  • Claude Code project controls and compatibility wrappers.

Who this is for

This is written for:

  • enterprise and solution architects responsible for modernization strategy;
  • engineering leaders who need progress without losing operational control;
  • developers working in unfamiliar or poorly documented legacy estates;
  • platform teams introducing AI-assisted engineering workflows;
  • risk, security, and change authorities in regulated environments; and
  • consultants who need a repeatable modernization method their clients can inspect.

It is particularly relevant when the system moves money, supports customers, feeds reporting, or contains years of undocumented business decisions.

Choose the right edition

If your immediate challenge is an existing system that is difficult to understand and dangerous to change, start with this book.

If you also need the production operating model for Claude Code agents—permissions, MCP, review, observability, rollback, and evidence—choose the two-book bundle.

Get Claude Code for Legacy Modernization See the Claude Code Production Engineering bundle

FAQ

Is this a prompt book?

No. Prompts are a small part of the work. The book is about recovering evidence, creating a verification harness, controlling change, and retaining human authority over production decisions.

Does the approach require a particular legacy technology?

No. The method is designed around behaviour, evidence, seams, contracts, and controlled migration. Those concerns apply across languages, databases, integration styles, and infrastructure generations.

Does it advocate a complete rewrite?

No. The book favours bounded, reversible slices. You prove behaviour, introduce a seam, compare old and new paths, define rollback conditions, and move authority only when the evidence supports it.

Is there a practical lab?

Yes. The Northstar Settlements companion lab includes synthetic fixtures, characterization tests, a retained golden master, differential comparisons, and exercises you can run in your own branch.