Skip to content
Back to AI Coding

Claude Code Agentic Refactoring Patterns

Drive safe large-scale refactors with Claude Code: scope, plan, checkpoint, verify.

Claude CodeAdvanced

Why

Stack Overflow's 2025 Developer Survey reports 9.7% of developers use Claude Code, and JetBrains' January 2026 AI Pulse found 18% of professional developers use it at work, up 1.5x since September 2025. Large refactors (rename a core type, swap a framework, migrate 200 files) are where agentic tools earn their keep, but they are also where they do the most damage if unsupervised.

A scoped, checkpointed pattern turns a risky 2-hour manual refactor into a 15-minute supervised run with a clean git history you can bisect.

When

Use this pattern for refactors that span more than ~10 files or touch a shared type many modules import. Avoid it for single-file edits (use Cursor Cmd+K) and for changes you cannot describe as a mechanical rule (those need human judgment per site).

How

1. Start from a clean tree and create a refactor branch: git checkout -b refactor/migrate-zod 2. Scope the task explicitly to prevent blast radius: "Only modify files under src/api/ and src/middleware/. Do not touch src/data/." 3. Ask for a plan first, not code: "List every file that imports 'validateBody' and the change needed in each. Do not edit yet." Review the plan. Reject or adjust before greenlighting execution. 4. Execute in checkpoints with a commit per step: "Migrate src/api/users.ts to zod. Run tsc. Commit if green. Stop on error." 5. Verify continuously. After each commit run the gate: npm run check && npm test If red, paste the error back: "fix the tsc error in src/api/users.ts you just created". 6. Inspect the result with git, not the chat: git log --oneline refactor/migrate-zod ^main git diff --stat main..refactor/migrate-zod Review any file outside the declared scope as a red flag. 7. Merge only after a full gate pass and a human review of the diff stat: npm run check && npm test && npm run build git checkout main && git merge --no-ff refactor/migrate-zod

Example

Migrating 40 routes from a hand-rolled validator to zod: $ git checkout -b refactor/zod-migration $ claude > Scope: only src/api/**/*.ts. Do not touch src/data/ or tests yet. > Step 1: list every route using 'assertValid(req.body)' and the zod schema it needs. Output a table, do not edit. [review the 40-row table, confirm schemas] > Step 2: for each route in the table, replace assertValid with a zod schema + safeParse, run tsc, commit per route. Stop on first error. Result: 40 commits, all green. Inspect: $ git diff --stat main..HEAD src/api/users.ts | 12 +- src/api/books.ts | 14 +- ... (40 files, 0 outside src/api/) Clean scope, bisectable history, zero files outside the declared scope.

Common Problems

  • ⚠Error: Cannot find module '@anthropic-ai/claude-code' → run `npm install -g @anthropic-ai/claude-code`; requires Node.js 18+.
  • ⚠"Error: ENOTFOUND api.anthropic.com" → check `echo $ANTHROPIC_API_KEY` is set and network/proxy allows api.anthropic.com:443.
  • ⚠Broken intermediate commits: a red commit in the middle breaks bisect. Configure stop-on-error and never commit red.
  • ⚠Error: Cannot find module '@anthropic-ai/claude-code' → run `npm install -g @anthropic-ai/claude-code`; requires Node.js 18+.

Best Practices

  • ✓Always ask for a plan first and review it before any edits. Plans are cheap, wrong edits are not.
  • ✓Declare a hard scope and verify it with git diff --stat after every run. Reject any out-of-scope file.
  • ✓Commit per logical step with conventional messages so the history is bisectable.
  • ✓Run the full gate (check + test + build) before merging, not just tsc.
  • ✓Use a dedicated refactor branch and merge with --no-ff to preserve the step history.

FAQ

How do I scope a Claude Code refactor to prevent blast radius?

Declare a hard scope in the prompt ('only modify files under src/api/, do not touch src/data/') and verify with `git diff --stat` after the run. Reject any file outside the declared scope. Scoping is the single most important safety control for agentic refactors.

Why ask for a plan before edits?

On a 40-file refactor, jumping straight to edits produces 40 wrong edits. Asking for a plan first ('list every file and the change needed, do not edit yet') lets you catch misunderstandings cheaply. Plans are reviewable in seconds; wrong edits take minutes to undo.

How do I keep refactor commits bisectable?

Commit per logical step with conventional messages ('feat(api): migrate users route to zod') and never commit red. Configure stop-on-error so a type failure halts the run instead of leaving a broken intermediate commit in history.

What if Claude loses context mid-refactor?

Long sessions forget the original rule. Use /compact to compress history, then re-state the scope rule and spec immediately after compacting. For very large refactors, split into multiple sessions with serialized JSON handoffs between them.

How do I verify a large refactor before merging?

Run the full gate (npm run check && npm test && npm run build) on the refactor branch, review `git diff --stat main..HEAD` for out-of-scope files, and do a human review of the diff. Merge with --no-ff to preserve the step history for bisection.