분산된 MSA 저장소를 워크스페이스로 묶어 운영한 기록
들어가기
이슈 하나를 처리할 때마다 IDE, 브라우저, CI 화면을 계속 오가야 했다. 문제는 저장소 개수 자체보다 맥락이 자주 끊기는 구조에 있었다. 분산된 저장소를 완전히 합치지 않고도 이 흐름을 줄일 방법이 필요했다. 그래서 관련 저장소를 도메인 단위 워크스페이스로 묶고 Git 서브모듈로 연결하는 방식을 실험했다.
이 글에서는 문제를 어떻게 정의했는지, 왜 서브모듈을 선택했는지, 오늘 바로 시작할 최소 도입 단계를 순서대로 정리한다.
1. 한 기능을 개발할 때마다 IDE 창이 늘어났다
분산된 MSA(마이크로서비스 아키텍처) 구조에서는 한 기능을 만들 때 IDE 창이 여러 개 뜬다. 서비스별 저장소(repo)가 따로 있기 때문이다.
여기서 진짜 비용은 코드 작성 시간이 아니었다. 맥락을 파악하는 시간이 더 컸다.
- 어떤 저장소가 이 이슈에 연관되는지 다시 찾는다
- 각 저장소 브랜치 상태를 다시 확인한다
AI를 함께 쓰면 이 비용은 더 커진다. 에이전트에게도 컨텍스트를 여러 번 나눠서 전달해야 하기 때문에, 작업을 나누는 것부터 비효율적이다.
2. 문제는 저장소 개수가 아니라 맥락이 자주 끊기는 구조였다
처음에는 "저장소가 많아서 불편하다"라고만 생각했다. 그런데 실제로는 불편의 핵심이 달랐다.
아래 항목 중 2개 이상이면 같은 문제를 겪고 있을 가능성이 크다.
- 이슈 하나를 보는데 IDE, 브라우저, CI 탭을 계속 왕복한다
- AI에게 같은 배경 설명을 여러 번 전달한다
- 변경 범위를 매번 사람이 수동으로 추적한다
3. 제가 도입한 구조: 도메인 디렉토리 생성 + 서브모듈 연결
해결은 단순했다. 관련 저장소를 임의의 상위 디렉토리로 묶고, Git 서브모듈(저장소를 링크로 연결해 독립 이력을 유지하는 방식)로 연결했다.
이 글에서는 내부 식별자를 일반화해서 설명한다.
A, B, C -> XXX(레거시)D, E, F -> {DOMAIN}(담당 도메인)
도메인 워크스페이스와 서브모듈 구조도
도입 목적은 하나였다. 기존 독립성을 깨지 않고 탐색 동선을 줄이는 것.
4. 왜 서브모듈이었는가: 3가지 대안 비교
도입 전에 세 가지 대안을 비교했다.
아래 용어는 이렇게 보면 된다.
- Git Subtree: 여러 저장소 코드를 한 저장소로 합쳐 관리하는 방식
- Git Submodule: 저장소를 링크로 연결해 독립 이력을 유지하는 방식
| 대안 | 전환 비용 | 브랜치 독립성 | CI/CD 영향 | AI 컨텍스트 탐색성 | 운영 난이도 | 판단 |
|---|---|---|---|---|---|---|
| 현상유지(분산 저장소) | 낮음 | 높음 | 없음 | 낮음 | 중간 | 탐색 비용이 계속 누적 |
| Git Subtree | 중간 | 중간 | 중간 | 중간 | 높음 | 병합/동기화 운영 부담 큼 |
| Git Submodule | 중간 | 높음 | 낮음 | 높음 | 중간 | 현 시점 최적 선택 |
핵심 기준은 두 가지였다.
- 기존 git/CI/CD를 흔들지 않을 것
- 개별 브랜치 운영을 유지할 것
서브모듈은 이 두 조건을 모두 만족했다.
5. 도입 후 무엇이 달라졌나
가장 큰 변화는 이슈 추적 흐름이었다. 전에는 "위치 찾기"에 시간을 썼고, 지금은 "문제 해결"에 집중할 수 있다.
| 구간 | 도입 전 | 도입 후 |
|---|---|---|
| 연관 서비스 찾기 | 저장소별 위치를 따로 탐색 | 워크스페이스에서 동시 확인 |
| 브랜치 상태 확인 | 서비스별 개별 확인 | 연관 모듈만 빠르게 확인 |
| AI 컨텍스트 전달 | 배경 설명을 여러 번 분할 전달 | 한 번에 맥락 전달 |
| CI/CD 검증 | 파이프라인을 넓게 확인 | 영향 서비스 중심으로 검증 |
기준 시나리오는 "연관 저장소 3개가 함께 바뀌는 이슈 1건"이다. 이 시나리오에서 추적 구간 4개가 모두 짧아졌다. AI 컨텍스트 전달 횟수는 "여러 번"에서 "1번"으로 줄었다.
체감된 변화는 아래와 같았다.
- 탐색 시작까지의 준비 시간이 줄었다
- AI와의 대화에서 반복 설명이 줄었다
- 기존 저장소의 git/CI/CD 경로는 문제 없이 유지됐다
- 서비스별 브랜치 전략도 그대로 유지됐다
6. 비용과 한계도 분명했다
좋은 점만 있었던 건 아니다.
가장 먼저 체감한 비용은 초기 Gradle 로딩 시간 증가였다. 워크스페이스를 처음 여는 순간은 분명 느리다.
또 하나의 비용은 운영 규율이었다. 서브모듈은 "자동으로 잘 굴러가는 구조"가 아니다.
비용이 생기는 시점도 비교적 명확했다.
- 워크스페이스를 처음 여는 시점
- 릴리즈 직전에 서브모듈을 동기화하는 시점
추가로 아래 규칙이 없으면 금방 운영 부담으로 돌아온다.
- 포인터 업데이트 규칙이 필요하다
- 동기화 기준 브랜치를 팀이 합의해야 한다
- 온보딩 문서가 없으면 신규 인원이 쉽게 혼란을 겪는다
결국 기술 자체보다 운영 규칙이 더 중요했다.
7. 이 방식이 특히 유리한 팀
아래 조건에 가까울수록 효과가 컸다.
- 시스템이 아직 미성숙하고 구조가 자주 바뀐다
- 도메인 책임은 있는데 저장소는 흩어져 있다
- AI 보조 개발을 자주 써서 컨텍스트 전달 비용이 크다
반대로 중앙 플랫폼이 이미 강한 팀도 있다. 또 저장소 통합이 이미 끝난 팀도 있다. 이런 경우에는 다른 전략이 더 맞을 수 있다.
8. 오늘 바로 시작하는 3단계
큰 전환보다 작은 실험이 안전하다. 아래 순서(1 → 2 → 3)면 첫 도입 판단이 가능하다.
1) 도메인 경계 정의
- 레거시 그룹과 도메인 그룹을 먼저 나눈다
- 한 이슈에서 함께 바뀌는 저장소를 우선 후보로 잡는다
2) 워크스페이스 생성 + 서브모듈 연결
- 상위 디렉토리를 만들고 저장소를 서브모듈로 연결한다
- IDE는 이 상위 루트를 기준으로 열면 된다
3) 운영 룰 고정
- 언제 포인터를 올리는지 시점을 고정한다
- 코드리뷰에서 서브모듈 포인터 diff(가리키는 커밋 해시 변경)를 확인한다
- 릴리즈 전 검증 순서를 문서로 남긴다
마무리
지금 결론은 명확하다. 완전한 통합보다, 맥락 손실을 먼저 줄이는 편이 더 빠르게 효과를 냈다.
도메인 워크스페이스와 서브모듈은 정답이 아니다. 하지만 분산 저장소로 고통받는 팀에게는 현실적인 중간 해법이 될 수 있다.
이번 실험 이후 남긴 판단 기준은 세 가지다.
- 저장소 개수보다 맥락 전환 횟수를 먼저 본다.
- 기존 git/CI/CD 경로를 흔들지 않는 범위에서 먼저 실험한다.
- 서브모듈 도입보다 포인터 규칙과 온보딩 문서를 먼저 고정한다.
AI 시대에는 더 그렇다. 문제 해결 속도는 모델 성능만이 아니라, 맥락을 얼마나 끊기지 않게 유지하느냐에서 크게 갈린다.