불필요한 SCSS 파일 제거로 개발 환경 정리

프로젝트에 한동안 손 안 댔던 디렉토리를 열면 항상 뭔가 나온다. 이번엔 SCSS였다.

aaa 와 kingdriver 관련 SCSS 파일들이 소스 트리 안에 아직 살아있었다. 실제로 import하는 곳도 없고, 빌드 결과물에 포함되는지조차 불분명한 상태. 이런 파일들은 딱히 "문제"를 일으키는 것처럼 안 보여서 오래 방치된다. 근데 쌓이다 보면 신규 개발자가 온보딩할 때 혼란의 원인이 되고, 나중에 빌드 설정 건드릴 때도 "이거 쓰이는 건지 아닌지" 확인하는 데 시간을 날리게 된다.

총괄 팀장 입장에서 이런 cleanup 작업은 사소하게 느껴지기 쉬운데, 오히려 이게 팀 전체 속도에 직결된다는 걸 반복 경험으로 알게 됐다. 기능 개발 속도만큼이나 코드베이스를 읽는 비용도 중요하다.

SCSS가 orphan 파일로 남게 되는 이유

대부분 서비스나 기능이 deprecated될 때 CSS/SCSS는 뒷순위로 밀린다. 컴포넌트 삭제하고, 라우팅 제거하고, API 연결 끊고 나면 지쳤거나 바빠져서 스타일 파일까지 손이 안 가는 경우가 많다. 기능은 사라졌는데 스타일만 커밋 이력 속에 남는 식이다.

SCSS는 특히 더 그런데, import 체계가 복잡해지면 어디서 실제로 쓰이는지 추적이 까다롭다. @import나 @use로 연결된 참조가 여러 파일에 걸쳐있으면, "혹시 어딘가에서 쓰이는 건 아닌가" 싶어서 손을 못 대는 경우도 생긴다. 결국 확인이 귀찮아서 그냥 놔두게 된다.

이번 케이스가 딱 그 패턴이었다. kingdriver 관련 서비스 컴포넌트는 이미 제거된 상태였는데 스타일 파일만 orphan으로 남아있었고, aaa 쪽은 초기 개발 단계에서 작업하다가 방향이 바뀌면서 그냥 커밋된 채로 묶여있었다. 둘 다 참조를 grep으로 추적했을 때 import 경로가 아무데도 없었다.

# SCSS 참조 여부 확인
grep -rn "@import.*aaa" src/
grep -rn "@use.*aaa" src/
grep -rn "@import.*kingdriver" src/
grep -rn "@use.*kingdriver" src/

# partial 파일(_로 시작)이면 파일명으로도 확인
grep -rn "_aaa" src/ --include="*.scss"
grep -rn "_kingdriver" src/ --include="*.scss"

전부 결과 없음이면 제거해도 안전하다. 동적으로 경로를 조합해서 import하는 패턴이 있으면 이것만으론 부족하지만, 이 프로젝트 구조에서는 grep으로 충분히 커버됐다.

빌드 파이프라인 관점에서 본 dead SCSS

파일 몇 개 남아있는 게 뭐 대수냐 싶을 수 있는데, 빌드 파이프라인 관점에서 보면 이야기가 달라진다.

항목	영향
번들 포함 여부	entry point에서 직·간접 import되면 dead code도 번들에 그대로 들어감
tree-shaking	SCSS는 JS와 달리 tree-shaking이 제한적, 명시적 삭제가 더 확실
빌드 시간	컴파일 대상 파일 수 증가로 전체 빌드에 미세하게 영향
lint 노이즈	stylelint 등이 dead 파일까지 검사해서 불필요한 경고 발생
온보딩 비용	실제 사용 파일과 dead 파일이 섞이면 코드 파악 시간 증가

특히 PurgeCSS나 UnCSS 같은 도구를 별도로 붙이지 않는 전통적인 Sass → PostCSS → bundle 체인에서는 entry에 물려있는 파일은 사용하지 않는 selector도 그냥 번들에 포함된다. "어차피 purge 단계에서 걸러지겠지"라고 생각하기 쉬운데, purge 설정이 완벽하지 않은 경우 그냥 나가버린다. 도구 의존보다 소스 정리가 더 근본적인 해결이다.

이런 cleanup을 반복하지 않으려면

지금처럼 나중에 별도 cleanup PR을 올리는 건 결국 context를 두 번 쓰는 일이다. 기능 삭제할 때 "관련 스타일 파일도 같이 정리"가 done criteria에 포함돼 있어야 이런 잔여물이 안 쌓인다.

팀 컨벤션으로 남기면 좋을 것들:

기능/서비스 삭제 PR에 관련 SCSS 파일 제거가 포함돼야 완료로 인정
제거 전 참조 확인 grep 명령어를 PR description 템플릿에 체크항목으로 추가
주기적으로 orphan 파일을 탐지하는 lint rule이나 CI 스크립트 도입 고려

커밋 메시지에도 이유를 남겨두는 게 중요하다. "aaa 기능 deprecated 후 참조 없는 SCSS 파일 제거" 이 한 줄이 6개월 뒤 히스토리 볼 때 "이거 왜 없지?" 하는 혼란을 막는다. 파일 삭제 커밋은 특히 배경 설명이 없으면 나중에 되돌려야 하나 말아야 하나 판단이 어렵다.

코드베이스를 깨끗하게 유지하는 건 결국 팀의 시간을 아끼는 일이다. 당장 눈에 보이는 기능 추가가 아니라서 티가 안 날 뿐이지, 쌓이면 분명히 속도 차이가 난다. 이번 작업이 작았던 만큼, 이런 cleanup을 한 번에 끝내는 습관을 팀 단위로 만드는 계기로 삼으려고 한다.