Use this free hidden-rule checklist before asking Claude Code to modernize a critical legacy system.
From the hidden-behaviour video
Start with seven sources of evidence.
Code is only one of them. Check runtime behaviour, production data, scheduled work, downstream contracts, operator knowledge, verification evidence, and rollback authority before Claude Code changes a critical system.
A convincing code explanation is not enough. Use these questions for one bounded modernization slice and record the evidence behind every answer.
1. What does the system do at runtime that the code alone does not explain?
Inspect logs, traces, metrics, feature flags, runtime configuration, retry behaviour, timeouts, side effects, and failure recovery. Capture examples before changing the implementation.
2. Which rules are encoded in production data?
Look for sentinel values, old status codes, special customer records, manually corrected fields, duplicate identifiers, and date boundaries. Build synthetic fixtures that reproduce the behaviour without copying sensitive data.
3. Which scheduled jobs change the result later?
List batch jobs, reconciliation tasks, file drops, delayed messages, cleanup routines, and end-of-day processing. A synchronous replacement can appear correct while breaking the next scheduled run.
4. Who depends on undocumented output?
Check API consumers, reports, exports, database readers, operations scripts, and manual procedures. Record the fields, ordering, timing, and error behaviour that each consumer relies on.
5. What do operators know that the repository does not?
Ask which alerts they ignore, which incidents recur, what they repair by hand, and when they refuse to run a process. Turn those answers into explicit examples and acceptance criteria.
6. What evidence will prove that the replacement is equivalent?
Choose reviewed golden masters, characterization tests, contract tests, invariants, and differential comparisons. Bind the evidence to a fixed input set and a specific revision.
7. Who can stop or reverse the change?
Name the person with cutover authority. Define the rollback trigger, the old path that remains available, and the evidence required before traffic moves.
Suppose a settlement service rounds a fee differently for a small set of older accounts. The branch is absent from the current application code. A nightly correction job reads a flag stored in the database and adjusts the ledger later.
A code-only rewrite misses the correction. A useful discovery pass finds the data flag, the nightly job, the resulting ledger entries, and the operator procedure used when the job fails. Those facts become fixtures, characterization tests, and a differential comparison before the replacement receives production traffic.
Claude Code can help collect the evidence and implement the bounded change. It should not decide which behaviour the business is allowed to lose.
Leanpub offers a 60-day refund guarantee. A paperback edition is also available on Amazon UK.