AI로 디자인시스템 마이그레이션하기 (1): 여정의 시작

인프랩 프론트엔드 팀이 20개 이상의 앱이 의존하는 Mantine 기반 디자인시스템을 v6에서 v8로 올리면서 AI 에이전트를 어떻게 활용했는지 다룬다. 단순 버전업이 아닌 스타일 기반 자체를 교체하는 작업이라 1차 시도가 실패했고, v6/v8 공존 격리 설계와 AI 에이전트 오케스트레이션으로 전사 규모 마이그레이션을 진행했다.

핵심 포인트

Mantine v6 → v8은 스타일 기반 교체 수준의 대공사 — 1차 "한 번에 모두 전환" 접근은 혼합 사용 불가로 실패
CSS 클래스 접두사(mantine-next-) + Provider 분리 + 의존성 격리로 v6/v8 공존 달성, 점진적 전환 가능하게 설계
컴포넌트를 4가지 유형(순수 래핑 ~ 완전 커스텀)으로 분류해 AI 에이전트가 migrate → test → verify 3단계를 독립 세션으로 실행
AST 기반 codemod(ds-codemod)를 자체 개발해 20개 앱의 import 경로와 prop 변환을 자동화
MIGRATION.md + WORK_LOG.md로 에이전트 세션 간 컨텍스트 전달, 실패 시 자동 재시도 및 이력 관리
"AI는 절차와 검증이 명확할 때 진가를 발휘" — 1차 출처 문서화 + 단계별 절차 + 자동 검증 체계가 핵심

상세 정리

마이그레이션 동기: 상위 버전 전용 컴포넌트 필요, TS5 호환성, 반응형 DX 개선, AI 활용을 위한 Storybook 표준화 등 복합 이유로 추진
1차 실패: 기존 v6와 신규 v8 혼합 사용 불가 — 모든 앱을 한 번에 전환해야 한다는 부담이 너무 커서 중단
공존 설계: CSS 클래스명에 mantine-next- 접두사를 추가해 v6/v8 CSS 충돌 방지, 영역별 ThemeProvider 분리로 같은 앱에서 두 버전 독립 동작
의존성 격리: v8 패키지가 자체 @mantine/core 의존성을 포함하도록 구성해 버전 충돌 회피
Emotion 유지: Mantine v7+는 네이티브 CSS로 전환했으나 마이그레이션 복잡도 증가를 피하기 위해 신규 DS에서도 Emotion 유지 결정
컴포넌트 분류: Type1(순수 래핑) ~ Type4(완전 커스텀) 4단계 난이도 체계로 AI 에이전트 작업 범위 명확화
에이전트 인프라: Mantine v6/v8 공식 문서를 로컬 Markdown으로 보관, 색인 파일로 컴포넌트별 필요 문서만 참조해 컨텍스트 낭비 방지
3단계 커맨드 파일: migrate(v8 API 변환) → test(동작 검증 + 비교 테스트) → verify(빌드 + 픽셀 비교)로 표준화, 각 단계 독립 세션 실행
오케스트레이션: MIGRATION.md(현재 단계 추적)와 WORK_LOG.md(단계 간 정보 전달)로 에이전트 세션 컨텍스트 관리, 실패 시 자동 재시도 및 이력 기록
codemod 개발: AST 기반 자동화로 import 경로(@inflearn/ds-react → @inflearn/ds-react-next)와 prop 변환(leftIcon → leftSection, compact → size="compact-sm") 처리
진행 관리: 20개 앱 마이그레이션 진행률 대시보드, 커밋 수 적은 앱부터 시작해 절차 검증 후 복잡한 앱으로 확대
주요 이슈: TS5 전용 문법 에러(pnpm patch 임시 패치), 모듈 페더레이션 싱글톤 충돌(선언 제거), CSS 우선순위(css → styles 속성 전환)
현재 상태: 1차 마이그레이션 완료, v6 패키지 완전 제거 / TS5 버전업 / Storybook 체계화 등 후속 작업 남음