Refactor a Heavy Codebase

What this pack solves

You inherited the file. It's 4,300 lines, named OrderService.ts, and nobody on the team will touch it. You need to split it, type it, or kill it — and the existing test suite covers 18%. Letting an LLM rewrite the whole thing from a prompt is how prod goes down at 2am. Letting yourself rewrite it by hand is how the quarter disappears.

This pack is the pipeline working engineers use instead: a coverage gate first, structural codemods for the 80% of mechanical changes, an AI agent for the ambiguous surgery, and a structural diff review before merge. Every tool here is for a specific stage. Install in order, use in order.

The five-stage pipeline

Stage 1 — Lock the behavior (coverage gate)

1. Tidy First (Kent Beck's discipline, packaged as a skill) — separates structural changes (rename, extract, move) from behavioral changes (logic). The discipline: never do both in the same commit. The skill enforces it. Read this before you touch anything.
2. Technical Debt Manager (Claude Code agent) — scans the target file/module and produces a ranked list: what to fix first, what the blast radius looks like, where coverage gaps will hide regressions. Use the output to write characterization tests for the current behavior before you change anything. If your coverage on the touched paths isn't ≥80%, stop and write tests first. This is the gate.

Stage 2 — Mechanical changes (codemods, not LLMs)

3. ast-grep — structural search-and-replace using tree-sitter. Find every callsite of getUserById(string) and rewrite it to getUserById({ id: string }) in one command, across 2,000 files, with zero false positives from string matching. This is the right tool for the 80% of a refactor that is mechanical.
4. GritQL — declarative pattern rewrites, slightly higher-level than ast-grep. Better when the transformation involves moving code between blocks (extract method, inline variable). Pick GritQL when the rule reads like "if you see X near Y, rewrite as Z".
5. Codemod — AI-powered migration CLI. Use for migrations the open-source community has already encoded (React class→hooks, Mocha→Vitest, Node http→fetch). Check the registry before writing your own codemod.

Stage 3 — The ambiguous surgery (AI agent)

6. Refactoring Specialist (Claude Code agent) — install path development-tools/refactoring-specialist. Hand it the file with the failing test and clear instructions: "extract these three methods into a PricingPolicy class, keep the public interface of OrderService unchanged, do not touch behavior". The agent will produce a diff. You review.
7. code-simplifier — Anthropic's official cleanup subagent. After the agent does the heavy lift, run code-simplifier across the diff to collapse trivial verbosity (nested ternaries, repeated guards). Surgical, scoped.

Stage 4 — Remove the bodies

8. Unused Code Cleaner (Claude Code agent) — after the split, dead imports, unused exports, and orphaned helpers will litter the diff. This agent finds them with cross-reference, not regex. Run it last, before the diff review — never before, because mid-refactor the "unused" stuff is often about to be wired up again.
9. Legacy Modernizer (Claude Code agent) — for the move-to-typed leg specifically: untyped JS → TS, Python → typed Python, callback → async. Use after Stage 2 codemods if the refactor includes a language/idiom upgrade.

Stage 5 — The merge gate (structural diff review)

10. code-review-graph MCP — gives your code-review agent (or you) a graph-aware view of the diff: which callers are affected, what changed in the public interface, where the test coverage gaps now sit. This is the last gate before merge. If the graph shows untested paths in the diff, send it back to Stage 1.

How they fit together

[Stage 1] Tidy First ──> Technical Debt Manager ──> characterization tests
                                                          │
                                                          ▼ (coverage ≥80%)
[Stage 2] ast-grep / GritQL / Codemod  ◀─── 80% mechanical changes
                                                          │
                                                          ▼
[Stage 3] Refactoring Specialist ──> code-simplifier  ◀─ ambiguous surgery
                                                          │
                                                          ▼
[Stage 4] Unused Code Cleaner ──> Legacy Modernizer (if typed migration)
                                                          │
                                                          ▼
[Stage 5] code-review-graph MCP  ─────────────────> merge

The critical rule: don't skip Stage 1. Every horror story about an AI agent "refactoring" a codebase into rubble starts with a missing characterization test. The agent moved code that looked dead and was actually load-bearing. Tests catch that. Nothing else does.

Tradeoffs you'll hit

• ast-grep vs GritQL — ast-grep is faster, simpler, ships everywhere. GritQL is more expressive when patterns need control flow. Default to ast-grep; reach for GritQL when the rule needs to say "after the assignment, before the return".
• Refactoring Specialist vs writing the diff yourself — for splits under 200 lines, the agent is overkill. For splits over 1,000, hand-writing is overkill. Sweet spot: 200-1,500 line surgical extractions where you know the target shape.
• Unused Code Cleaner timing — if you run it during Stage 2, it will delete code you're about to wire back up in Stage 3. Run last. Always.
• Codemod registry coverage — for popular migrations (React, Mocha, Node), the registry is gold. For your internal API rename, you'll write your own ast-grep rule. Don't fight it.

Common pitfalls

• Coverage-as-vanity-metric — 80% line coverage on the touched files, not on the repo overall. The agent only cares about the blast radius. Repo-wide coverage is a manager's number.
• Letting an LLM rewrite a whole file — paste the file into Claude, get back "cleaner" code, ship it. This is the route to a 2am page. The pipeline above is the alternative: small, reviewed, gated diffs.
• Forgetting to commit between stages — every stage produces a reviewable diff. Commit at every stage boundary. Bisecting later requires it.
• Running Unused Code Cleaner on partial refactor — it will delete the helpers Stage 3 is about to call. Last step, every time.