Skip to content

Small-Step Refactoring Workflow

A refactoring working discipline — instantiates Behavior-Preserving Refactoring

Breaks a large restructuring into a chain of tiny, individually behavior-preserving edits, each verified green before the next, so the system is never more than one small step away from working.

A big-bang restructuring fails in a characteristic way: you make fifty changes, run the tests, see red, and now the defect is somewhere in fifty changes. Small-Step Refactoring Workflow eliminates that search by construction. It decomposes the restructuring into a sequence of edits each small enough to be obviously behavior-preserving, and re-runs the safety net after every single one — "refactor under green." The granularity itself is the mechanism: because only one tiny thing changed since the last green, a failure is localized to that step automatically, and undoing it costs seconds. Its defining stance is that the system stays working at all times; there is never a "it'll compile again by Thursday" valley. Where an Automated Refactoring Tool executes an individual transform, this workflow governs the order and size of the whole chain of them.

Example

A developer must replace a tangled 300-line pricing function with a clean strategy-per-tier structure. Rather than rewrite it, they work in a chain of micro-steps: extract the tier lookup into its own function — run tests, green, commit; introduce a parameter object for the shared arguments — green, commit; move one pricing branch into a strategy class — green, commit; repeat per branch. Around the seventh step the suite goes red. Because only that one small move happened since the last green, the cause is unambiguous; they revert just that step — a few minutes of lost work, not the afternoon — fix the misplaced edge case, and continue. The end state is the same clean structure a big rewrite would have produced, but at no point was the code broken, and no regression ever had room to hide.

How it works

The change is expressed as an ordered series of small transformations, each of which is individually behavior-preserving and independently committable. Between every step the regression guard runs to green; a red result means the last step — and only the last step — is suspect. Each green commit becomes a checkpoint the work can fall back to. What distinguishes the method from ordinary careful coding is the strict rule against accumulating unverified changes: you never make a second edit before the first is proven green, because it is exactly that accumulation that destroys localization.

Tuning parameters

  • Step size — how tiny each edit is. Smaller steps make behavior-preservation self-evident and reverts cheaper, but multiply the number of test runs and commits.
  • Guard speed — how fast the safety net is. A sub-second unit suite enables truly tiny steps; a slow suite forces larger, riskier ones, so guard speed effectively sets the achievable step size.
  • Commit granularity — committing every green step versus squashing a logical group. Fine commits give precise revert points; squashing keeps history readable.
  • Refactor / feature separation — whether a step is ever allowed to change behavior. The discipline holds only if the answer is no: structure and behavior never move in the same step.
  • Checkpoint depth — how far back reverts realistically reach. Frequent green commits keep the safe fallback close to the current edit.

When it helps, and when it misleads

Its strength is fearlessness in dangerous code: it makes defects trivially localizable, reverts nearly free, and the system continuously shippable, which is what lets a team restructure legacy no one fully understands.[1] It is the safest available path from a tangled structure to a clean one.

Its central weakness is borrowed safety: "green after every step" is only as trustworthy as the guard is thorough, so tiny steps over thinly-tested code are small, not safe, and the green light can flatter a change that quietly broke an uncovered path. The discipline also decays under deadline pressure — people batch several edits before testing and silently lose the localization that was the whole point — and a change that genuinely needs a design leap can be dressed up as a hundred busywork micro-steps that never reach it. The guard against all three is to keep the safety net fast and honest and to hold the one-change-per-green rule even when rushed; a step that cannot be made behavior-preserving is a behavior change and belongs to a reviewed change, not to this workflow.

How it implements the components

  • internal_restructuring_scope — it defines the restructuring as an ordered sequence of small internal edits and their granularity, rather than one monolithic change.
  • regression_guard — it operationalizes the guard as an after-every-step green check, so any break surfaces at the exact step that caused it.
  • rollback_checkpoint — each green commit is a known-good point, making the last step, and only the last step, cheap to undo.

The workflow consumes the safety net but does not build it — the test corpus is authored by Characterization Test Harness or a regression suite — and it does not perform release-level rollback of a deployed version, which is Deployment Rollback; the individual mechanical transforms it sequences are the Automated Refactoring Tool's job.

Notes

The workflow's safety is entirely on loan from the guard, which is why a Characterization Test Harness is usually the first thing stood up on untested legacy: without a green to refactor under, small steps buy tidiness but not protection. The method scales the confidence of the safety net down to individual edits — it cannot manufacture confidence the net does not already provide.

References

[1] Martin Fowler's "two hats": at any moment you are either adding behavior or refactoring, never both, and you switch hats consciously. Kent Beck frames the same discipline as "make the change easy, then make the easy change" — the small-step chain is how you make the change easy without breaking anything on the way. ↩