모노레포 빌드 도구 선택과 운영 플레이북
좋은 도구는 체크리스트가 긴 도구가 아니라, 저장소 규모가 커져도 팀이 여전히 구조를 이해할 수 있게 해주는 도구입니다.
저장소가 커지면 무엇이 바뀌는가
초기에는 단순 workspace만으로 충분해 보일 수 있습니다. 하지만 규모가 커지면 압박 지점이 달라집니다.
- 영향 없는 프로젝트까지 함께 다시 빌드됨
- 태스크 순서가 사람 머릿속 지식이 됨
- 의존성 경계가 약해짐
- CI 비용이 변경량보다 더 빠르게 상승함
- 로컬 피드백이 느려져 저장소 구조 자체를 신뢰하지 않게 됨
이 시점부터 모노레포 도구는 편의 기능이 아니라 구조 비용을 다루는 수단이 됩니다.
기본 workspace는 시작점이지 항상 종착점은 아니다
pnpm workspace나 npm workspaces는 충분히 좋은 출발점이 될 수 있습니다. 특히 아래 조건에서는 그렇습니다.
- 앱과 패키지 수가 아직 많지 않을 때
- 의존성 경계를 사회적 규칙으로 관리할 수 있을 때
- CI 비용이 아직 크지 않을 때
- 팀이 도구 복잡도를 낮게 유지하고 싶을 때
하지만 설치 묶음 이상이 필요해지는 순간 한계가 보입니다. 그래프 인식, 영향 기반 실행, 원격 캐시, 경계 강제가 중요해지면 기본 workspace만으로는 부족해지는 경우가 많습니다.
실전에서는 무엇을 봐야 하나
Nx, Turborepo, workspace-only 구성을 비교할 때는 다음 질문이 더 중요합니다.
- 현재 프로젝트 수와 증가 속도는 어떤가
- 앱, 서비스, 공용 패키지가 얼마나 혼합되어 있는가
- CI 대기 시간과 비용에 얼마나 민감한가
- 코드 생성기나 경계 강제가 필요한가
- 팀이 감당할 수 있는 도구 복잡도는 어느 정도인가
Nx는 그래프 정책, 코드 생성, 규칙 강제가 중요한 팀에 더 잘 맞는 편이고, Turborepo는 상대적으로 가벼운 실행 모델과 캐시 체감이 장점이 될 수 있습니다. workspace-only는 단순하지만 그만큼 운영 규율을 사람이 더 많이 떠안아야 합니다.
캐시는 규모가 커지면 필수에 가깝다
캐시가 약한 모노레포는 감정적으로도 비싸집니다. 개발자는 작은 수정 하나에도 긴 대기를 겪고, 결국 저장소 구조 자체를 불신하게 됩니다.
좋은 캐시는 다음을 만족해야 합니다.
- 입력이 같으면 이전 결과를 재사용할 수 있다
- 로컬과 CI에서 일관되게 동작한다
- 왜 hit/miss가 났는지 설명 가능하다
- 팀 전체가 원격 캐시를 함께 쓸 수 있다
캐시는 단순 성능 기능이 아니라 개발 리듬을 지키는 장치입니다.
의존성 경계는 의도가 아니라 강제가 필요하다
모노레포의 대표적인 실패는 모든 것이 천천히 서로를 import하기 시작하는 것입니다. 그렇게 되면 물리적으로는 하나의 저장소지만, 개념적으로는 엉킨 거대 프로젝트가 됩니다.
보통 필요한 장치는 이런 것들입니다.
- 앱이 어떤 패키지까지 참조할 수 있는지에 대한 규칙
- lint나 graph policy로 강제되는 layer 경계
- shared 패키지에 대한 owner 지정
- 왜 어떤 태스크가 affected 되었는지 보이는 가시성
문서만으로는 오래 버티기 어렵고, 결국 도구가 경계를 지지해 줘야 합니다.
CI는 변경 영향 범위를 따라가야 한다
모든 PR에서 전체 저장소를 다시 빌드하고 테스트하면, 규모가 커질수록 팀이 지불하는 대기 비용이 급격히 커집니다. 더 건강한 흐름은 보통 이렇습니다.
changed files -> affected packages -> affected apps -> targeted build/test/deploy모노레포 도구의 진짜 가치는 여기서 가장 크게 드러납니다. 비용을 줄이면서도 피드백을 더 자주 받게 해주기 때문입니다.
도구가 팀 합의를 대신해 주지는 않는다
좋은 도구가 있어도 아래 합의는 여전히 필요합니다.
- 스크립트와 패키지 이름 규칙
- 소유권과 리뷰 책임
- 언제 새 패키지를 만들지에 대한 기준
- 버전/릴리스 정책
- shared 라이브러리와 앱 전용 코드의 경계
도구는 규율을 증폭할 수는 있어도, 없는 규율을 대신 만들어 주지는 않습니다.
자주 보이는 실패 패턴
- 아직 필요하지 않은데 무거운 도구부터 들여오는 경우
- 저장소 규모가 커졌는데도 최소 도구에만 머무는 경우
- shared 패키지가 dump 폴더가 되는 경우
- 왜 어떤 태스크가 돌았는지 아무도 설명하지 못하는 경우
- 그래프는 복잡해졌는데 ownership은 여전히 흐린 경우
건강한 모노레포는 가장 정교한 모노레포가 아니라, 규모가 커져도 여전히 읽히는 모노레포입니다.
체크리스트
- 현재 저장소 규모가 더 강한 그래프/캐시 도구를 정당화하는가
- affected build가 CI 비용을 실제로 줄이고 있는가
- 패키지 경계가 사회적 규칙이 아니라 자동으로 강제되는가
- 개발자가 왜 어떤 태스크가 실행되는지 이해할 수 있는가
- 도구가 새 의식 절차를 늘리는 대신 운영 모호성을 줄이는가
마무리
모노레포 빌드 도구는 유행이 아니라 운영 판단으로 골라야 합니다. 좋은 선택은 저장소가 커져도 빌드 비용, 의존성 경계, 개발자 피드백이 계속 이해 가능한 상태를 유지하게 해주는 선택입니다. 문제는 규모 그 자체가 아니라, 설명할 수 없게 된 규모입니다.
Continue Reading
다음으로 읽기 좋은 글
AI 코딩 워크스페이스 가드레일 운영법
AI 코딩 도구를 쓰는 팀은 생산성만이 아니라 안전한 작업 경계도 함께 설계해야 합니다. 워크스페이스 가드레일 기준을 정리합니다.
🔧 ToolsDev Container 기반 재현 가능한 워크스페이스 가이드
개발 환경, 온보딩, 도구 버전, CI 정합성을 dev container로 표준화하는 실무 가이드입니다.
📚 IT 이야기개발자들은 왜 CLI를 사랑하게 되었을까
화려한 GUI가 많은 시대에도 개발자들은 여전히 터미널로 돌아갑니다. CLI가 기술 문화의 중심이 된 이유를 이야기처럼 풀어봅니다.
🚀 DevOpsKubernetes 심화 — HPA, Resource 관리, Pod Scheduling
Kubernetes 운영을 설정 모음이 아니라 자원 배치와 장애 복원력의 관점에서 정리합니다. requests/limits, HPA, affinity, taint, PDB, probe를 언제 어떻게 써야 하는지 실무적으로 설명합니다.
다음 탐색