Breaking a large refactor into agent-sized tasks

Breaking a large refactor into agent-sized tasks means turning one risky change into an ordered series of small ones, where each step leaves the codebase building and passing its tests and has its own check. Agents are good at mechanical, local edits and poor at holding a forty-file change in mind while keeping every caller consistent. Ask for the whole refactor in one session and you usually get a diff too large to review, a build that is broken halfway, and a summary that says everything went well. Ask for one step at a time, in the right order, and each diff is small enough to read and each step can be reverted on its own. The techniques are old ones (expand and contract, characterization tests, migrating callers in batches) applied with more discipline than people usually bother with when a human does the work. For the mechanics of ordering, see task dependency graphs.

Why big refactors go wrong with agents

Three things go wrong. First, scale: the change exceeds what fits comfortably in the agent's context, so it edits some files based on a summary of others and the edits drift apart. Context window limits explains why this happens even with large windows.

Second, intermediate breakage. A single-session refactor has no green points in the middle. If the session stops at file twenty-three of forty, you have a broken branch and a partial explanation.

Third, review. A diff of two thousand lines will not be read carefully by anyone, and agent-written refactors often mix the intended change with renames, reformatting and small improvements the agent decided on along the way. When something breaks later, the change that caused it is hidden among the ones that did not.

The fix for all three is the same: smaller tasks, each green, each reviewable, in a recorded order.

A sequence that stays green

The standard shape is expand, migrate, contract. Expand: add the new code beside the old without changing callers. Migrate: move callers over in batches. Contract: remove the old code once nothing uses it. Every step leaves the build passing.

Here is a sequence for replacing a shared money helper that several features import.

Task 1: Add characterization tests that pin current behavior for every caller, including the ones nobody thinks about, such as a CSV export. Check: the new tests pass on the untouched code.

Task 2: Add the new helper beside the old one, with its own tests. No caller changes. Check: the full suite passes.

Tasks 3 to 5: Migrate callers one module per task: checkout, then invoices, then export. Check for each: the full suite passes, including the characterization tests for the other modules.

Task 6: Remove the old helper. Check: the full suite passes and a repository search finds no remaining references.

Each task fits one session and one review, and any single step can be reverted without unwinding the rest.

Finding callers and recording the order

The order of a refactor is only as good as your list of what depends on what. Build that list by searching the repository, not from memory or from the agent's assumptions. Search for imports, direct calls, string references and configuration that names the module.

A test project from BRAIN FLUID's development shows what one missing entry does. Four tasks shared a cents() helper. A scripted change to the helper made checkout pass its new check and broke the CSV export. A query over the recorded relationships nominated the checkout task and its parent but not the export task, because the export's import of the helper had never been recorded; the query did report its coverage as incomplete [D6]. A report of incompleteness, though, does not name the module that was missed.

Record each dependency as you find it, including import relationships between modules, and make each migration task depend on the tasks before it. Declared versus inferred dependencies covers why the declared list is the one you can act on, and why it is never automatically complete.

Checks between steps, and work found on the way

Run the full suite after every step, not just the tests the agent wrote. A refactor's risk sits in the code it did not mean to affect, and narrow tests miss regressions for exactly that reason. If the full suite is slow, run it at least before each merge and keep a fast subset for the agent's own iterations.

Agents doing refactors find things: a second copy of the helper, a caller in a script outside the main source tree, a test that was already broken. Each of these becomes a new task in the sequence, placed where it belongs, not an addition to the current diff. The current task stays as specified.

Track the sequence visibly. A numbered list works; a board or a timeline helps when the refactor spans weeks. What matters is that anyone, including the next agent session, can see which steps are done, which is next and which are blocked. When a step is reviewed and merged, mark it so before starting the next. Starting step five while step four waits for review is how sequences quietly fork.

QUESTIONS

How small should each refactoring task be for an AI agent?

Small enough that the diff can be reviewed in one sitting and the step can be reverted on its own. In practice that usually means one module or one kind of mechanical change per task. If the completion check for a step is hard to state, or the step leaves the build broken until a later one runs, split it differently.

Can an AI agent do a large refactor in one session?

It can produce one, but the result is hard to trust. A single session has no green points in the middle, the diff is too large to review carefully, and the agent edits some files from summaries of others. Splitting the work into an expand, migrate and contract sequence gives you checkpoints, smaller reviews and steps you can undo individually.

How do I find every caller before an agent changes a shared function?

Search the repository for the function's name, its module's imports and any string or configuration references, including scripts and tests outside the main source tree. Ask the planning agent for its list too, then compare the two. Write the result down as dependencies, and add characterization tests for each caller before the change so a missed one shows up as a failure.

RELATED GUIDES

• Gantt planning in BRAIN FLUID: the integrated view and its prototype
• How to read project progress in BRAIN FLUID Build

RELATED HARNESS PAGES

• Task dependency graphs for AI agents Task dependency graphs for AI agents: declare prerequisites, let selection skip blocked work and keep dependencies in the context each agent gets.
• Declared vs inferred dependencies in change-impact analysis Declared vs inferred dependencies in change-impact analysis: what task links and import graphs each catch, where each is blind, how to combine them.
• Why narrow acceptance tests miss AI regressions Why narrow acceptance tests miss AI regressions: a task's check can pass while a shared change breaks another consumer. A worked example and a fix.
• The blast radius of AI code changes The blast radius of AI code changes: what one agent edit can break elsewhere, a worked rounding example, and how a reviewer finds affected features.