# [[Incremental Migration]]

## 📌 Brief 시 Summary
**Incremental Migration(점진적 마이그레이션)**은 오래된 기술이나 아키텍처에서 새로운 기술로 전환할 때, 전체 시스템을 한 번에 재작성(complete rewrite)하는 대신 단계적으로 이동하는 전략을 의미합니다 [1]. 한 번에 모든 것을 변경하는 위험을 최소화하고, 아키텍처를 현대화하는 동안에도 기능 개발을 지속할 수 있게 해주는 **"재작성(rewrite)이 아닌 리팩토링(refactor)"** 철학에 기반합니다 [1]. 대표적인 예로, Context API에서 Zustand로 상태 관리를 전환할 때 알림과 같은 단순한 유틸리티부터 시작하여 결제 흐름과 같은 복잡한 도메인으로 점진적으로 영역을 넓혀가는 방식이 있습니다 [1].

## 📖 Core Content
*   **전면 재작성의 위험성 회피:** 기존 기술에서 새로운 기술로 전환할 때, 애플리케이션 전체를 한 번에 갈아엎는 전면 재작성(complete rewrite)은 너무 높은 위험을 수반합니다. 점진적 마이그레이션은 이 리스크를 우회하는 권장 접근법입니다 [1].
*   **단계적 전환 (스토어 단위 이동):** 한 번에 하나의 스토어(store)씩 이동하는 방식이 효과적입니다 [1]. 알림(notifications)과 같은 상대적으로 단순하고 독립적인 유틸리티성 상태부터 시작하여, 점진적으로 장바구니나 체크아웃 흐름(checkout flow) 같은 복잡한 핵심 도메인으로 전환을 진행합니다 [1].
*   **기능 개발과 아키텍처 현대화의 병행:** 이 접근법의 핵심적인 이점은 리팩토링 철학을 기반으로 하기 때문에, 시스템 구조를 현대화하는 중에도 비즈니스 요구사항에 맞춘 새로운 기능 개발을 중단 없이 계속할 수 있다는 점입니다 [1].
*   **커스텀 훅(Custom Hook)을 활용한 리팩토링 단위화:** 모던 React 환경에서 리팩토링의 주요 단위는 커스텀 훅입니다 [2]. 거대한 컴포넌트 내부에서 로직을 추출해 훅으로 분리함으로써 모듈성과 테스트 가능성을 높이며, 이를 통해 점진적인 구조 개선 및 마이그레이션을 안전하게 수행할 수 있습니다 [2].

## ⚖️ Trade-offs & Caveats
소스 내에서 점진적 마이그레이션 자체의 심각한 부작용을 명시하고 있지는 않으나, 전환을 시도하는 기술과 조직 상황에 따라 마이그레이션 경로(Migration Paths)별 난이도와 한계가 존재합니다 [3].
*   **기술 스택별 전환 난이도의 차이:** Context API에서 Zustand로의 전환은 비교적 쉽다(Easy)고 평가되지만, Zustand에서 Redux로의 점진적 전환은 고통스러울 수 있으며(Painful), Redux에서 Zustand로 전환하는 것은 가능하지만 위험(Possible but risky)이 따릅니다 [3].
*   **기술 변경 시점의 모호함:** 규모 확장 단계(Scaleup, 50-500명)의 기업에서는 Zustand 같은 도구를 사용하다가 한계에 부딪힐 때 Redux로의 마이그레이션을 계획해야 하는데 [4], 이처럼 언제 점진적 마이그레이션을 결단하고 시작해야 하는지에 대한 구조적 고민과 전환 부하가 발생할 수 있습니다. 

## 🔗 Knowledge Connections

### Related Concepts

#### [관계 유형 A: 아키텍처/기반 기술]
- [[Context API]]
  - 연결 이유: 점진적 마이그레이션의 주요 출발점(레거시 기술) 사례로 소스에서 언급되었습니다 [1].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 마이그레이션 이전의 레거시 상태 관리가 어떤 문제를 겪는지 파악하고, 왜 단순한 도메인부터 전환을 시작해야 하는지에 대한 당위성을 이해할 수 있습니다.
- [[Zustand]] / [[Redux]]
  - 연결 이유: 마이그레이션의 목적지 또는 전환 경로에 해당하는 상태 관리 기술들입니다 [1, 3, 4].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 각 기술 간의 전환이 쉬운지(Easy), 고통스러운지(Painful) 파악하여 조직 규모에 맞는 목표 아키텍처를 어떻게 설정하고 이동할 것인지 판단할 수 있습니다.

#### [관계 유형 B: 구현/리팩토링 도구]
- [[Custom Hooks]]
  - 연결 이유: 모던 React에서 구조를 점진적으로 변경할 때 사용하는 '리팩토링의 핵심 단위(primary unit)'입니다 [2].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 거대한 컴포넌트의 비즈니스 로직을 UI와 어떻게 분리하여 모듈성과 테스트 용이성을 확보하는지 실무적인 구현 관점에서 이해할 수 있습니다.

### Deeper Research Questions
- 기존 상태 관리(예: Context API)와 신규 상태 관리(예: Zustand)가 공존하는 점진적 마이그레이션 과정에서, 두 상태 간의 동기화나 의존성은 어떻게 처리해야 안전한가?
- Zustand에서 Redux로의 마이그레이션이 특히 "고통스럽다(Painful)"고 평가되는 아키텍처적, 구현적 차이점은 무엇인가?
- 마이그레이션과 신규 기능 개발을 병행할 때 발생할 수 있는 브랜치(Branch) 충돌이나 통합 문제를 해결하기 위한 Git Workflow는 어떻게 구성되어야 하는가?
- 대규모 애플리케이션에서 커스텀 훅 단위로 로직을 분리하는 리팩토링을 진행할 때 성능 저하(오버헤드)를 유발하지 않는 최적화 방법은 무엇인가?
- 시스템의 일관성을 유지하기 위해, 한 기술에서 다른 기술로의 '점진적 마이그레이션'이 최종 완료되었다고 판단하는 기준(Definition of Done)은 어떻게 정의해야 하는가?

### Practical Application Contexts
- **Implementation:** React 코드베이스에서 새로운 상태 관리 라이브러리를 도입할 때, 전체를 교체하지 않고 에러 알림 등 아주 독립적인 단위 기능부터 새로운 스토어에 연결해 나가는 방식으로 구현을 진행합니다 [1].
- **System Design:** 소프트웨어를 현대화할 때, 빅뱅(Big Bang) 방식이 아니라 기존 서비스가 지속적으로 운영 및 확장되면서 레거시와 신규 아키텍처가 공존할 수 있는 설계 원칙을 수립합니다 [1].
- **Operation / Maintenance:** 기능 개발 부서와 아키텍처 개선 부서가 분리되지 않고, 유지보수 일정 내에서 기능 배포와 기술 부채(Technical Debt) 감소를 동시에 이뤄내도록 운영합니다 [1].
- **Learning Path:** 큰 컴포넌트를 분해하여 Custom Hook으로 독립시키는 연습을 통해, 향후 코드 마이그레이션에 필요한 모듈화 역량을 학습합니다 [2].
- **My Project Relevance:** 현재 진행 중인 프로젝트에서 구형 라이브러리(또는 패턴)를 최신 기술로 업그레이드해야 하는 태스크가 주어졌을 때, 비즈니스 영향을 최소화하는 점진적 적용 로드맵을 작성하는 데 활용할 수 있습니다.

### Adjacent Topics
- [[Technical Debt Management (기술 부채 관리)]]
  - 확장 방향: 점진적 마이그레이션은 결과적으로 기술 부채를 통제하고 해결하기 위한 여러 전략 중 하나이므로, 시스템이 노후화됨에 따라 기술 부채를 어떻게 측정, 관리, 상환하는지에 대한 넓은 관점의 엔지니어링 전략으로 학습을 확장할 수 있습니다 [1].

---
*Last updated: 2026-04-30*