1단계
모노레포 vs 멀티레포
25 분
모노레포 vs 멀티레포
프로젝트 수가 3 개를 넘으면 구조 결정이 개별 라이브러리 선택보다 더 큰 영향.
1. 모노레포 — 한 저장소 다수 프로젝트
warragon/
├── frontend/
│ ├── pryzeet/
│ ├── admin/
│ ├── codingstairs/
│ └── dmddksl/
├── backend/
│ ├── java-backend/
│ └── python-backend/
├── infra/
└── docs/
2. 장점
- atomic change — 프론트 + 백엔드 API 변경을 한 PR 로
- 코드 공유 — 유틸 · 타입 한 곳에서
- 일관된 도구 — pnpm · Docker · CI 한 세트
- 리팩터 쉬움 — 전체 검색 · 치환
- 팀 간 가시성 — "저쪽 팀이 어떻게 짰지?"
3. 단점
- 저장소 커짐 — git clone 1GB+
- CI 복잡 — "어떤 프로젝트 바뀐 건지 감지"
- 권한 분리 어려움 — 외주 · 보안 영역 접근 제어
- 도구 선택 제약 — 하나의 패키지 매니저 · Node 버전
4. 멀티레포 (polyrepo) — 프로젝트마다 저장소
github.com/me/pryzeet-web
github.com/me/pryzeet-api
github.com/me/codingstairs-web
github.com/me/admin-web
5. 장점
- 작은 저장소 — clone · push 빠름
- 권한 분리 — 프로젝트별 access control
- 독립 릴리스 — 영향 범위 명확
- 다양한 도구 — 프로젝트마다 다른 스택
6. 단점
- cross-repo 변경 — 여러 PR 동시 · 의존성 관리
- 코드 중복 — "util 3 번 작성"
- 버전 drift — TypeScript · Node 버전 불일치
- 발견성 낮음 — 다른 팀 코드 보기 어려움
7. 선택 기준
| 상황 | 추천 |
|---|---|
| 개인 · 소규모 팀 (~10명) | 모노레포 |
| 프로젝트 긴밀 연결 (프론트 + API) | 모노레포 |
| 100명+ 엔지니어 | 멀티레포 또는 Nx · Turborepo monorepo |
| 엄격한 권한 분리 필요 | 멀티레포 |
| 라이브러리 배포 | 멀티레포 (semantic versioning) |
8. 모노레포 현실 — 적절한 도구
pnpm workspaces · Nx · Turborepo · Lerna.
# pnpm-workspace.yaml
packages:
- "frontend/*"
- "backend/*"
- "packages/*"
pnpm -F pryzeet add lodash # 특정 워크스페이스에만
pnpm -F "./frontend/*" typecheck # 여러 워크스페이스 동시
9. CI 최적화
모노레포는 기본 설정이면 매 PR 에 전체 빌드 → 느림. 변경 감지 필요.
# .github/workflows/test.yml
- uses: dorny/paths-filter@v3
id: changes
with:
filters: |
frontend_pryzeet: frontend/pryzeet/**
backend_java: backend/java-backend/**
- if: steps.changes.outputs.frontend_pryzeet == 'true'
run: cd frontend/pryzeet && pnpm test
Turborepo 는 자체 cache · 의존성 그래프로 자동 처리.
10. 결합도 관리
한 저장소에 모두 있다고 서로 import 남발하면 사실상 big ball of mud.
- 프로젝트 간 명시적 경계 —
frontend/*는backend/*에서 import 금지 - 공통 코드는
packages/에만 - 린트 룰 · eslint-plugin-boundaries 로 강제
11. 우리 모노레포 (warragon) 예
- 서비스 9 개 (frontend 7 + backend 2)
- PostgreSQL 5 인스턴스
- Docker Compose 3 환경 (LOCAL · DEV · PROD)
- 문서 SSOT
docs/+ 노트notes/+ 강좌courses/
한 저장소의 장점을 atomic PR · 문서 통합 · Claude agent 설정 단일화에서 체감.
12. 자주 걸리는 자리
- 저장소 한쪽만 푸시 — CI 통과했으나 배포 후 deploy 실패
- workspaces 의존성 루프 — A → B → A
- 너무 세분화 — 100 개 패키지는 오버엔지니어링
- 보안 · 외주 영역 접근 어려움 — 별도 저장소 또는 CODEOWNERS
하고픈 말
"처음부터 멀티레포" 는 흔한 실수. 한 팀 / 한 사람은 모노레포로 시작하고 규모 · 권한 분리가 필요해지는 시점에 분리가 순서.
Next
- 02-ssot-where