How to Keep Code Quality High (and Velocity Up) During a Major Rewrite
Direct answer: Teams keep code quality high during a major rewrite by not doing a "big bang" rewrite at all. They replace the old system piece by piece behind a stable interface (the strangler fig pattern), pin current behaviour with characterisation tests, run old and new code side by side and compare results, release behind feature flags, and freeze new features in the old system. Velocity comes from shipping small, verified slices, not from writing the new system faster.
"How do big companies keep code quality high while increasing engineering velocity during a major re-write?" showed up in my site's search data this month, and it's a better question than most. Rewrites are where good teams lose years. The techniques below are well documented and used at large companies; none of them are secret, but they're routinely skipped under deadline pressure. For how to measure whether it's working, see what coding velocity is and how to measure it.
Why rewrites go wrong#
In 2000, Joel Spolsky called rewriting code from scratch "the single worst strategic mistake that any software company can make," using Netscape as the example: years spent rebuilding while competitors kept shipping. A quarter of a century later, the failure pattern hasn't changed:
- Hidden behaviour. The old code is ugly partly because it handles a hundred edge cases nobody wrote down. The rewrite drops them and customers find out first.
- Two systems, one team. The old one still needs fixes, so the new one falls further behind.
- No feedback until the end. A big-bang cutover means the riskiest moment of the project is also the first time real users touch it.
- Scope creep. "While we're rewriting it, let's also…"
Seven techniques that keep quality high#
1. Strangle it, don't replace it#
Martin Fowler's strangler fig application pattern puts a routing layer in front of the old system and moves one route, module or workflow at a time to the new one. The old system shrinks until it can be switched off. Every step is small enough to review, test and roll back.
2. Pin behaviour with characterisation tests#
Before changing anything, write tests that record what the old system actually does, not what the spec says. Michael Feathers called these characterisation tests in Working Effectively with Legacy Code. For an API, that can be as simple as recording real requests and responses and asserting the new code returns the same. These tests are your definition of "done".
3. Branch by abstraction#
Inside one codebase, branch by abstraction introduces an interface in front of the thing you're replacing, makes the old code one implementation, builds the new implementation behind it, and switches over. Everything stays on the main branch and deployable. No six-month rewrite branch that nobody can merge.
4. Run old and new side by side#
For critical logic, run both implementations on real traffic, serve the old result, and log any difference. GitHub open-sourced Scientist for exactly this: run an "experiment" with a control and a candidate, compare, and publish mismatches. When mismatches drop to zero for long enough, switch. It's the most convincing quality evidence you can get, because it uses production data, not test fixtures.
5. Release behind feature flags#
Ship the new path to internal users, then 1% of traffic, then 10%. Flags decouple deploying code from releasing it, which lets you keep deploying daily during a rewrite without exposing unfinished work.
6. Freeze features in the old system#
Agree up front: no new features in the old system, bug and security fixes only. And no new features in the new system until it matches the old one. Parity first, improvements second. This is the hardest rule to hold and the one that matters most.
7. Plan the data migration as its own project#
Code is usually the easy part. Schemas, historical records and invariants are where rewrites quietly break. Use dual writes or change-data-capture, run reconciliation jobs that compare old and new data, and rehearse the cutover. I've written about why business rules and data are the real risk in any system.
How this increases velocity, not just safety#
These techniques look slower on paper. In practice they're faster, because they remove the most expensive event in a rewrite: the late surprise. Small slices mean:
- Short lead time. Each slice reaches production in days, so you learn from real usage early.
- Low change fail rate. Characterisation tests and side-by-side runs catch regressions before users do.
- Cheap rollback. A flag flip instead of an incident.
- Visible progress. Stakeholders see routes move over, which buys the patience a rewrite needs.
Track the DORA metrics (lead time, deployment frequency, change fail rate, rework rate) for the new system from the first slice. If the change fail rate climbs, slow down before it costs you a quarter.
Quality gates worth enforcing#
- Static analysis at a strict level from day one in the new code. In PHP that means PHPStan at a high level, which is cheap to run now that PHPStan Turbo cut cold runs by more than half.
- Small pull requests with a clear owner for every review.
- Characterisation tests can't be deleted without a written reason.
- AI-generated code gets the same review as human code. AI is useful for writing characterisation tests and boilerplate. It's also very good at confidently dropping the edge case the old code handled. I covered our guardrails in how AI changed our engineering velocity.
Should you rewrite at all?#
Often the honest answer is no. Refactor in place if the architecture is sound and the code is just messy. Rewrite (incrementally) when the platform itself is the problem: an unsupported runtime, a framework with no upgrade path, or a data model that can't represent the business any more. If you're on an old PHP version, an upgrade playbook usually beats a rewrite.
Frequently asked questions#
Is it better to rewrite or refactor?#
Refactor in place when the architecture is sound and the code is just messy. Rewrite incrementally when the platform itself is the problem, such as an unsupported runtime or a data model that no longer fits the business.
What is the strangler fig pattern?#
A way to replace a system gradually: a routing layer sends some functionality to the new system while the rest stays on the old one, until the old system can be switched off. The name comes from Martin Fowler.
What are characterisation tests?#
Tests that record what existing code actually does, including odd edge cases, so a rewrite can prove it behaves the same. The term comes from Michael Feathers' Working Effectively with Legacy Code.
How do you measure a rewrite's progress?#
Track the share of traffic or functionality served by the new system, plus DORA metrics such as lead time and change fail rate. A rising change fail rate is the signal to slow down.
Key takeaways#
- Avoid big-bang rewrites. Replace systems slice by slice with the strangler fig pattern or branch by abstraction.
- Pin current behaviour with characterisation tests before you change anything.
- Run old and new code side by side on real traffic and switch only when results match.
- Use feature flags, freeze features in the old system, and treat data migration as its own project.
- Measure the rewrite with lead time and change fail rate from the first slice.
Sources#
- Joel Spolsky: Things You Should Never Do, Part I (2000)
- Martin Fowler: Strangler Fig Application
- Martin Fowler: Branch By Abstraction
- GitHub Scientist
- Michael Feathers, Working Effectively with Legacy Code (Prentice Hall, 2004)
- DORA: software delivery performance metrics
Facing a rewrite and not sure how to slice it? Let's talk.