In most cases, do not rewrite everything: replace the code piece by piece, one feature at a time, while the old system keeps running. A full rewrite is only justified in a few specific cases, listed below.
Martin Fowler sums up his teams' experience: the "rebuild the same thing, but better" plan usually goes down in flames, because a serious system takes a long time to replace and its real behaviour is poorly understood (Martin Fowler, Strangler Fig).
01Why full rewrites fail so often
A codebase nobody wants is almost always a codebase that works. Its overlong functions hold fixes accumulated from bugs found in production. Joel Spolsky made the point back in 2000 about Netscape, which went almost three years without a major release during its rewrite: throwing the code away means throwing away all those fixes and handing years to your competitors (Joel Spolsky, Things You Should Never Do).
Three mechanisms show up every time:
There is a human bias too. Reading code is harder than writing it, so other people's code always looks worse than it is. In an r/cto thread, a former CTO of two startups describes treating every architecture decision as permanent, even though much of it was replaced a few months later (r/cto discussion). Code is not a monument: it is a temporary state you keep evolving.
02The criteria to decide
Before deciding, answer these questions. Each answer pushes one way.
The Azure documentation for the pattern says the same from another angle: gradual migration does not fit when requests cannot be intercepted, when there is no integration point you can change, or when the system is small enough to replace in one go (Microsoft, Strangler Fig pattern). Outside those cases, piece-by-piece replacement wins.
Find where the code really hurts
The feeling that "everything must go" can be checked. The areas to tackle first are the ones that change often: that is where debt costs you, on every release. This Git command lists the most modified files over the last twelve months:
Cross that list with the files behind most bugs and incidents. If a handful of files stand out, the diagnosis is clear: targeted refactoring is enough and a rewrite would be overkill. If the pain is everywhere and the technology itself is blocking, the rewrite question becomes legitimate. This triage is also at the heart of a technical due diligence before a raise or an acquisition.
03Migrate piece by piece with a strangler fig
The principle, described by Fowler and taken up by Microsoft: a facade placed in front of the old system receives every request. At first it sends almost all of them to the old code. At each step, one feature is rebuilt in the new system and the facade routes the matching traffic to it. When nothing depends on the old system anymore, you switch it off, then remove the facade (Microsoft, Strangler Fig pattern).
The order that keeps risk low:
1. Agree on the outcomes: ship faster, reduce incidents, leave a dead technology. Without a shared goal, the migration drifts. 2. Write characterization tests on the critical paths: they freeze current behaviour, bugs included, so any difference shows up. 3. Put the facade in place: a reverse proxy, an API gateway or routing inside the app. 4. Pick the first slice where value is high and coupling is low, ideally a new feature. 5. Shift traffic gradually, with a rollback available at each step. A boring deployment makes those switches routine. 6. Decommission as you go, so you do not maintain two systems forever.
Transitional code (facade, adapters, dual writes) is meant to disappear. It looks like waste, but it is the price of a migration without downtime. Make sure it does not become a single point of failure.
The trickiest part is usually the database shared by the old and new systems. Decide early who writes what, and add an adaptation layer so the new code does not inherit the old one's conventions.
Finally, change how the team works as well. Fowler insists that without organisational change, the new system will end up in the same state as the old one. This is often where a fractional CTO adds the most: setting the criteria, ordering the slices and holding the course over several months.
04FAQ
How long does a gradual migration take?
Longer than a rewrite on paper, but it delivers value from the first slice and can stop at any point without losing everything. The duration depends on the number of slices and on how coupled the database is.
When should you rewrite everything anyway?
When the system is small and well understood, when the technology can no longer be maintained or deployed, or when requests cannot be intercepted at all. Even then, write characterization tests first so nothing gets lost along the way.
Isn't refactoring just kicking the can down the road?
Not if it targets the files that change the most and follows a measurable goal. Kicking the can is fixing things at random with no priority. The hotspot command above exists precisely to choose.
05Sources
A big-bang rewrite bets the product on a project you cannot see the end of. Replace it piece by piece, measure each step, and keep the full rewrite for the rare cases where nothing else holds.
Talk about your project ↗