모노레포 절망편 – 14개의 레포로 부활하기까지 걸린 1년

flex 웹 제품은 모노레포(monorepo) 위에서 성장해왔습니다. 초기에는 단일 코드베이스 덕분에 협업이 단순했고, 빠른 제품 개발이 가능했습니다. 그러나 제품과 팀이 커질수록 상황은 달라졌습니다. 공용 코드가 잦은 충돌을 일으키고, 매주 거대한 변경 PR이 쌓였으며, 정기배포일마다 모두가 긴장 속에서 배포를 지켜보는 일이 반복되었습니다. 모노레포는 절망이 되었습니다.

정기배포 그만두기

2024년 2월, 플렉스팀은 “정기배포를 멈추자”는 목표를 세우고 새로운 여정을 시작했습니다. 모노레포를 해체하고 패키지와 애플리케이션을 개별 레포지토리로 분리하는 방법을 선택했습니다. 단순히 레포를 쪼개는 작업에 그치지 않았습니다. 빌드, 버저닝, 변경 통제 체계를 새롭게 설계해야 했고, 공용 패키지와 애플리케이션 간 의존성을 어떻게 관리할지도 고민해야 했습니다.

이 과정은 쉽지 않았습니다. 1년 5개월 동안 9개의 마일스톤을 거치며 팀은 점진적으로 모노레포에서 벗어났습니다. 그 결과 flex 웹 제품의 코드베이스는 14개의 개별 레포지토리로 재탄생할 수 있었고, 2025년 7월 드디어 3년간 이어온 정기배포를 공식적으로 종료하게 되었습니다.

1년의 여정이 남긴 교훈들

사실 모노레포냐 폴리레포가 중요하진 않습니다. 피상적인 기술적 고민에 그칠 것이 아닙니다. 제품과 팀이 커지면서도 명확한 경계가 존재하며, 복잡도를 통제하고, 가치가 있는 모듈들이 공유되는 코드베이스를 만드는 것이 더 중요합니다. 정기배포 그만두기 프로젝트를 진행하며, 다음 3가지 교훈들을 얻었습니다.

첫째, 경계 없이 코드를 공유해서는 안 됩니다. 모노레포를 처음 도입할 때는 공용 코드의 장점이 커 보였습니다. 한 레포지토리에 모든 패키지가 존재하니 재사용성이 높아지고, 당장은 빠르게 개발할 수 있었습니다. 하지만 시간이 지나면서 문제는 점점 커졌습니다. 서로가 만든 공용 코드를 경계 없이 가져다 쓰게 되었고, 코드베이스의 복잡도가 걷잡을 수 없이 올라갔습니다.

“이제 이거 쓰지 마세요”라는 규칙만으로는 아무런 효과가 없었습니다. 작은 수정 하나가 다른 팀 코드에 문제를 일으키는 일이 빈번하게 일어났습니다. Nx팀이 정의했듯, 단순히 같은 레포지토리에 코드를 모아두는 것만으로는 모노레포라고 부를 수 없습니다. 레포지토리를 분리하면서 자연스러운 경계를 수립했고, 각 팀이 독립적으로 책임질 수 있는 코드베이스를 만들 수 있었습니다.

둘째, 코드베이스를 복잡한 상태로 방치하지 않아야 합니다. 시간이 지남에 따라 모노레포 안의 패키지 수는 눈덩이처럼 불어났습니다. 어디에 무슨 패키지가 있는지도 알기 어려웠고, 의존성은 개발자들의 인지 범위를 넘어섰습니다. 특정 기능을 공유하기 위해 새 패키지를 계속 만들다 보니 코드베이스는 파편화되고 복잡도가 급격히 증가했습니다.

방치된 복잡성은 결국 개발자들에게 ‘인지 부하’로 돌아왔습니다. 코드를 변경할 때마다 예상치 못한 곳에서 에러가 발생했고, 빌드와 테스트 속도는 점점 느려졌습니다. 이를 해결하기 위해 모노레포 의존성을 파악하고 정리하는 내부 도구인 ‘고구마(goguma)’를 개발하여 불필요한 패키지를 정리했습니다. 그 결과 패키지 수를 줄이는 것만으로도 전체 빌드 성능이 38% 개선되었고, CI 실행 속도 또한 유의미하게 빨라졌습니다.

셋째, 공유 모듈이 무엇인지 정의하고 알맞게 다뤄야 합니다. 그동안 공유 모듈이 어떤 최소 조건을 충족해야 하는지 정의하지 않았습니다. 그 결과 가치가 매우 떨어지는 공유 모듈들이 만들어졌습니다. 이러한 공유 모듈들은 사용 빈도가 낮고 유지보수되지 못하여 코드베이스의 취약성을 높였습니다.

공유 모듈의 기준을 명확히 세웠습니다. 제품 전체에서 반드시 하나여야만 하는 코드, 그리고 공용화가 되지 않으면 개발 생산성이 급격히 떨어지는 코드. 이 두 가지 조건을 만족하지 못하는 모듈은 과감하게 각 사용처로 내재화하고 중복을 허용했습니다. 공용 레이어에는 디자인 일관성을 보장하는 디자인 시스템, 널리 쓰이는 유틸성 함수, 일관성이 중요한 비즈니스 로직만 남겼습니다.

다음 단계

각 제품 스쿼드가 분리된 레포지토리에서 더욱 자유롭고 필요한 방식으로 개발할 수 있도록 지원할 예정입니다. 또한 공용 모듈에 대한 명세와 문서를 정리해 AI 개발 도구가 더 적극적으로 팀을 도울 수 있는 환경을 만들 것입니다.

더 많은 이야기 나누기

이번 글에서는 여정을 간략히 정리했지만, 실제 과정에는 훨씬 더 많은 디테일과 시행착오가 있었습니다. 더 깊은 내용을 원한다면 발표 자료(링크)에서 확인하실 수 있습니다. 또, 플렉스팀은 디스코드채널에서 다양한 엔지니어링 주제와 경험을 나누고 있습니다. 궁금한 점이나 비슷한 고민이 있다면 함께 이야기를 이어가 주세요.

함께 문제를 풀어갈 동료 찾습니다

플렉스팀 FE 챕터는 제품이 성장하며 직면하게 되는 모든 기술적 도전에 맞서면서, 웹 제품 개발의 새로운 기준을 만드는 여정을 이어가고 있습니다. 적정한 기술적 선택과 더불어, 그 선택이 팀과 조직의 현재와 미래에 어떤 의미를 가지는지 함께 고민하는 동료를 기다립니다. 문제 의식이 공감된다면, 이러한 문제를 풀어보고 싶다면 지금 합류하세요!