You inherit a business-critical, 6,000-line god class that every team edits weekly and that has almost no tests. How do you plan and sequence unwinding it without freezing feature delivery?

## Why this is a migration problem, not a cleanup task A long-lived god class is where a decade of undocumented business rules live. It is also a **coordination bottleneck**: every team edits it, so any long-running rewrite branch diverges faster than you can merge it. Both facts point to the same conclusion — proceed in **small, individually shippable, behavior-preserving steps** that can be interleaved with feature work and abandoned at any point without leaving the system worse. ## Step 0 — Decide whether to act at all Refactoring is an investment; justify it with the cost it removes: merge conflict rate, lead time for changes touching the class, defect density, onboarding time, inability to test. If the class is stable (low churn) and nobody is blocked, leaving it alone may be correct. Rank by *change frequency × complexity* — hot, complex code repays cleanup; cold complex code usually does not. ## Step 1 — Gather evidence - **Version-control churn analysis**: which methods/regions change, and together with what. Co-change clusters are natural module boundaries revealed by history rather than guesswork. - **Coupling map**: who calls in (afferent) and what it calls out (efferent). Callers define the interfaces you will need. - **Runtime usage**: log or trace which paths actually execute in production. Dead code is the cheapest win — delete it instead of refactoring it. - **Field-usage clustering**: group methods by the fields they touch; each cluster is a candidate extracted class. ## Step 2 — Build the safety net *before* moving code - **Characterization (approval/golden-master) tests** capture what the system *currently does*, including behavior you suspect is wrong. Their job is change detection, not correctness. Generate inputs broadly and snapshot outputs. - **Seam-level tests** at the class's public surface, ideally driven from real recorded traffic or production-shaped fixtures. - **Parallel run / shadow comparison** for the riskiest logic: execute old and new implementations side by side on real traffic, log differences, only cut over when divergence is zero. - **Feature flags / toggles** so each cut-over is reversible in seconds without a deploy. Without this, every subsequent step is a gamble; with it, extraction becomes mechanical. ## Step 3 — Create seams - **Interface Segregation**: give each caller group a narrow interface describing only what it uses. This decouples callers from the class as a whole and lets you re-point them later, one at a time. - **Dependency inversion**: replace internally constructed or globally located collaborators with injected ones, so pieces can be tested and replaced. - **Sprout and wrap** (from working-with-legacy-code practice): implement new behavior in a *new* class (sprout) or wrap the existing call to add behavior, rather than adding another method to the blob. ## Step 4 — Extract cohesively, ship continuously For each cluster: extract class → move the fields and methods → replace the original bodies with one-line delegations → ship. Callers keep compiling; behavior is unchanged; the diff is reviewable. Prefer **behavior-preserving, tool-assisted refactorings** (extract class, move method, inline) over hand-editing. Never mix a refactor commit with a behavior change commit — mixed diffs are unreviewable and un-bisectable. Order the clusters by risk-adjusted value: start with a moderately sized, well-understood cluster to prove the pipeline and build trust, not with the scariest core rule. ## Step 5 — Strangle Adopt the **strangler fig** approach: new features are implemented only against the extracted components; the façade routes calls to old or new implementations. The god class shrinks by attrition even during periods when nobody is funded to work on it. Eventually the façade has no logic left and can be deleted or demoted to a thin adapter. ## Step 6 — Guardrails so it does not regrow - Automated thresholds: file length, cyclomatic complexity, parameter counts, fan-in limits — with a **baseline** so existing debt does not block builds but new debt does (ratchet: the number may only go down). - **Architecture/fitness-function tests** encoding the target boundaries ("module X must not depend on Y"). - **Explicit ownership** for the new components; unowned code re-accretes. - Review norm: adding a method to the legacy class requires justification. ## Organizational realities - **Fund it visibly.** Purely opportunistic "boy-scout rule" cleanup rarely finishes a 6,000-line class; agree an explicit allocation (e.g. a fixed share of each iteration) with a stated business rationale. - **Team topology matters.** If five teams edit it, the class mirrors a missing ownership boundary (Conway's law). Extraction should follow the intended team boundaries, otherwise the new modules will just be co-edited too. - **Measure and publish**: lines in the class, number of dependents, merge-conflict count, change lead time, incidents attributable to it. Metrics turn "cleanup" into a trackable initiative and let leadership stop it rationally rather than emotionally. - **Know when to stop.** The goal is not zero legacy; it is removing the bottleneck. If churn and conflicts fall to acceptable levels with 1,500 lines remaining, declare victory. ## Why the big-bang rewrite is the wrong default It requires reproducing behavior you cannot enumerate, forbids incremental value delivery, forces a long-lived branch against a file everyone edits, and concentrates all risk into one cut-over. Rewrites are defensible only when the platform/runtime itself must change or the code is genuinely small; even then, prefer strangling behind a stable interface.