Behaviour is compared with the legacy system before cutover
The new service is run against real traffic alongside the old one, and the differences are examined, before it serves users.
HighChecked by hand
- Applies to:
- Every service
- Rule id:
- architecture.parity-verified
Why it matters
Nobody knows everything a legacy system does. Years of special cases live in its code and in what its users have come to expect. A rewrite from the specification reproduces the specification, not the system. Comparing the two on real traffic is the only way to find what was missed before customers do.
How to apply it
- Send a copy of production requests to the new service (shadow traffic) and discard its responses.
- Compare results with the legacy system's automatically, and log every difference.
- Sort the differences: bugs in the new service, bugs in the old one that you choose to keep or fix, and noise such as timestamps.
- For writes, shadow into a separate store or compare the resulting state. Never write twice to the same place.
- Set a bar for cutover: for example, a week with no unexplained difference.
Example
For ten days the proxy mirrored /api/pricing/quote to the new pricing service. A comparator found 0.4% of quotes differed: a rounding rule for three currencies and an undocumented staff discount. Both were fixed, and cutover began after seven days with no differences.
References
Checklists with this rule
Related agent skill: strangler-fig-migration