The Only Scalable Fix is Migration

The instinct when a codebase slows you down is to fix it incrementally — clean it up as you go, leave every file a little better than you found it. But incremental cleanup is structurally incapable of winning. You refactor one file while three other engineers add code to different parts of the system using the old patterns. The debt isn't just persistent — it's compounding.

Will Larson makes the case that the only mechanism that actually works at scale is migration — a concerted, team-wide effort to move from the old pattern to the new one. Not a side project. The project.

A migration that works moves through three phases.

First, derisk: pick one difficult module, prove the new pattern there, learn what breaks, fix the tooling.

Second, enable: build the scripts, documentation, and examples that make migration self-service for other teams. Make doing the right thing easier than doing the old thing — because if the old path is still available and still familiar, most people will take it.

Third — and this is where most migrations die — finish. Teams hit 90% and declare victory. But 90% means maintaining two systems simultaneously, which is often worse than the original mess. Every exception to the new pattern is a crack. Real migration ends with deletion: the old system is removed, the old path is gone, and there's nothing left to maintain.

The 10% that remains after "good enough" is the part that will quietly rot for the next three years. If the debt is worth fixing, it's worth finishing.