ClaudeRefactoringLevel 3: Workflows

How Do You Break Up a Huge Function With Claude?

Have Claude list the function's separate responsibilities in order of risk, then extract only the safest one. Run the tests, commit, and repeat. Tell it to move the code rather than rewrite it, so you can check the diff at a glance.

Prompt to copy 
[function] in [file] does too much. Don't rewrite it. Read all of it first, then find its callers.

List its responsibilities and the seams between them. For each seam, give the state it reads and writes, and rank the seams from safest to riskiest to extract. Flag any seam that would need more than [4] parameters, since that probably isn't a real boundary.

Then extract only the first one into a well-named function, with behavior identical. Move the code rather than rewriting it. Run [test command], show me the output, and stop. Tell me what state it still shares with the parent.
  1. 1Rank seams by risk
  2. 2Move the safest onemove it, don't rewrite it
  3. 3Run the tests
  4. 4Commitone seam per commit
Repeat until a seam won't separate cleanly
Rule of thumb, not an Anthropic chart: one extraction at a time leaves one suspect when something breaks.

Try it now

  1. 1Send the prompt in Claude Code, and read the ranking before it continues. You may know of a risk it can't see.
  2. 2After the extraction, check it with git diff --color-moved, which colors moved lines differently. Most of the change should show as moved, not rewritten.
  3. 3Commit, then reply next seam. It worked if the parent function gets shorter with each commit and the tests pass every time.

Use it when

Functions that have grown to hundreds of lines, mix several responsibilities, or can't be tested because everything is tangled together. It needs tests around the function. If there are none, write characterization tests first.

Skip it when

Long code that's cohesive and linear. A data pipeline that reads top to bottom can be clearer whole than chopped into pieces. Don't extract to hit a line count, and don't start if your tests can't catch a mistake in this function.

Why it works

A big rewrite gives you a hundred suspects when something breaks, while one extraction gives you one. That's a rule of thumb, not a vendor claim. Very large files also change how Claude Code works. Anthropic's tools reference says a read that goes over the default token limit returns only the first page with a PARTIAL view notice, and a read cut short that way doesn't count as having read the file before an edit. A file over 256 KB returns an error, telling Claude to read a portion or search. Duplicated code matters as well, because Edit needs its text to appear exactly once. Asking Claude to read everything and map the state first means it's working from the whole function, not its first page.

Example

A 300-line request handler validates input, applies business rules and formats a response. Claude might rank formatResponse as safest, because it only reads the result, and business rules as riskiest, because they share four variables with the rest. Extract the formatter first and commit. Then do validation. What's left is the hard part, now in plain view and much shorter.

Going further

Treat the shared state as your map. Whatever a seam can't cleanly separate shows the real coupling, and that's what to redesign next, so stop extracting there. For a risky one, Anthropic's worktree docs show a refactorer subagent with isolation: worktree in its frontmatter, which works in a separate checkout and can't run commands in your main one. Two traps apply. Subagent worktrees branch from your default branch unless you set worktree.baseRef to "head", so uncommitted work and unpushed commits aren't there. And /rewind doesn't normally restore subagent edits, so review their work through git.

Common mistakes

  • Letting Claude rewrite the logic while extracting. Then a pure move becomes a behavior change, and the moved-lines view can no longer help you check it.
  • Pushing through a helper with six parameters. That usually means the seam isn't real, so stop and rethink the boundary.
  • Extracting several seams in one commit. A broken test then can't tell you which one caused it.
  • Splitting cohesive logic into small pieces that mean nothing alone, just to shrink the line count.

Sources

Checked 6 November 2026. Products change often, so confirm details with the vendor.

Related

Workflow How Do You Refactor With Claude Safely? Technique Should You Rename Code Before Refactoring It? Technique How Do You Refactor Code That Has No Tests? Best practice How Do You Limit What Claude Can Do Through MCP?

Beyond the course

Glossary Vibe coding Pricing guide Claude pricing, plans and models