TL;DR
Rewrite a codebase from scratch only when the current system cannot reach a required outcome through bounded repair and the team can preserve critical behaviour, data and operations during replacement. First test an incremental boundary around the worst constraint. If replacement remains necessary, migrate one capability at a time, define parity from evidence and keep a rollback or coexistence route. A rewrite justified by dislike of old code usually underestimates hidden behaviour and the cost of running two systems.
In this article
- Diagnose the constraint before choosing replacement
- Count the behaviour the old system carries
- Compare repair, extraction and replacement
- Treat data migration as product work
- Define parity from outcomes, not matching screens
- Fund coexistence and the end of the old system
- Choose a rewrite for necessity, not morale
- Frequently Asked Questions
6 min read
A rewrite promises a clean start. It also removes years of encoded behaviour, including rules nobody documented and failures the old system already learned to survive. The new code may be easier to understand while still being less complete.
The question is when should you rewrite a codebase from scratch? Choose replacement only when a necessary outcome is structurally unreachable through repair, and when you have a credible migration plan for behaviour, data, users and operations. The age or appearance of the code is not enough.
Diagnose the constraint before choosing replacement
Teams often describe the entire codebase as the problem when one boundary, dependency or data model creates most of the pain. Trace recent difficult changes and incidents. Identify the recurring constraint and test whether a wrapper, extraction, upgrade or contained refactor can reduce it.
- The required product or regulatory outcome is explicit.
- The current structure that blocks it is demonstrated.
- Smaller containment or incremental repair has been evaluated.
- Hidden behaviour and external dependencies have been investigated.
- The organisation accepts the opportunity cost of replacement.
A short diagnostic spike should reduce uncertainty. It should not become an unofficial rewrite that commits the team before the decision is reviewed.
Count the behaviour the old system carries
Feature lists rarely describe a mature system. Behaviour also lives in validation order, default values, timing, retries, data cleanup, exports, support procedures and workarounds in connected systems. Users may depend on results nobody intended as a feature.
Build a behaviour inventory from several sources: production traces, tickets, tests, database constraints, support records, logs and interviews with operators. Classify each behaviour as required, intentionally changed, obsolete or unknown. Unknown behaviour is migration risk, not automatic scope.
The undocumented-codebase mapping method provides a practical way to trace one behaviour through code, data and effects before replacement.
Compare repair, extraction and replacement
A rewrite is one option on a spectrum. Repair may improve the existing design in place. Extraction can move a bounded capability behind a new interface. Replacement rebuilds the system or a major part and migrates users and data.
Comparison
| Option | Useful when | Main risk |
|---|---|---|
| Contain and repair | The constraint is local and behaviour can be protected | Improvements may not remove deeper coupling |
| Extract a capability | A stable seam and ownership boundary exist | Shared data can keep systems tightly coupled |
| Incremental replacement | Capabilities can move while old and new coexist | Temporary complexity lasts longer than planned |
| Full cut-over rewrite | Coexistence is impossible and scope is genuinely bounded | Long feedback gap and high parity risk |
Martin Fowler’s Strangler Fig pattern favours gradual replacement around an existing system to reduce cut-over risk. It is a strategy, not a guarantee. The team still has to prove the seam, compatibility and operating model.
Treat data migration as product work
Data is where clean rewrites meet history. The old database contains incomplete rows, legacy identifiers, duplicate records and meanings that changed over time. A new schema does not resolve those facts by itself.
Define how each important record maps, which system owns writes during coexistence, how changes are reconciled and how migration is verified. Include permissions, retention and audit needs. Rehearse with representative data and record rejects rather than silently dropping them.
A rollback may become impossible after external effects or irreversible transformation. In that case use compatibility windows, dual reads, staged ownership or a forward repair plan. State the point of no return before cut-over.
- Inventory critical behaviour and data, including unknowns.
- Establish a boundary where one capability can move.
- Define parity and intentional differences with proof methods.
- Rehearse data movement, failure and recovery.
- Move a limited slice, observe it and decide whether to continue.
Define parity from outcomes, not matching screens
A new system does not need the same internal structure or every historical interface. It does need agreed outcomes for users, operators and connected systems. Define parity through examples: calculations, permissions, state transitions, exports and failure handling.
Some old behaviour should be removed. Mark that as an intentional product decision and communicate it. Otherwise a missing function may be defended as cleanup after users discover the loss.
Automated comparison can help for deterministic outputs. Replay representative inputs through old and new paths and investigate differences. It cannot decide whether an old result was correct, so a domain owner must judge mismatches.
Fund coexistence and the end of the old system
During an incremental rewrite, the organisation pays for two systems, adapters, duplicated observation and extra support. Include this temporary state in the plan and staffing. A target architecture diagram that omits coexistence understates the hardest part.
Name the removal criteria for the old path: all required capabilities moved, data reconciled, integrations changed, recovery rehearsed and owners trained. Assign the decommissioning work before enthusiasm shifts to the next project.
Define stop conditions as well. If the first capability cannot reach parity, the seam proves unstable or cost expands beyond the accepted range, reconsider the approach. Sunk effort is not evidence that the next slice will work.
Choose a rewrite for necessity, not morale
Developer frustration is real, but a rewrite is an expensive way to improve morale if the underlying issues are unclear ownership, shifting requirements or weak review. Those conditions will follow the team into the new codebase.
The technical-debt measurement approach connects constraints to delivery outcomes. The major-refactor decision covers structural change that preserves behaviour in place. Use those diagnoses before committing to replacement.
A justified rewrite has a narrow reason, a migration sequence and evidence gates. It is less romantic than “start over,” and far more likely to protect the value already carried by the system.
If a critical system needs replacement and your team needs a verifiable migration path, Build with us. Eliyce agrees scope and evidence in writing and delivers reviewable increments; the page explains the service without promising a fixed result.
Preserve operational knowledge as carefully as code behaviour. Deployment order, repair scripts, support triage and capacity limits may never appear in source files. Observe a normal release and one recovery procedure before replacement planning. Decide which practices should be automated, retained or retired, and verify that the new system gives operators equivalent visibility.
Run the rewrite with one accountable migration owner. Separate teams may own capabilities, but one person or small group must reconcile data, cut-over order and parity decisions across them. Without that view, every component can report completion while the replacement as a whole remains unsafe to adopt. Make ownership explicit.
Frequently Asked Questions
When should you rewrite a codebase from scratch?
Rewrite when a required outcome is structurally unreachable through bounded repair, the organisation accepts the opportunity cost, and the team can preserve critical behaviour, data and operations through a staged migration with evidence.
How do you know whether old code is beyond repair?
Trace the constraints behind important changes and test smaller treatments. If containment repeatedly fails, necessary change remains unsafe and no viable seam exists inside the current structure, replacement may be justified. Age and poor style are insufficient evidence.
What should be documented before a rewrite begins?
Document critical behaviours, data meanings, integrations, operational procedures, ownership, known failures and unknown areas. Define which outcomes require parity and which differences are intentional product decisions.
Is it safer to rewrite one module at a time?
Often, when the module has a stable boundary and can coexist with the old system. Shared databases and cross-cutting transactions may defeat that independence. Demonstrate the seam with one capability before scaling the approach.
How do you compare the old and new systems?
Replay representative inputs, compare observable outputs and state changes, inspect permission and failure paths, and let domain owners judge differences. Tie results to exact versions and representative data rather than visual similarity alone.
When should a rewrite programme be stopped?
Stop or redesign when early slices cannot achieve agreed parity, the migration boundary proves unsafe, coexistence cost exceeds the accepted range or the business outcome no longer justifies the investment. Preserve useful tests and boundaries from the work.
