Claude Code Learning Hub
中文 Mingyu's Library

Hub / Tips / B · Parallelism & throughput

What to do when a change touches 200 files

Changing import paths, migrating a component library, renaming an API — one change spread across hundreds of files. Grinding through them one by one in a single session is slow and misses things.

The key to a large-scale change isn't "make the AI edit faster" — it's locking the change into a pattern first, then picking the right executor: deterministic transforms go to a script, judgment calls fan out to agents, and spot checks plus full validation catch whatever slips through.

One-line answer

Answer Our takeThree steps: ① lock the change into an explicit pattern on 3–5 representative files and confirm it by hand; ② for purely mechanical text/AST transforms, have Claude write a script and run it once (fast, zero tokens, rerunnable) — only fan out with a workflow/subagents when each file needs individual judgment; ③ when done, spot-check random diffs, then run type checks/tests as full validation, and keep fixing until they pass.

Steps

  1. Lock the pattern on a small sample.Pick 3–5 representative files (one ordinary, one edge case, one worst case) and have Claude change those first; confirm the approach by hand.OfficialThe workflows docs give the same advice in the cost section: run a small slice of a big task first — "one directory instead of the whole repo" — before deciding to roll it out.
  2. Decide: script or LLM.Our takeThe criterion is "can the change be written as a rule":
    Nature of the changeExecutorExamples
    Deterministic transform: one rule applies to every fileHave Claude write a script/codemod and run it onceChanging import paths, renaming a function, bulk-replacing config keys
    Per-file judgment: rules can't cover everything, context mattersFan out with a workflow / subagents, one agent per fileMigrating styled-components to Tailwind, adding auth checks to every route
    A script's advantage is that the result is diffable and reviewable, and if it's wrong you fix the script and rerun; 200 files are 200 chances for an LLM to be inconsistent, but just one loop for a script.
  3. When you do fan out to agents, prefer a dynamic workflow.OfficialSay "use a workflow" in your prompt, or add the keyword ultracode, and Claude writes the orchestration as a script that runs in the background, keeping intermediate results in script variables instead of crowding the conversation context; the migration example in the docs is exactly "migrate every component under src/components/ from styled-components to Tailwind, working on each file in its own isolated copy". /workflows shows agent and token counts per stage, and workflows can be paused and resumed. Limits: at most 16 agents concurrently, 1000 per run; beyond 25 agents or a projected 1.5M tokens you get a "Large workflow" warning. Requires v2.1.154+ on a paid plan.
  4. For reviewable PRs, use /batch.Official/batch is a built-in skill: it splits one large change into 5–30 worktree-isolated subagents, each opening its own pull request, so review naturally happens at PR granularity. How worktree isolation works: Worktrees: keep parallel sessions out of each other's way.
  5. For CI or full scripting, go headless.Officialclaude -p "<instruction>" --allowedTools "Read,Edit" runs one task non-interactively; the exit code can drive script branching, --output-format json returns structured results, and adding --bare skips loading hooks/plugins — a good fit for per-file calls inside a loop. Details in D13 · Headless & CI.
  6. Finish with spot checks plus full validation.Our takeRandomly sample 5–10 files and read the diffs by hand to confirm the pattern didn't drift; then run full validation.OfficialWorkflows have a ready-made closing pattern for this: "run npx tsc --noEmit and keep fixing the reported errors until the type check passes", plus adversarially verifying each finding before reporting it.
  7. Cost note.OfficialA workflow fanning out dozens of agents consumes noticeably more tokens than a single conversation, and it counts toward your plan usage — one more reason step 2 reaches for a script first.

Copy-paste prompt

I need to roll this change out across the whole repo (about 200 files):
<change description>.
Work in three steps, pausing for my confirmation between each:

1. First find every file that needs the change and report the count, then
   pick 3 representative ones (the most ordinary, the most complex, the
   most edge-case) and change those for me to review. Wait for me to
   confirm the approach;
2. Once confirmed, decide how to execute: if the change is a
   deterministic text/AST transform, write a repeatable script and run it
   once — show me the script first; if each file needs individual
   judgment, use a workflow to fan out, changing each file in an isolated
   copy;
3. When everything is done: show diffs for 5 randomly chosen files, then
   run <type check/test command> and keep fixing until it passes.
   Finally report the total number of files changed and the validation
   results.

Sources & last verified