Cost Per Refactor: Estimating a Multi-File Change Up Front

A refactor is the one task where you can estimate AI cost reasonably well before starting, and also the one where the estimate most often comes in three times higher than people expect. Both facts have the same cause: the work is dominated by how many files must be held in view simultaneously, and that number is knowable in advance.

The useful move is to do the arithmetic before the run rather than after the invoice, because the answer frequently changes the plan.

Why refactors are the worst case

Most agent tasks have a natural context ceiling. A bug fix reads a handful of files, finds the defect and stops. A feature adds code in one area. In both, the model can forget most of what it read once it has moved past it.

A refactor cannot forget. Renaming a type, changing a function signature or moving a module means every call site must be updated consistently, and consistency requires that the model still knows what it did in file three when it reaches file nineteen. The transcript therefore grows monotonically and nothing can be dropped safely.

Worse, the failure mode of dropping something is silent. A compaction step that discards the earlier edits does not produce an error — it produces a run where the second half of the codebase gets a slightly different convention than the first half, and you find out in review. The hidden cost of context bloat covers the general mechanism; refactors are its extreme case.

How context scales with files touched

Two things grow at once, which is what makes the total surprising.

The first is the accumulated content: every file read stays in the transcript, so after N files the context holds roughly the sum of all N file sizes plus the edits made to them. The second is the resend: that whole accumulation is sent again on every subsequent turn.

So cumulative input across a refactor of N files is on the order of N squared times the average file size, not N times it. Doubling the number of call sites roughly quadruples the token bill. This is the single most important fact for estimation, and it is why a refactor that felt twice as big as the last one costs four times as much.

The practical consequence: the estimate is far more sensitive to file count than to model choice. Halving the files in scope beats any price difference you can find between providers.

A rough estimation method

You can get within a factor of two in about ten minutes, which is enough to decide the approach.

Step one: count the sites. Grep for the symbol you are changing and count distinct files, not occurrences. Call it N.

Step two: size the average file. Take the total bytes of those files divided by N, and convert to tokens with a rough divisor of four characters per token — refine it for your language if you have measured it, since the spread is real. Token costs by language covers how far off that divisor gets.

Step three: apply the quadratic. Cumulative input is approximately the system prompt times the number of turns, plus average file tokens times N times N divided by two. The second term dominates as soon as N is more than a handful.

Step four: add the verification tail. Every refactor ends with running builds and tests, reading failures and patching. Budget a third to a half again on top of the edit phase, more if the suite is slow or noisy.

Worked through: forty files averaging 800 tokens gives roughly 800 times 1,600 divided by two, about 640,000 input tokens for the edit phase, plus a verification tail taking it near a million. Multiply by your input rate, halve it or better if the stable prefix is cached, and you have your number.

Staged versus single-pass

The quadratic is also the argument for staging, and it is a strong one.

A single pass over forty files carries the full N-squared cost. Four staged passes of ten files each, with a fresh context per stage, cost roughly four times the ten-file quadratic — which is a quarter of the single-pass figure. The saving is real and large.

What you give up is cross-stage consistency. The model in stage three does not remember the judgement calls made in stage one, so it may resolve an ambiguous case differently. The fix is to write those decisions down: a short conventions note carried into every stage, stating the new signature, the naming, and how edge cases were handled. That note is a few hundred tokens per stage against a saving measured in hundreds of thousands.

Single-pass is still right when the change is genuinely interdependent — where a decision in one file determines what is correct in another, and no summary can capture it. Those refactors exist, and they are expensive by nature. Choosing a model for refactoring covers where model capability actually changes the outcome.

The cheapest refactor is the one a tool does

Before spending anything, check whether the change is mechanical.

A pure rename, an import reorganisation, a signature change with no behavioural component — these are what language servers, codemods and AST tools are for. They are deterministic, free, instant, and correct across a thousand files as easily as ten. Handing that work to a model is paying for judgement that is not required.

The right split is usually a hybrid: let the deterministic tool do the mechanical ninety percent, then send the model only the sites it could not resolve. That collapses N from forty to five, and the quadratic does the rest of the work for you.

Watch the tail, not the average

Refactor costs are skewed even within one project. Most runs land near the estimate; a few blow past it because the model hit an unexpected dependency, or the tests were already failing before it started, or a generated file with 20,000 lines got pulled into context.

That last one is worth guarding explicitly. Exclude generated code, lock files, vendored directories and snapshots from anything the agent can read. A single accidental read of a large generated artefact can cost more than the entire intended refactor, and it will be resent on every remaining turn. The token cost of long context covers what that resend is actually worth.

The rule to apply

Count the files first. Under ten, run it in one pass and do not think about it. Ten to fifty, stage it with a written conventions note. Above fifty, find a deterministic tool for the mechanical part and send the model only the residue.

Then log actual against estimate once, for one real refactor. The ratio you get is stable enough to reuse, and having it turns every future refactor estimate into a thirty-second calculation. Cost per agent run covers the instrumentation that makes that log possible.