Claude Code Under Context-Window Pressure on the Aggregator: Splitting a Big Refactor Across Backends Without Losing the Plan
When a refactor outgrows a single model's context window, moving the plan into a durable file and issuing per-file calls across backends on one API key keeps the work coherent. This guide covers writing a plan artifact, routing slices to models by strength, and validating the result.
Why big refactors hit a ceiling
Large refactors fail for a simple reason: the model has to hold the whole change in one prompt. Even with large context windows, stuffing every file into one call degrades attention, increases cost, and makes recovery from a bad edit expensive. The fix is not a bigger prompt. It is a smaller unit of work tied to a plan that lives outside the chat.
Put the plan in a file, not the conversation
The conversation is a bad place for a plan. It is ephemeral, it grows with every message, and switching backends means starting over. Write the plan to a real file in the repo, for example REFACTOR_PLAN.md, and treat it as the source of truth. The plan should include:
- The goal of the refactor in one or two sentences.
- A list of files to touch and why each one changes.
- Interface decisions (function signatures, module boundaries, naming).
- The order of edits and any dependencies between files.
- A definition of done, including tests to run.
Keep it short enough that it fits comfortably in a single prompt. Every later call references this file instead of re-describing the task.
Split by file, not by feature
Feature-based splits tend to cut across files, which forces the model to reason about code it cannot see. File-based splits keep each call self-contained: one prompt, one file, one plan section. For each file, the call payload is the plan, the current file contents, and any interfaces it depends on. The output is the new file contents plus a one-line note on what changed.
When files are tightly coupled, process them in dependency order: interfaces first, then implementations, then call sites. Update the plan file after each wave so the next call sees the latest decisions.
Route each slice to the right backend
A single API key that reaches multiple models lets you match the slice to the job without managing separate accounts or keys per provider. A practical routing pattern:
- Planning and interface design: a strong reasoning model. This call happens once and sets the direction for everything else.
- Per-file edits on straightforward code: a fast, low-cost model. Most files fall here.
- Tricky files (concurrency, complex types, cross-cutting changes): route back to the stronger model, still passing the same plan.
- Review and diff checks: a different model than the one that wrote the edit, to catch blind spots.
Because all backends sit behind the same key, switching models is a parameter change, not a new integration. Keep the routing table in a note next to the plan so the split is reproducible.
Keep each call inside the window
Even per-file calls can overflow. Guard against it:
- Pass only the interfaces a file needs, not whole modules.
- Summarize large files in the plan rather than pasting them whole; ask the model to produce a patch if the file is huge.
- Log token usage per call and split a file further when it approaches the limit.
- Never rely on the model to remember earlier turns; if it is not in the prompt or the plan, it does not exist.
Validate across backends
Cross-backend work needs a shared check. After each wave, run the project's tests and linters. Then give the plan, the changed files, and the test output to a reviewer model and ask one question: does this match the plan? Discrepancies go back into the plan file, not into a chat thread. This keeps every backend aligned to the same written contract.
Keep the plan durable
Commit REFACTOR_PLAN.md with the code, or keep it in a branch. If the work pauses or a backend changes, the next person or model resumes from the file, not from a lost conversation. The plan is the handoff artifact; the API key is the transport.
Cost note
On this platform you pay the official model price multiplied by 1.3 in USDC on Base, with no KYC. If you contribute keys, you are credited the official price multiplied by 1.1 (or 1.2 for premium backends). Splitting work by file keeps each call small, so you pay for the tokens the task actually needs rather than for a giant prompt repeated on every turn.