Driving a Large-Scale Refactoring

Migrating sixty calls from an old internal API to the new one is exactly the kind of task an agent excels at: mechanical, repetitive, no decisions to make. It's also the kind of task that produces the worst possible result when launched all at once. You get back a 1,400-line diff touching sixty-two files, the test suite shows eleven failures, and you have no way of knowing whether those eleven failures come from a systematic error repeated sixty times or from three legitimate edge cases. The diff is too big to review, too intertwined to partially revert, and too slow to regenerate to throw away painlessly.

The problem isn't the agent's capability, it's the granularity of verification. During a refactoring, the question you must be able to answer at any moment is: "is the repository still consistent?" A monolithic diff lets you answer it only once, at the end, when all the errors are mixed together. The method is therefore to impose a sequence of steps, each of which can be committed alone, verified alone, and reverted alone, and to make that sequence a constraint in the prompt, not a hope.