Refactoring is the task shape that punishes short-context models hardest. A rename that looks safe in one file breaks a caller three directories away; a framework upgrade only works if every touchpoint moves together. This is the work Claude Opus 5 is unusually good at, because it can hold the whole picture and keep going for a long time without losing the thread.
This page is written for engineers planning a migration nobody wants to start. If you want the model overview first, start with the complete Claude Opus 5 guide.
| Best effort level | xhigh |
| Context available | 1M tokens — enough for real working material, not just snippets |
| Cost | $5 per million input tokens, $25 per million output |
Why Claude Opus 5 suits large-scale refactoring
- Long-horizon execution: it sustains coherent work across long autonomous runs rather than degrading after a few turns.
- The 1M-token window means the caller, the callee, and the test all fit in the same session.
- 128K max output lets it emit a whole rewritten module in one response.
- It self-verifies as it goes, re-reading its own edits without being prompted.
A workflow that works
- Write a migration spec before the first prompt. What changes, what must not change, and how you will know it worked.
- Give it the test command. A migration with a runnable check is a fundamentally different task from one without.
- Do a pilot slice first — one module end to end — then hand it the pattern and the rest of the repo.
- Commit in reviewable chunks. Ask for the work in stages you can actually read.
- Re-run the full suite yourself. Its self-verification is good; it is not your CI.
Settings to start from
Set the effort level to xhigh. Long-horizon agentic work is the canonical xhigh use case. Give it a large max output too, so a big refactor isn't truncated mid-file.
Leave adaptive thinking on — it is the default on Claude Opus 5, and turning it off introduces failure modes that are not worth the saving. See effort levels explained if you want to tune this properly.
What to watch out for
- Scope creep is the main risk. Left unconstrained it may modernise things you did not ask it to touch. State the boundary explicitly.
- Migrations are where an uncapped subagent budget gets expensive. Cap the fan-out.
- A long turn can run for many minutes. Plan for it — streaming, timeouts, and a UI that shows progress rather than looking frozen.
The verdict
For the migration that has been sitting in the backlog for two years, this is the model to point at it — with a spec, a test command, and an explicit scope boundary.
If cost is the constraint, read how to cut Claude Opus 5 costs before downgrading — routing and caching usually beat switching models.
More on Claude Opus 5
Start with the complete Claude Opus 5 guide for the overview, or go deeper:
Ready to go deeper?
Read the full Claude Opus 5 guideFrequently Asked Questions
How large a codebase can Claude Opus 5 refactor in one session?
The 1M-token context window covers a large repository including tests and documentation. The practical limit is usually your review capacity rather than the model's: stage the work into chunks you can actually read and verify.
How do I stop Claude Opus 5 from changing things I didn't ask about?
Say so explicitly. Opus 5 sometimes widens scope — adding cleanup, abstractions, or defensive handling around the change you requested. An instruction to deliver exactly the requested scope, and to flag rather than act on anything it thinks is also wrong, reduces this to near zero.
Is Opus 5 or Sonnet 5 better for a migration?
Opus 5, if the migration is genuinely hard — unfamiliar code, cross-file coupling, ambiguous requirements. Sonnet 5 costs $3/$15 versus $5/$25 and is capable enough for mechanical, well-patterned changes. Many teams pilot with Opus 5, then let a cheaper model apply the established pattern.
