여러 스킬을 하나로 — 모노레포 패턴

식당 하나 vs 푸드코트

여러분, 동네 맛집 하나를 상상해보세요. 김치찌개 하나만 파는 작은 식당이에요. 메뉴도 간단하고, 주방도 하나, 셰프도 한 명. 깔끔하죠?

근데 시간이 지나면서 이 셰프가 재능이 넘치는 거예요. 김치찌개만 하기엔 아까워서, 된장찌개도 만들고, 비빔밥도 만들고, 냉면도 만들어요.

처음에는 하나의 주방에서 다 해결했는데, 메뉴가 5개, 10개로 늘어나니 문제가 생겨요.

그래서 결심합니다. "차라리 푸드코트를 차리자."

같은 건물 안에 여러 개의 전문 주방을 두는 거예요. 김치찌개 전문 주방, 비빔밥 전문 주방, 냉면 전문 주방. 각 주방은 독립적으로 운영되지만, 식재료 창고는 공유하고, 같은 위생 기준을 따르고, 한 명의 매니저가 전체를 관리해요.

이게 바로 오늘 배울 모노레포(Monorepo) 패턴이에요.

스킬 하나만 만들 때는 폴더 하나면 충분했죠. 근데 관련된 스킬이 3개, 5개, 10개로 늘어나면? 각각 따로 관리하는 것보다 하나의 저장소(레포지토리)에 모아두는 게 훨씬 효율적이에요.

모노레포가 뭔데?

"모노레포"라는 단어가 어렵게 느껴질 수 있는데, 아주 간단해요.

반대 개념은 폴리레포(Polyrepo)예요. 폴리(Poly) = 여러 개. 즉, 스킬마다 각각 별도의 저장소를 만드는 거죠.

비유로 정리하면:

• 폴리레포 = 독립 식당 5개. 각각 다른 건물, 다른 주인, 다른 식재료 창고.
• 모노레포 = 푸드코트 1개. 같은 건물, 같은 매니저, 공유 식재료 창고. 주방만 각각 분리.

언제 모노레포를 써야 할까?

모든 상황에 모노레포가 좋은 건 아니에요. 이럴 때 쓰면 좋아요:

• 관련된 스킬이 3개 이상일 때 — 혼자 사는 것보다 함께 사는 게 효율적인 수준
• 스킬들이 공통 참조 파일을 공유할 때 — 같은 코딩 컨벤션, 같은 회사 규칙 등
• 스킬들이 하나의 워크플로우에 속할 때 — 리뷰 → 배포 → 모니터링처럼 연결되는 경우
• 같은 팀이 여러 스킬을 관리할 때 — 버전 관리와 업데이트를 일괄 처리하고 싶을 때

반대로, 이럴 때는 굳이 모노레포를 안 써도 돼요:

• 스킬이 1~2개뿐이고, 관련성도 없을 때
• 완전히 다른 분야의 스킬일 때 (요리 스킬 + 코드 리뷰 스킬 = 관련 없음)
• 혼자 쓰는 간단한 스킬일 때

모노레포의 구조 살펴보기

자, 실제로 어떻게 생겼는지 봅시다. 디렉토리 구조를 보면 바로 이해가 될 거예요.

my-skill-suite/
├── package.json          ← (선택) 도구 설정용
├── shared-references/    ← 공유 참조 파일들
│   ├── SHARED-PREAMBLE.md
│   ├── coding-standards.md
│   └── team-conventions.md
├── skill-review/         ← 코드 리뷰 스킬
│   ├── SKILL.md
│   └── references/
│       └── review-checklist.md
├── skill-deploy/         ← 배포 스킬
│   ├── SKILL.md
│   └── references/
│       └── deploy-process.md
└── skill-monitor/        ← 모니터링 스킬
    ├── SKILL.md
    └── references/
        └── alert-rules.md

보이시나요? 핵심 구조를 하나하나 뜯어볼게요.

1. 최상위 폴더 = 푸드코트 건물

my-skill-suite/가 전체를 감싸는 폴더예요. 이게 하나의 Git 저장소가 됩니다. GitHub에 올릴 때도 이 폴더 전체를 하나의 프로젝트로 올려요.

2. shared-references/ = 공유 식재료 창고

이게 모노레포의 가장 큰 장점이에요. 모든 스킬이 공통으로 참조하는 파일을 여기에 모아둡니다.

예를 들어:

• SHARED-PREAMBLE.md — "우리 팀은 이런 코딩 스타일을 씁니다"라는 공통 규칙
• coding-standards.md — 변수명 규칙, 들여쓰기 규칙 등
• team-conventions.md — 팀 내 약속들 (커밋 메시지 형식, 브랜치 전략 등)

이 파일들이 변경되면, 모든 스킬에 자동으로 반영돼요. 한 번 고치면, 전부 업데이트. 이걸 폴리레포로 하면? 저장소 3개에 같은 수정을 3번 해야 하죠. 끔찍해요.

3. 각 스킬 폴더 = 개별 주방

각 스킬은 자기만의 폴더 안에서 독립적으로 존재해요. SKILL.md도 각자 있고, 스킬 전용 references/도 각자 있어요.

푸드코트에서 각 주방이 자기만의 레시피와 특수 재료를 갖고 있는 것처럼요.

실제 사례: gstack 모노레포

이론만 하면 재미없으니까, 실제 사례를 볼게요.

이 책에서 여러 번 언급한 gstack 기억하시죠? gstack은 여러 스킬이 하나의 모노레포에 들어있어요.

• /browse — 웹 브라우저로 사이트를 탐색하고 테스트
• /benchmark — 성능을 측정하고 비교
• /canary — 배포 후 모니터링
• /review — 코드 리뷰
• /qa — QA 테스트
• /design-review — 디자인 검토

이 스킬들이 왜 모노레포에 있을까요?

첫째, 워크플로우가 연결돼 있어요. 코드를 짜면 → 리뷰하고 → 배포하고 → 모니터링해요. 이 과정이 자연스럽게 이어지기 때문에, 같은 저장소에 있는 게 맞아요.

둘째, 공통 인프라를 공유해요. browse 스킬이 사용하는 브라우저 도구를, benchmark나 canary도 같이 써요. 공유 자원이 있으니 모노레포가 효율적이죠.

셋째, 같은 팀이 관리해요. 업데이트할 때 한 번에 모든 스킬을 확인하고 수정할 수 있어요.

모노레포의 장점 정리

지금까지 이야기한 장점을 깔끔하게 정리해볼게요.

1. 공유 참조 파일 — "한 번 쓰고 여러 번 쓰기"

팀의 코딩 규칙이 바뀌었다고 해봐요. 모노레포라면? shared-references/coding-standards.md 하나만 수정하면 끝. 폴리레포라면? 스킬 10개의 저장소를 하나하나 열어서 똑같은 수정을 10번 해야 해요.

2. 일관된 버전 관리 — "다 같이 업데이트"

Git에서 커밋(변경 기록) 하나로 여러 스킬을 동시에 업데이트할 수 있어요. "이번 변경은 리뷰 스킬과 배포 스킬 모두에 영향을 줘" — 이런 수정을 하나의 커밋으로 깔끔하게 기록할 수 있죠.

3. 쉬운 테스트 — "한 자리에서 전부 확인"

모든 스킬이 한 곳에 있으니, 전체를 한 번에 테스트하기가 쉬워요. "리뷰 스킬 고쳤는데, 배포 스킬에 영향 없나?" 같은 걸 바로 확인할 수 있죠.

4. 발견 가능성 — "아, 이런 스킬도 있었어?"

팀원이 모노레포를 둘러보다가 "오, 모니터링 스킬도 있네? 이거 몰랐는데!" 하고 발견할 수 있어요. 각각 다른 저장소에 흩어져 있었다면, 존재 자체를 모를 수도 있었을 거예요.

직접 만들어보기: 나만의 스킬 모음

자, 이론은 충분해요. 직접 만들어봅시다!

여러분이 마케팅 팀에서 일한다고 가정하고, 마케팅 관련 스킬 3개를 모노레포로 만들어볼게요.

1단계: 최상위 폴더 만들기

mkdir marketing-skills
cd marketing-skills

2단계: 공유 참조 파일 만들기

mkdir shared-references

shared-references/SHARED-PREAMBLE.md 파일을 만들어요:

# 우리 팀 마케팅 원칙

- 타겟 오디언스: 25-35세 한국 직장인
- 톤앤매너: 친근하지만 전문적
- 브랜드 컬러: #E85D4A (코럴), #2B8C8C (틸)
- 절대 하지 않는 것: 과장 광고, 허위 할인
- 모든 콘텐츠는 모바일 퍼스트로 작성

이 파일은 마케팅 스킬 전체가 공유하는 "우리 팀의 바이블"이에요.

3단계: 개별 스킬 폴더 만들기

mkdir -p skill-copy-write/references
mkdir -p skill-social-post/references
mkdir -p skill-report/references

각 스킬의 SKILL.md를 만들면 끝이에요. 우리가 이전 챕터에서 배운 것 그대로요.

최종 구조

marketing-skills/
├── shared-references/
│   └── SHARED-PREAMBLE.md
├── skill-copy-write/        ← 광고 카피 작성
│   ├── SKILL.md
│   └── references/
│       └── brand-voice.md
├── skill-social-post/       ← SNS 포스트 생성
│   ├── SKILL.md
│   └── references/
│       └── platform-specs.md
└── skill-report/            ← 마케팅 리포트 생성
    ├── SKILL.md
    └── references/
        └── report-template.md

깔끔하죠? 세 스킬이 한 지붕 아래 정리되어 있고, 공유 참조로 연결되어 있어요.

주의할 점: 이것만은 피하세요

모노레포를 처음 쓸 때 흔히 하는 실수들이에요.

실수 1: 관련 없는 스킬 몰아넣기

"모노레포가 좋다니까, 내 모든 스킬을 다 하나에 넣자!" — 이러면 안 돼요. 요리 스킬과 코드 리뷰 스킬은 관련이 없잖아요. 관련 없는 스킬을 억지로 모으면, 오히려 복잡해져요.

실수 2: shared-references를 너무 크게 만들기

공유 파일이 너무 많고 복잡하면, 어떤 스킬이 어떤 공유 파일을 쓰는지 파악이 안 돼요. 진짜 공통으로 쓰는 것만 넣으세요.

실수 3: 한 스킬이 너무 많은 걸 하기

모노레포 안의 각 스킬은 여전히 "한 가지 일을 잘하는" 원칙을 지켜야 해요. "리뷰도 하고 배포도 하고 모니터링도 하는" 스킬 하나보다, 각각 분리된 3개의 스킬이 낫습니다.