Leanpub Header

Skip to main content
Go to Leanpub.com

Claude Code for Legacy Modernization

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

Claude Code for Legacy Modernization
This book is 87% completeLast updated on 2026-08-17
Thomas De Vos

Legacy modernization is an evidence problem before it is a code-generation problem. Use Claude Code to recover hidden behavior, build a verification harness, and move critical systems in controlled, reversible slices without handing production decisions to AI. Includes 26 practical chapters, 86 diagrams, and a runnable companion lab.

Minimum price

$17.99

$39.00

You pay

Author earns

$

Also available for 1 book credit with a Reader Membership

PDF
EPUB
WEB
APP
About

About

About the Book

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 behavior matters, who still depends on it, or whether a replacement is safe to operate.

Claude Code for Legacy Modernization is a practical field handbook for changing critical systems without pretending that the repository is a complete specification. It shows you how to recover hidden business rules, reconstruct runtime behavior, identify unknown consumers, and turn those findings into evidence that engineers and decision owners can review.

The method follows one bounded modernization slice from discovery to retirement.

You will learn how to:

recover business rules from code, data, runtime flows, side effects, and operational knowledge; establish a trustworthy baseline before asking AI 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;
compare legacy and replacement behavior before cutover;
define acceptance criteria and rollback triggers in advance;
cut over under named human authority;
measure accepted outcomes and retire the old path without losing the evidence trail.

Claude Code assists with repository discovery, test preparation, bounded implementation, old-and-new comparison, contradiction checks, and evidence assembly. It does not decide which behavior is correct or authorize a production change. Architects, domain owners, security reviewers, and operational leaders keep those decisions.

The book follows Northstar Settlements, a fictional financial-services system, through a complete modernization thread. The companion lab lets you reproduce the baseline, inspect the legacy behavior, run the tests, expose an intentional replacement mismatch, and complete the exercises in your own branch.

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;
  • Claude Code project controls and compatibility wrappers;
  • reusable schemas, checklists, evidence records, and decision templates.


Companion lab

Northstar Modernization Lab

This book is for software engineers, architects, technical leads, quality engineers, and platform or operations professionals responsible for systems that are valuable, difficult to understand, and dangerous to change.

### Continue with the companion guides

Need the wider production-agent engineering foundation? Claude Code: Building Production Agents That Actually Scale covers tools, MCP, hooks, permissions, evals, observability, cost engineering, and multi-agent operations.


Need both books? The Claude Code Production Engineering bundle combines that production-agent guide with this complete legacy-modernization handbook.

Share this book

Categories

Software EngineeringSystems EngineeringLarge language models

Feedback

Email the Author

Bundle

Bundles that include this book

Author

About the Author

Thomas De Vos

Contents

Table of Contents

Preface

  1. The Trap
  2. The Reality
  3. The Engine
  4. Why this is a handbook
  5. One bounded flow
  6. What changes in this edition
  7. How Claude Code participates
  8. What proof means here
  9. The result I want

How to use this handbook

  1. Use the full route first
  2. Work in chapter-sized states
  3. Keep one knowledge and verification thread
  4. Use the standard chapter contract
  5. Divide machine checks from human decisions
  6. Use the handbook on your own system
  7. Choose a shorter route carefully
  8. Use the appendices as working material
  9. Know when the work is complete

Chapter 1: Knowledge Recovery and the Verification Harness

  1. Chapter outcome
  2. Phase framing: Start safely
  3. Practical chapter contract
  4. Apply the contract

Chapter 2: Build the modernization workspace

  1. Chapter outcome
  2. Practical chapter contract
  3. Apply the contract

Chapter 3: Set Claude Code boundaries

  1. Chapter outcome
  2. Practical chapter contract
  3. Apply the contract

Chapter 4: Record the baseline before asking for changes

  1. Chapter outcome
  2. Practical chapter contract
  3. Apply the contract

Chapter 5: Map code and runtime paths

  1. Chapter outcome
  2. Phase framing: Knowledge Recovery
  3. Practical chapter contract
  4. Apply the contract

Chapter 6: Trace data, messages, batch flows, and side effects

  1. Chapter outcome
  2. Practical chapter contract
  3. Apply the contract

Chapter 7: Extract rules and recover operational knowledge

  1. Chapter outcome
  2. Practical chapter contract
  3. Apply the contract

Chapter 8: Build characterisation tests

  1. Chapter outcome
  2. Phase framing: Build the Verification Harness
  3. Practical chapter contract
  4. Apply the contract

Chapter 9: Create a reviewed golden master

  1. Chapter outcome
  2. Practical chapter contract
  3. Apply the contract

Chapter 10: Protect consumer contracts

  1. Chapter outcome
  2. Practical chapter contract
  3. Apply the contract

Chapter 11: Test invariants and metamorphic relations

  1. Chapter outcome
  2. Practical chapter contract
  3. Apply the contract

Chapter 12: Create safe replay data

  1. Chapter outcome
  2. Practical chapter contract
  3. Apply the contract

Chapter 13: Define acceptance and rollback

  1. Chapter outcome
  2. Practical chapter contract
  3. Apply the contract

Chapter 14: Find and create a seam

  1. Chapter outcome
  2. Phase framing: Change one slice
  3. Practical chapter contract
  4. Apply the contract

Chapter 15: Design the strangler path

  1. Chapter outcome
  2. Practical chapter contract
  3. Apply the contract

Chapter 16: Evolve APIs and schemas

  1. Chapter outcome
  2. Practical chapter contract
  3. Apply the contract

Chapter 17: Preserve semantics across language and framework changes

  1. Chapter outcome
  2. Practical chapter contract
  3. Apply the contract

Chapter 18: Migrate data without splitting truth

  1. Chapter outcome
  2. Practical chapter contract
  3. Apply the contract

Chapter 19: Operate bounded human and Claude Code roles

  1. Chapter outcome
  2. Phase framing: Execute the Verification Harness
  3. Practical chapter contract
  4. Apply the contract

Chapter 20: Build the differential harness

  1. Chapter outcome
  2. Practical chapter contract
  3. Apply the contract

Chapter 21: Challenge the tests with mutation testing

  1. Chapter outcome
  2. Practical chapter contract
  3. Apply the contract

Chapter 22: Run old and new paths in parallel

  1. Chapter outcome
  2. Practical chapter contract
  3. Apply the contract

Chapter 23: Reconcile outputs, state, and side effects

  1. Chapter outcome
  2. Practical chapter contract
  3. Apply the contract

Chapter 24: Produce evidence, cut over, and roll back

  1. Chapter outcome
  2. Practical chapter contract
  3. Apply the contract

Chapter 25: Measure accepted outcomes

  1. Chapter outcome
  2. Phase framing: Finish the modernisation
  3. Practical chapter contract
  4. Apply the contract

Chapter 26: Decommission the old path

  1. Chapter outcome
  2. Practical chapter contract
  3. Apply the contract

Appendix A: Claude Code setup for bounded modernization work

  1. What this setup controls
  2. Start with admission, not installation
  3. Record the actual installation
  4. Create the workspace structure
  5. Write concise project instructions
  6. Apply project permissions
  7. Add a deterministic direct-file hook
  8. Define one bounded discovery task
  9. Run the task with explicit controls
  10. Review and reject deliberately
  11. Promote work only through human gates
  12. Setup acceptance checklist
  13. Failure file: the copied allowlist
  14. My position
  15. Practice exercises
  16. Notes

Appendix B: Repeatable task contracts

  1. What a task contract must settle
  2. Use one contract for one evidence dependency
  3. Store contracts as versioned files
  4. The canonical contract
  5. Write the prompt from the contract
  6. Constrain the return without confusing shape with truth
  7. Four reusable task profiles
  8. Run a contract without losing the execution record
  9. Validate syntax, then validate evidence
  10. Review with a disposition record
  11. Rejection tests for the contract system
  12. Manage contract change
  13. My position
  14. Practice exercises
  15. Notes

Appendix C: Test scaffolding

  1. Start with the evidence question
  2. Use a repository layout that exposes authority
  3. Define one case as data
  4. A small differential harness
  5. Test the harness before trusting it
  6. Add properties without inventing the domain
  7. Protect interfaces with contract scaffolds
  8. Record side effects rather than suppressing them silently
  9. Use mutation testing to challenge the oracle
  10. Bound Claude Code’s role
  11. Retain the run as evidence
  12. Failure file: the shared oracle
  13. My position
  14. Practice exercises
  15. Notes

Appendix D: Prompt and review catalogue

  1. How to use the catalogue
  2. Pattern 1: Read-only discovery
  3. Pattern 2: Dependency mapping
  4. Pattern 3: Business-rule extraction
  5. Pattern 4: Contradiction check
  6. Pattern 5: Characterisation-test design
  7. Pattern 6: Contract-test design
  8. Pattern 7: Bounded implementation
  9. Pattern 8: Adversarial review
  10. Pattern 9: Unsupported-claim check
  11. Pattern 10: Evidence packaging
  12. Bad prompt counterexamples
  13. Review catalogue
  14. Preserve human authority

Appendix E: Squad and programme templates

  1. Choose the smallest template that fits the decision
  2. Template 1: Pilot squad charter
  3. Template 2: Standard delivery squad charter
  4. Template 3: Multi-squad programme charter
  5. Template 4: Role charter
  6. Template 5: Responsibility map
  7. Template 6: Decision-rights map
  8. Template 7: Sprint evidence contract
  9. Template 8: Review-capacity plan
  10. Template 9: Scarce-specialist allocation
  11. Template 10: Handoff record
  12. Template 11: Escalation record
  13. Template 12: Programme coordination board
  14. Template 13: Full-flow time and resource baseline
  15. Operating the templates as one system
  16. Final checks before use

Appendix F: Source and version register

  1. Use three evidence states
  2. Record a claim
  3. Current tested compatibility register
  4. Add another tool or source
  5. Keep the boundary visible

Companion assets and reproducibility

  1. What is supplied
  2. Establish the local identity
  3. Run the supplied gates
  4. Use the verification helper
  5. Use the Claude compatibility helper
  6. Distribution note

Glossary

About the author

Leave an evidence trail

The Leanpub 60 Day 100% Happiness Guarantee

Within 60 days of purchase you can get a 100% refund on any Leanpub purchase, in two clicks.

See full terms...

Earn $8 on a $10 Purchase, and $16 on a $20 Purchase

We pay 80% royalties on purchases of $7.99 or more, and 80% royalties minus a 50 cent flat fee on purchases between $0.99 and $7.98. You earn $8 on a $10 sale, and $16 on a $20 sale. So, if we sell 5000 non-refunded copies of your book for $20, you'll earn $80,000.

(Yes, some authors have already earned much more than that on Leanpub.)

In fact, authors have earned over $15 million writing, publishing and selling on Leanpub.

Learn more about writing on Leanpub

Free Updates. DRM Free.

If you buy a Leanpub book, you get free updates for as long as the author updates the book! Many authors use Leanpub to publish their books in-progress, while they are writing them. All readers get free updates, regardless of when they bought the book or how much they paid (including free).

Most Leanpub books are available in PDF (for computers) and EPUB (for phones, tablets and Kindle). The formats that a book includes are shown at the top right corner of this page.

Finally, Leanpub books don't have any DRM copy-protection nonsense, so you can easily read them on any supported device.

Learn more about Leanpub's ebook formats and where to read them

Write and Publish on Leanpub

You can use Leanpub to easily write, publish and sell in-progress and completed ebooks and online courses!

Leanpub is a powerful platform for serious authors, combining a simple, elegant writing and publishing workflow with a store focused on selling in-progress ebooks.

Leanpub is a magical typewriter for authors: just write in plain text, and to publish your ebook, just click a button. (Or, if you are producing your ebook your own way, you can even upload your own PDF and/or EPUB files and then publish with one click!) It really is that easy.

Learn more about writing on Leanpub