All shipped software carries debt. The question is whether the debt is localized, understood, and priced into velocity—or whether it is a fog that slows every feature and onboarding conversation.
Signals it is time to refactor
- Every feature touches the same god module
- Bugs cluster in one neighborhood of the codebase
- Onboarding takes weeks before useful commits
- Tests are feared because they are brittle or missing
Contain when you must move
Use seams—feature flags, adapters, and module boundaries—when you need speed but refuse to spread the mess. Pay down debt as part of features that already require touching the area. Opportunistic cleanup beats “refactor quarters” that never ship customer value.
