Most legacy rewrites do not fail because the new code is bad. They fail because a rule the business depended on never made it across. Nobody wrote it down, so nobody rebuilt it.
The short answer
Legacy rewrites lose business rules because many rules exist only in the running system, not in any document. Capture behavior first, have the business owner approve it as a spec, and prove the rebuild with parity tests.
The rule nobody wrote down
Every system that has run a business for twenty years carries rules that exist only in its behavior. Someone added them after an audit, an incident or a phone call, and the reason left with that person.
BHV-0904
Stock count variances above 2% need a supervisor’s approval.
Rules like this one are why a rewrite can pass every test you wrote and still fail the business. The tests check what you knew. The rule is what you did not know.
Three kinds of rewrite
Follow BHV-0904 through three ways of rebuilding the same system.
- Lost
Manual rewrite
Nobody knows the rule exists, so it is never rebuilt. Someone notices months after go-live.
- Changed, unnoticed
AI coding tools alone
The batch job is rewritten and its generated tests pass. The approval step is gone, and nothing flags it.
- Caught before the rebuild
Rules captured first
The rule is found in recorded month-end runs, written into the spec the owner approves and marked critical.
The difference is not the quality of the code. It is whether anyone knew the rule was there before the code was written.
Start from behavior, not documents
Documents describe what a system was meant to do. Code shows what it does, but not why. The running system shows both, so start there: read the code, replay recorded traffic in a test environment, and write each rule down as a behavior with its evidence.
claims.cblLegacy, COBOL
1PAYOUT-CALC SECTION.2 COMPUTE PAY-AMT =3 FUNCTION MIN(CLAIM-AMT PAYOUT-CAP)BHV-02114 IF FRAUD-SCORE > 70BHV-02175 PERFORM HOLD-PAYMENT6 END-IFWhen a rule never appears in the recordings, say so. Mark it as needing evidence and find it somewhere else, such as historical records, before anything is rebuilt.
Let the owner approve the rules
A list of behaviors is still a guess until the person who owns the business process signs it. That signature turns an inventory into a spec, and the spec becomes the only thing agents build to.
A rule that nobody has approved is still a guess.
It also changes the conversation. Instead of asking engineers whether the new system is right, you ask the business owner whether these are their rules.
Prove it before go-live
Once the spec is approved, every rebuilt behavior needs proof. Replay the same recorded runs against the new system and compare the results, behavior by behavior. Fix every mismatch and run it again. Then let the business owner accept the parity report, one wave at a time, while the old system stays ready to take back over.
In CrewPE
This is the modernization thread: capture, Gate 1 for the spec, rebuild and parity, then Gate 2 for each wave.
See how modernization worksQuestions teams ask
- Why do legacy rewrites lose business rules?
- Because many rules were never documented. They were added to the code after audits, incidents or customer requests, and they exist only in how the running system behaves. A rewrite that starts from documents or from the code alone can miss them.
- Do AI coding tools solve the problem?
- Not on their own. They can rewrite code quickly and generate tests that pass, but the tests only check what the tool understood. A rule the tool did not notice can disappear without any test failing.
- How do you prove a rebuilt system behaves the same?
- Record real runs of the old system in a test environment, replay them against the new one, and compare the results behavior by behavior. Every mismatch is fixed and re-run before the business owner accepts the wave.
Parani Raja
Co-founder of EnWithAI, working on legacy modernization: keeping what old systems know when they are rebuilt.