Refactoring at Scale: How AI Handles 800-File Renames Without Drift

The Class Of Work Most Refactoring Skips

A symbol rename across 800 files is the kind of work senior engineers used to absorb personally. It is high-touch, low-creative, and obvious to defer when there is something else to ship. Across a typical 10-year codebase, hundreds of such refactors sit undone because nobody could justify the two days they would take.

AI changes the economics. A well-orchestrated rename pipeline does the same work in 20 minutes with no behavioral drift. This post is how.

What "Without Drift" Means

A safe rename has three properties:

• Comprehensiveness. Every reference is updated. No straggler import, no string usage in test fixtures, no comment referring to the old name (unless we explicitly choose to keep comments historical).
• Locality. Only the symbol named is touched. Adjacent code is not "improved." The diff is exactly the rename and nothing else.
• Semantic identity. The behavior of the code after the rename is identical to before. No tests should change behavior. No subtle binding changes.

A naive rename (find-and-replace), fails all three. It misses references in dynamic contexts. It accidentally edits unrelated symbols with the same string. It changes behavior when the original name was bound dynamically.

The Pipeline

Four stages:

Stage 1: AST-aware identification. Walk the codebase with a language-aware parser. Identify every reference to the symbol, definition, callers, imports, type references. Do not match strings; match AST nodes.

Stage 2: Dynamic reference detection. Some references are not in the AST (string-based imports, getattr, eval). Run a secondary pass with heuristic regex on the known patterns. Surface ambiguous matches for human review.

Stage 3: Diff generation. Produce the rename diff for every confirmed reference. The diff is mechanical at this stage, no LLM reasoning, just structured edits.

Stage 4: Validation. Run the test suite. Run any type checker. Diff the bytecode (for languages where this is meaningful). Verify that the only changes are the renames.

The LLM's job in this pipeline is at stage 2, disambiguating dynamic references that the parser cannot resolve confidently. Stages 1, 3, and 4 are deterministic tooling.

Why The LLM Is Not Doing The Rename

This is counterintuitive in an AI-coding post. The LLM is not the rename engine because:

• The work is structural, not creative. AST tools do it more reliably and faster.
• The LLM occasionally introduces errors in mechanical transformations that AST tools do not.
• The cost difference is substantial. AST rename of 800 files costs cents. LLM rename of 800 files costs tens of dollars.

The LLM is in the loop for one specific thing: deciding which references in ambiguous contexts are actually the same symbol. That is judgment work, which the LLM is good at, and which AST tools are not.

The Categories Of Rename

Three risk tiers:

Safe. Internal symbol with no public API exposure, no dynamic references, no string references in tests. Most renames. Pipeline runs unattended.

Medium. Public API symbol, but with no external consumers within the org's monorepo. Pipeline runs and produces a PR; human reviewer signs off.

Dangerous. Public API with external consumers, or symbol used in serialization (JSON keys, database column names, environment variables). Pipeline produces a plan with a compatibility shim and a deprecation timeline. Human leads.

Most teams skip the planning of which tier a rename falls into. The tier classification is a 5-minute conversation that prevents 90% of rename incidents.

What Goes Wrong Without The Pipeline

Three real failures we have seen from naive (LLM-only or human-only) renames:

The serialized rename. A column was renamed in code. The database column was not. The ORM had implicit mapping. Tests passed locally but production broke on first query. The fix: serialization renames need explicit migration choreography.

The dynamic miss. A symbol was referenced by name in a configuration file. The renamer did not check config files. Production loaded the old name on startup and crashed. The fix: include config and template files in the reference walk.

The same-named neighbor. A symbol foo was renamed. The codebase also had a class method foo on an unrelated class. The renamer caught both. The fix: AST-aware identification distinguishes them; naive string replace does not.

The pipeline above addresses each of these.

What About Cross-Repo Renames

A symbol renamed in one repo and consumed by 12 others is the harder case. The pipeline extension:

• Identify all consuming repos (via a service registry or manual list).
• Produce a per-repo rename PR.
• Produce a coordinator PR in the source repo that ships the old name as a shim with a deprecation date.
• Schedule the shim removal for the date after all consumer PRs merge.

For the multi-repo coordination story more broadly, see multi-repo cross-service tickets.

A Specific Example

A platform team had a 4-year-old symbol process_event that was used 800 times across the monorepo. The team had wanted to rename it to handle_event for consistency, but no one had the two days. They ran the pipeline.

• Pipeline runtime: 22 minutes.
• References updated: 803 (the AST walk found 3 they did not know about).
• Dynamic references that required disambiguation: 6 (the LLM flagged them, the human approved 5 and rejected 1 as a same-named unrelated symbol).
• Test failures: 0.
• Reviewer time: 35 minutes (walking through the diff highlights).
• Outcome: clean rename, merged same day.

The team estimated this would have been about $1,500 of engineering time in the old workflow. Pipeline cost: $4 in compute, mostly LLM disambiguation.

The Generalization

Most mass refactors are renames or moves. The same pipeline shape (AST identification, LLM disambiguation of dynamic references, deterministic diff generation, validation), handles file moves, namespace migrations, and signature changes.

The pattern is: lean on deterministic tools for the bulk of the work, use the LLM specifically for the judgment moments, and never blur the line between them. That separation is what keeps the work fast and the drift at zero.

For the broader refactoring strategy, see AI for legacy modernization. For scaling these patterns across many repos, see scaling AI across 500 repositories.