---
id: 7f8e9d2c-b1a3-4e5f-a0b2-c1d2e3f4a5b6
category: Dev
confidence_score: 0.98
tags: [react, legacy, migration, refactoring, incremental-migration, architecture, frontend]
last_reinforced: 2026-05-01
github_commit: "wikification-legacy-react"
---

# Legacy React Migration & Refactoring Standard

## 📌 한 줄 통찰 (The Karpathy Summary)
> 레거시 React 코드베이스의 현대화는 '전면 재작성(Rewrite)'이 아닌 '점진적 리팩토링(Incremental Refactor)'을 원칙으로 하며, 테스트 안전망 구축, 커스텀 훅을 통한 로직 분리, 그리고 FSD 아키텍처 도입을 통해 기술 부채를 체계적으로 해결하는 과정이다.

## 📖 구조화된 지식 (Synthesized Content)

### 1. 리팩토링의 황금률: Refactor, Do Not Rewrite
- **안전망 선구축**: 코드 수정 전 유닛 테스트 및 시각적 회귀 테스트(Storybook, Chromatic 등)를 통해 기존 기능의 무결성을 보장한다.
- **점진적 마이그레이션**: 시스템 전체를 한 번에 바꾸는 대신, 알림이나 작은 기능 단위의 스토어부터 하나씩 최신 상태(Zustand, TanStack Query 등)로 전환한다.

### 2. 컴포넌트 및 언어의 현대화
- **함수형 전환**: 클래스형 컴포넌트를 함수형 컴포넌트와 훅(Hooks) 기반으로 전환하며, 불필요한 `useEffect` 안티패턴을 제거한다.
- **TypeScript 도입**: 정적 타이핑을 통해 코드의 예측 가능성을 높이며, 파일 단위로 점진적으로 적용한다.
- **관심사 분리**: 비대한 컴포넌트(300줄 이상)에서 비즈니스 로직을 **커스텀 훅**으로 추출하여 UI와 로직을 분리한다.

### 3. 상태 관리 및 아키텍처 개편
- **상태 분할**: 서버 데이터(TanStack Query), 전역 클라이언트 상태(Zustand), URL 상태 등으로 목적에 맞게 파편화하여 관리한다.
- **FSD 아키텍처 도입**: 기술적 파일 유형(Type-based) 구조에서 비즈니스 도메인 중심의 **Feature-Sliced Design**으로 개편하여 모듈 간 결합도를 낮추고 응집도를 높인다.

### 4. 코드 거버넌스 및 표준화
- **네이밍 규칙**: `kebab-case`(파일명/폴더명), `PascalCase`(컴포넌트), `camelCase`(훅/변수) 등 운영체제 및 팀 협업 표준을 수립한다.
- **자동화**: ESLint, Prettier, Husky를 활용하여 커밋 시점에 아키텍처 경계 위반 및 포맷팅을 자동으로 검사한다.

## ⚠️ 모순 및 업데이트 (Contradictions & RL Update)
- **추상화의 함정 (DRY vs KISS)**: 중복 제거를 위한 과도한 추상화는 오히려 코드를 블랙박스화하여 디버깅을 어렵게 한다. '세 번 반복될 때까지 기다리기(Rule of Three)' 원칙을 준수해야 한다.
- **과도기적 복잡성**: 점진적 마이그레이션 중에는 레거시와 신규 상태 관리 시스템이 공존하여 일시적으로 구조가 복잡해질 수 있음을 인지하고 마이그레이션 로드맵을 명확히 해야 한다.
- **초기 오버헤드**: FSD 등의 엄격한 구조는 소규모 프로젝트에서는 과도한 설계(Overkill)가 될 수 있으므로 프로젝트 규모에 맞춰 유연하게 적용한다.

## 🔗 지식 연결 (Graph)
- **Parent**: 10_Wiki/Topics/Development
- **Related**: [[Feature-Sliced Design|Feature-Sliced Design]], TanStack Query, Zustand, Unit Testing, [[SOLID Principles|SOLID Principles]]
- **Raw Source**: 00_Raw/레거시 React 코드베이스 마이그레이션, 00_Raw/Incremental Migration, 00_Raw/Legacy React Codebase Modernization, 00_Raw/Legacy React Codebase Refactoring, 00_Raw/React Codebase Refactoring, 00_Raw/프론트엔드 리팩토링 및 코드 유지보수

## 💻 GitHub 동기화 자동화 워크플로우
1. Stage: git add .
2. Commit: `git commit -m "[P-Reinforce] Wikify Legacy React Migration & Refactoring Standard"`
3. Push: `git push origin main`