모노레포 전환으로 팀 온보딩과 협업 구조를 개선한 첫 주

모노레포 첫 주. 아무것도 없던 자리에 뼈대를 세운 날이다.

왜 지금 모노레포인가

팀이 커지면서 앱과 패키지가 제각각 흩어져 있는 상황이 눈에 밟히기 시작했다. 공통 컴포넌트를 쓰려면 npm 패키지를 일일이 버전 맞춰서 설치해야 했고, 타입 한 줄 바꾸면 downstream 전체를 직접 쫓아다니며 확인해야 했다. 이 비용이 팀 속도를 조용히 갉아먹고 있었다.

모노레포 전환을 결정한 건 기술적 판단이기도 했지만, 절반은 팀 운영 판단이었다. 새 멤버가 합류했을 때 "이 코드는 어느 레포에 있어요?"를 없애고 싶었다. 온보딩 비용, 컨텍스트 스위칭 비용을 구조로 줄이는 것. 그게 이번 Week 1의 진짜 목표였다.

Week 1에 건드린 파일들

숫자로 보면 6개 파일이지만, 이게 "작은 작업"이라고 보면 오산이다. 이 파일들이 앞으로 팀원 전원이 매일 밟고 지나가는 땅이 된다.

CI를 첫날부터 붙인 이유

ci.yml을 Day 1에 커밋한 건 의도적이었다. 인프라 스캐폴딩 단계에서 CI를 미루는 팀을 자주 봤는데, 나중에 붙이려고 하면 그때는 이미 "동작은 하는데 CI가 깨지는" 상태가 누적되어 있다. 처음부터 그린 빌드를 유지하는 습관을 구조로 강제하는 게 낫다.

# ci.yml — 초기 파이프라인 기본 구조 예시
on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: pnpm install --frozen-lockfile
      - run: pnpm run build
      - run: pnpm run lint
      - run: pnpm run typecheck

단순해 보여도 이 구조가 의미하는 건 크다. PR 올릴 때마다 lint, typecheck, build 세 관문을 통과해야 머지할 수 있다는 팀 약속이다. 코드리뷰에서 "혹시 빌드 깨지지 않나요?" 같은 확인 코멘트가 사라진다.

스캐폴딩에서 팀장이 직접 해야 하는 것들

솔직히 말하면 이 작업, 팀원에게 넘길 수도 있었다. 하지만 초기 구조 결정은 내가 직접 짰다. 이유가 있다.

• .eslintrc.json 상속 구조: 루트에서 어디까지 공유하고 앱별로 어디서 갈라지는지를 처음부터 잘못 잡으면 나중에 "이 규칙 왜 있어요?"가 넘친다
• components.json: UI 컴포넌트 기준을 초기에 못 박지 않으면 앱마다 다른 컴포넌트 시스템이 난립하기 시작한다
• README.md: 온보딩 문서는 팀장이 직접 쓰는 게 맞다. 설치 명령어보다 "왜 이 구조인지"를 담아야 하기 때문이다

apps/
  web/          ← Next.js 앱
packages/
  ui/           ← 공유 컴포넌트
  config/       ← 공유 eslint, tsconfig

이 디렉토리 구조 자체가 팀에게 보내는 메시지다. "공통은 packages에 담고, apps에서는 조립만 해라."

Week 1 회고

기술적으로 화려한 작업은 아니다. 커밋 메시지에도 chore가 붙었다. 그런데 이 커밋이 이후 모든 커밋의 토대가 된다는 걸 팀원들이 알아줬으면 한다.

모노레포 첫 주는 항상 "아무것도 동작하지 않는 상태에서 모든 것을 동작하게 만드는" 구간이다. 이 구간을 빨리, 단단하게 통과하는 게 팀장의 역할이라고 생각한다. 다음 주부터 팀원들이 feature 브랜치를 딸 수 있게, 그 땅을 닦은 한 주였다.

끝.

🛒 이 글과 어울리는 추천 상품

• 모니터암 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.