모노레포 vs 멀티레포

프로젝트 수가 늘어나면 폴더 배치보다 경계와 검증 책임을 먼저 정해야 합니다. 저장소 방식은 팀 규모, 배포 독립성, 권한 경계에 맞춰 선택합니다.

1. 모노레포 — 한 저장소의 여러 앱과 서비스

workspace/
├── apps/
│   ├── web/
│   └── console/
├── services/
│   ├── api/
│   └── worker/
├── packages/
│   ├── contracts/
│   └── ui/
├── infra/
└── docs/

2. 장점

atomic change — 화면과 API 계약을 한 변경으로 검증
코드 공유 — 타입·계약·접근성 유틸을 한 곳에서 관리
일관된 도구 — 패키지 매니저·컨테이너·검증 명령을 통일
리팩터링 가시성 — 영향 범위를 저장소 전체에서 검색
변경 추적 — 문서·스키마·배포 설정의 연결을 함께 확인

3. 단점

저장소 커짐 — clone과 인덱싱 비용 증가
CI 복잡 — 바뀐 앱과 의존 그래프를 찾아야 함
권한 분리 어려움 — 민감한 영역을 같은 저장소에서 보호해야 함
도구 제약 — 공통 런타임과 패키지 정책이 필요

4. 멀티레포 (polyrepo) — 배포 단위마다 저장소

github.com/example/web
github.com/example/api
github.com/example/console
github.com/example/worker

5. 장점

작은 저장소 — clone과 변경이 빠름
권한 분리 — 저장소별 access control
독립 릴리스 — 배포 영향 범위가 명확
도구 자율성 — 팀별 런타임과 릴리스 주기 선택

6. 단점

cross-repo 변경 — 여러 PR과 버전 조율 필요
코드 중복 — 같은 유틸을 반복 구현하기 쉬움
버전 drift — TypeScript·Node·계약 버전이 달라짐
발견성 낮음 — 다른 팀의 구현을 찾기 어려움

7. 선택 기준

상황	추천
개인·소규모 팀	모노레포
화면과 API가 긴밀히 함께 바뀜	모노레포
독립 릴리스와 강한 권한 분리	멀티레포
여러 언어·도구를 완전히 분리	멀티레포
공유 라이브러리를 안정적으로 배포	멀티레포 또는 명확한 packages 경계

8. 모노레포의 현실적인 도구

pnpm workspaces·Nx·Turborepo·Lerna 중 팀의 캐시·그래프 요구에 맞는 하나를 고릅니다.

# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "services/*"
  - "packages/*"

pnpm --filter web add lodash
pnpm --filter web test
pnpm --filter "./services/*" typecheck

9. 변경 감지와 CI

모노레포에서 매번 전체 빌드를 실행하면 피드백이 늦어집니다. 변경된 경로와 그 의존성을 계산하되, 공통 계약이 바뀌면 소비자 검증을 넓혀야 합니다.

# ci.yml
filters:
  web: apps/web/**
  api: services/api/**
  contracts: packages/contracts/**

steps:
  - if: web or contracts
    run: pnpm --filter web test
  - if: api or contracts
    run: pnpm --filter api test

10. 결합도 관리

한 저장소에 함께 있다고 서로의 내부 파일을 import하면 사실상 big ball of mud가 됩니다.

앱은 서비스의 공개 API와 계약 패키지만 사용
공통 코드는 packages/에 두고 소유자를 명시
DB 모델·마이그레이션은 해당 서비스 경계 안에 둠
경계 위반을 lint rule과 CI로 실패시킴

11. 실전 점검표

배포 단위를 먼저 나누고 폴더 이름은 역할을 표현합니다.
API·이벤트·DB 스키마의 소비자를 문서화합니다.
공통 패키지는 독립 테스트와 버전 규칙을 가집니다.
변경 감지 결과와 실제 검증 목록을 CI 로그에 남깁니다.
저장소를 나누더라도 계약·관측·복구 기준은 동일하게 유지합니다.

자주 걸리는 자리

저장소 한쪽만 배포해 계약이 어긋남
workspaces 의존성 루프가 생김
100개 패키지로 과도하게 분리함
민감한 데이터와 공개 코드의 권한 경계를 늦게 정함

02-ssot-where