Extract One Seam at a Time

A refactoring pattern for oversized functions or modules where you have Claude identify the natural seams — self-contained chunks of responsibility — and extract them one at a time, testing after each, rather than rewriting the whole thing in one move.

A single giant rewrite is unreviewable and risky: if it breaks, you don't know which of a hundred changes did it. Extracting one seam at a time keeps every step small, individually verifiable, and easy to revert. Claude is good at spotting seams — a block that only touches a few variables, a loop body that could be a function — and at doing the mechanical extraction cleanly.

Functions that have grown to hundreds of lines, mix several responsibilities, or are hard to test because everything is entangled. The classic 'this method does too much' situation.

Code that's long but genuinely linear and cohesive — a data-transformation pipeline that reads top to bottom may be clearer whole than chopped into named pieces. Don't extract for a metric's sake.

This function is too large and does several things: <paste>.

Don't rewrite it all at once. First, list the distinct responsibilities you see and the seams between them, in the order they're safest to extract. Then extract just the first one into a well-named function, keeping behaviour identical, and stop so I can run the tests. We'll go seam by seam.

A 300-line request handler is doing validation, business logic, and response formatting. Claude lists the three seams, extracts validateRequest first, you run the tests green, then it extracts the formatting. After three small commits the handler is a readable ten lines that calls three tested helpers.

Ask Claude to extract each seam behind the smallest possible interface and note what state it still shares with the parent. The shared state it can't cleanly cut is a map of the real coupling — the thing to redesign next, once the easy seams are out of the way.

• Extracting everything in one commit, so a broken test can't tell you which extraction caused it.
• Creating helpers with six parameters because the seam wasn't really independent — that's a sign to stop and rethink the boundary, not push through.
• Extracting purely to hit a line-count target, splitting cohesive logic into fragments that are individually meaningless.