2nd/10_Wiki/Topics/Legacy_React_Migration.md

id, category, confidence_score, tags, last_reinforced, github_commit

id	category	confidence_score	tags	last_reinforced	github_commit
7f8e9d2c-b1a3-4e5f-a0b2-c1d2e3f4a5b6	Dev	0.98	react legacy migration refactoring incremental-migration architecture frontend	2026-05-01	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, TanStack Query, Zustand, Unit Testing, 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