CSS 전처리기 마이그레이션 회고

배경과 목표

모바일웹 정적 리소스 저장소의 CSS 빌드 환경이 더 이상 유지보수되지 않는 레거시 전처리기 위에 구축되어 있었습니다. 수천 개의 SCSS 파일이 @import 방식으로 결합되어 있어 변수 충돌, 의도치 않은 상속, 빌드 시간 증가 등 여러 문제가 누적되고 있었습니다.

이를 해결하기 위해 최신 Dart 기반 전처리기로의 전환을 추진했으며, 단순한 문법 변경을 넘어 빌드 파이프라인 전체를 재설계하는 것을 목표로 했습니다.

주요 작업 내용

• 빌드 환경을 Dart 기반으로 교체, 기존 빌드 도구와의 호환성 확보
• 전체 SCSS 파일의 @import를 @use/@forward로 일괄 전환
• AI 코딩 도구를 활용해 수천 개 파일을 일관된 규칙으로 자동 변환
• 변환 결과물의 CSS diff를 수동 검증하여 누락·오류 수정
• Watch 모드 및 부분 빌드 기능 개선으로 개발 시 빌드 효율 향상
• 미사용 CSS 36개 파일 식별 및 제거

기술적 성과

빌드 성능 비교

• 네임스페이스 도입으로 변수·믹스인 충돌 가능성 제거, 코드 가독성 향상
• 각 partial 파일 단위로 빌드되어 의도치 않은 상속 문제 해소
• @use ... with 구문으로 컨텍스트별 변수 오버라이드 가능

// 네임스페이스로 출처를 명확히 한 사용 예시
@use "../../common/mixins" as *;
@use "../mixins/mixins" as search_mixins;

@include search_mixins.slick-dot($border-color: "none");

// 엔트리에서 partial 변수를 오버라이드하는 예시
@use "../order/component/message" as * with (
  $gift-type: false
);

AI 활용 전략

수천 개 파일의 문법 변환을 수작업으로 진행하기엔 비현실적이었기에, AI 코딩 도구의 자동 변환 기능을 적극 활용했습니다.

• 팀 전용 규칙(Rule) 파일을 작성하여 AI가 일관된 변환 결과를 생성하도록 유도
• 변환 후 반드시 빌드된 CSS diff를 사람이 검증하는 프로세스를 수립
• AI가 불필요한 수정(주석 제거, 포맷 변경)을 하는 케이스를 발견 → 프롬프트 개선으로 해결

팀 회고 요약

좋았던 점

AI를 활용한 대규모 일괄 변환으로 시간 단축. 프로젝트 전반의 SCSS 구조와 히스토리를 이해하는 계기가 됨. 마지막 검증·배포 과정에서 팀 전체 협업이 원활했음.

아쉬웠던 점

기존 SCSS 구조의 복잡한 의존성까지 개선하진 못함. 사전 경험 부족으로 시행착오 발생. AI 신뢰도 편차로 diff 검증 비용 증가.

다음 시도

AI 활용 표준 프롬프트 가이드 정리, SCSS 의존성 구조 개선, 내장 함수 활용 스터디, 다른 저장소 확대 적용 계획.