---
type: knowledge
domain: architecture
status: active
last-reviewed: 2026-07-27
---

# 마이그레이션·전환 설계

> 한 줄 정의
> 돌아가는 시스템을 **세우지 않고 바꾸는** 전환의 공통 원리 — 레거시 대체·스키마 변경·데이터 이관에 같은 뼈대가 적용된다. SI 이관 실무(이관 계획서·정제 책임·리허설 계약)는 [[02_데이터·DB 설계]]가 정본, 계약(API) 차원의 진화는 [[호환성과 계약 진화]].

## 1. 기본값 — 빅뱅 금지, 점진 전환

- 한 번에 갈아끼우는 cutover는 되돌릴 수 없는 순간을 스스로 만드는 것이다. **기본값은 신·구 공존 구간을 둔 점진 전환**이며, 빅뱅은 공존이 불가능하다는 증명(기술·계약 근거)이 있을 때만 ADR로 채택한다 ([[설계 결정과 리뷰]]).
- 전환의 모든 단계는 두 질문을 통과해야 한다: **이 단계만 배포할 수 있나? 이 단계만 되돌릴 수 있나?** 하나라도 "아니오"면 단계를 더 쪼갠다.

## 2. Strangler Fig — 레거시 대체의 표준형

1. 레거시 앞에 **라우팅 지점**(파사드·프록시)을 세운다 — 소비자는 이 지점만 본다.
2. 기능 단위로 새 구현을 만들고 라우팅을 **하나씩** 새쪽으로 돌린다 ([[우선순위와 스코프]]의 수직 슬라이스와 동형).
3. 옛길은 트래픽 0이 확인될 때까지 유지한다 — 롤백 = 라우팅 되돌리기.

- 순서는 리스크 역순이 아니라 **학습 우선**: 대표적이면서 작은 기능 하나로 전환 파이프라인 전체(라우팅·모니터링·롤백)를 먼저 증명한다.

## 3. Expand–Contract — 스키마 변경의 표준형

깨지는 스키마 변경을 배포 가능한 단계로 분해한다:

| 단계 | 작업 | 롤백 |
|---|---|---|
| 1. Expand | 새 컬럼·테이블 **추가** (옛것 유지) | 추가분 제거 |
| 2. Dual write | 신·구 양쪽에 쓰기 | 새쪽 쓰기 중단 |
| 3. Backfill | 과거 데이터 채우기 + **대조 검증** | 재실행 가능(멱등하게 작성) |
| 4. Read switch | 읽기를 새쪽으로 전환 | 읽기 되돌리기 |
| 5. Contract | 옛 컬럼 제거 — **사용량 0 확인 후** | 여기부터 어렵다 — 그래서 마지막 |

- dual write 없이 backfill만 하면 백필 중 쓰인 데이터가 유실된다 — 2→3 순서는 바꿀 수 없다.
- 코드 배포와 스키마 변경은 항상 분리 배포한다: 어느 한쪽만 롤백해도 동작해야 한다.

## 4. 검증 — 전환의 근거는 대조 데이터

- **듀얼 런/섀도우**: 신·구를 병행 실행해 결과를 대조한다. "새 시스템이 맞다"의 근거는 리뷰가 아니라 대조 일치율이다.
- 데이터 이관 검증은 3층: 건수 일치 → 집계값(합계·분포) 일치 → 샘플 레코드 대조. 각 층의 허용 오차와 **중단 기준(몇 % 불일치면 롤백)**을 리허설 전에 합의한다 ([[02_데이터·DB 설계]] 리허설 원칙).
- 정합 창(freeze·이중 기록 구간)은 짧을수록 좋지만, 없애는 것보다 **명시**하는 것이 먼저다 — 창 동안의 변경분 처리 방법이 이관 설계의 절반이다.

## 5. 되돌림과 종료

- 롤백 불가 단계(계약상 cutover 선언·옛 시스템 폐기·라이선스 종료)는 **가장 마지막에** 배치한다 — [[분산 신뢰성 패턴]]의 "보상 불가 단계 후치"와 동형.
- 전환의 완료는 새것의 가동이 아니라 **옛것의 제거**다: 트래픽 0 확인 → 제거 일정 합의 → 실제 제거. "나중에 지우자"로 남긴 옛길은 영구 이중 유지보수가 된다.
- 외주·SI에서는 옛 시스템 폐기·병행 운영 기간·그 비용 부담이 계약 사항이다 — 기술 판단만으로 폐기하지 않는다 ([[SI 수주와 범위 관리]]).

## 안티패턴

- **빅뱅 cutover** — 되돌림 없는 주말 작업. 실패 시 월요일이 없다.
- **dual write 생략한 백필** — 백필 완료 시점과 데이터 최신 시점이 어긋나는 고전적 유실.
- **대조 없는 전환 선언** — "새 시스템도 잘 돌아요"는 증거가 아니다. 일치율 숫자가 증거다.
- **옛길 방치** — 전환 종료 조건에 제거가 없으면 시스템이 둘로 늘어난 것이다.
- **코드·스키마 동시 배포** — 한쪽 롤백이 다른 쪽을 깨는 결합. 항상 분리한다.

## 관련 문서

- [[00_설계 허브]] · [[호환성과 계약 진화]] · [[아키텍처 스타일 선택]] · [[분산 신뢰성 패턴]] · [[설계 결정과 리뷰]]
- [[02_데이터·DB 설계]] · [[SI 수주와 범위 관리]]