Refactoring 2,000 Lines with an Agent, One Slice at a Time
Refactoring a 2,000-line file in reviewable slices
A 2,000-line file rarely contains one large problem. It contains several small responsibilities sharing variables, assumptions, and unfortunate shortcuts. Asking a coding agent to “clean it up” gives those assumptions room to disappear.
I use a tighter loop: capture behavior, extract one responsibility, inspect the patch, run checks, commit. Here is a worked example for a TypeScript service with src/billing.ts, an npm lockfile, and Vitest behind npm test. Substitute your paths before running these commands.
Prepare the relay and an isolated checkout
This walkthrough assumes Codex is installed and already configured for your provider. Fluxo gives that setup one key and one base URL, https://api.fluxorelay.com, across Claude, GPT, Gemini, DeepSeek, Kimi, GLM, Qwen, Grok and more. It works with Claude Code, Codex, Gemini CLI, and any OpenAI SDK. For this session, GPT-6 Astra is one available choice; use the model identifier supplied by your provider configuration.
First, check your working tree. Commit or stash existing work before continuing; the new worktree starts from committed HEAD.
git status --short — git worktree add ../billing-slices -b refactor/billing-slices
cd ../billing-slices — npm ci
npm test -- --run — npx tsc --noEmit
If either check fails, record and resolve the baseline before asking the agent to edit. Otherwise, every later failure becomes a guessing game.
Map billing.ts before moving its functions
Read the file yourself, then ask the agent for a responsibility map. The first useful output is a boundary you can explain.
wc -l src/billing.ts — rg -n '^(export |async |function |class |const )' src/billing.ts
codex exec --sandbox read-only 'Inspect src/billing.ts, its callers, and existing tests. Do not edit files. Identify three small extraction candidates, their dependencies, and observable behavior that tests must preserve. Flag shared mutable state and side effects.'
Suppose the map identifies amount formatting, invoice validation, and database persistence. Start with formatting because it has the fewest dependencies. Leave persistence until its transaction boundaries are understood.
Capture formatting behavior before extraction
Ask for tests against the existing public entry point. A test that only exercises a newly extracted helper cannot tell you whether callers still receive the same result.
codex exec --sandbox workspace-write 'Inspect src/billing.ts and existing test conventions. Add characterization tests in src/billing.test.ts through existing public exports for amount formatting. Cover zero, negative values, rounding boundaries, and supported currencies where applicable. Assert current behavior. Do not change production code or add dependencies. Report any behavior you cannot exercise.'
git diff -- src/billing.test.ts — npm test -- --run src/billing.test.ts
Read every assertion. If the current rounding behavior looks wrong, preserve it for this refactor and open a separate bug. Mixing a behavior fix into a move makes review harder.
git add src/billing.test.ts — git commit -m 'test: characterize billing amount formatting'
Extract one module and inspect every changed line
Now give the agent a bounded edit with explicit stop conditions.
codex exec --sandbox workspace-write 'Extract only the amount-formatting responsibility from src/billing.ts into src/billing/format-amount.ts. Preserve public exports, signatures, rounding, defaults, and error behavior. Update imports as needed. Do not change tests, dependencies, validation, or persistence. If extraction requires changing behavior or moving shared mutable state, stop and explain.'
git diff --stat — git diff -- src/billing.ts
git status --short — git diff does not display untracked file contents, so read the new module explicitly.
cat src/billing/format-amount.ts — git diff --check — npm test -- --run — npx tsc --noEmit
Check initialization order, imports that execute code, and exported names. Passing tests support the review; they do not establish equivalence by themselves.
git add src/billing.ts src/billing/format-amount.ts — git diff --cached
git commit -m 'refactor: extract billing amount formatting'
Repeat the checkpoint for invoice validation
Repeat the same test-first sequence for validation, with a fresh prompt and a named destination. Keep each commit independently understandable. If a slice reaches unrelated files, narrow the boundary before continuing.
Small slices also make agent usage easier to evaluate. Fluxo bills per real token, including cache reads and writes, with no monthly fee; inspect usage alongside each accepted patch. Create a Fluxo account if you want to try this workflow with your own repository. Users also earn a referral share when people they invite pay.
Stop when the next extraction needs a design decision. A shorter file is useful only when its responsibilities become easier to follow.