Skip to content

PATTERN Cited by 1 source

Audit-then-refactor migration

A repeatable playbook for rolling out a new code-level invariant (new ID type, new API, deprecated helper, etc.) across a large multi-team codebase, without a big-bang rewrite.

Steps

  1. Automated audit. Scripted pattern match (regex / AST / type graph) locates every call site that touches the thing being changed. Output: a candidate list — expected to be noisy.
  2. Map to team ownership. Use the directory layout / CODEOWNERS / service registry to turn each candidate into a work item assigned to a specific owning team. Turns the migration from one intractable project into N tractable per-team ones.
  3. Manual review for context. Owners triage each finding: internal-only vs. externally exposed, safe-to-rewrite vs. needs business-logic judgment. This step is non-negotiable — the pattern match doesn't know intent.
  4. AI-assisted refactor with humans in the loop. An LLM proposes the diff per finding; an engineer reviews, refines, and lands it. Humans stay on the hook for correctness; the AI handles volume.
  5. Type safety + tests as the safety net. Make the invariant expressible in the type system (e.g., distinct types for the old and new IDs) so any regression surfaces at compile time. Linters and code-review rules enforce boundaries.
  6. Company-wide coordination. Shared tracker / hub so progress is visible across teams, and the migration goal is a named priority across engineering, product, privacy, legal, etc.

When to use

  • Wide-fanout invariants (every data-access site needs to change).
  • Changes where per-team context matters and a blanket find-and-replace would ship bugs.
  • Organizations large enough that central enforcement doesn't scale but decentralized execution does.

Seen in

  • sources/2026-04-14-airbnb-privacy-first-connections — Airbnb migrated every user-data access site to the new User ID / Profile ID split using exactly this sequence: Python audit scripts → team mapping → manual review → AI-assisted refactor → type safety and shared tracking hub.
Last updated · 200 distilled / 1,178 read