모노레포 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