백엔드·Flutter 모노레포 첫 커밋 구조 잡는 법

새 프로젝트 모노레포를 처음 세팅한 날의 기록이다.

왜 모노레포였나

백엔드와 Flutter 앱을 각각 별도 레포로 분리하는 선택지도 있었다. 예전에 그렇게 운영해봤는데, 결국 "앱이 쓰는 API 스펙이 바뀌었는데 백엔드 레포엔 그 맥락이 없다"는 상황이 반복됐다. PR 하나가 두 레포를 오가다가 리뷰가 끊기고, 이슈 트래킹도 분산됐다.

이번 daily-bible 프로젝트는 MVP 단계부터 백엔드와 앱이 같은 맥락 안에서 움직이는 게 낫다고 판단했다. 모노레포로 묶으면 루트 .gitignore, README.md 하나로 전체 구조를 선언하고, app/ 디렉토리 하위에서 Flutter 전용 설정(app/.gitignore, app/.metadata, app/analysis_options.yaml)을 격리할 수 있다. 크게 복잡한 툴체인(Turborepo, Nx 같은 것)은 MVP 단계에서 오버엔지니어링이라 일단 심플한 디렉토리 분리로 시작했다.

첫 커밋의 파일들이 하는 일

이번 커밋에 들어간 파일들이 소박해 보여도, 각각이 프로젝트의 "규칙"을 선언하는 역할을 한다.

특히 analysis_options.yaml은 나중에 팀원이 붙었을 때 코드 스타일 논쟁을 줄여주는 파일이다. 린트 룰을 초반에 합의 없이 넘어가면, 중반부에 PR마다 스타일 지적이 쌓이고 리뷰 집중도가 깎인다. MVP라도 이건 첫 커밋에 같이 넣는 게 맞다고 생각한다.

.metadata도 Flutter 프로젝트에서 SDK 버전 추적에 쓰이는 파일인데, 팀원 개발환경 맞출 때 "나는 되는데 너는 왜 안 돼?" 상황을 줄이는 데 실질적으로 기여한다. 사소하게 보이지만 온보딩 비용이라는 관점에서 보면 이런 파일들이 결국 시간을 아껴준다.

bootstrap 커밋에서 내가 챙기는 것들

feat: bootstrap ... 형태의 초기 커밋은 그냥 "프로젝트 껍데기 만들기"가 아니다. 이 커밋이 이후 모든 작업의 기준선이 된다. 내가 부트스트랩 커밋에서 반드시 확인하는 체크리스트를 정리하면 이렇다.

• 루트 .gitignore 완성도: 시크릿 파일, IDE 설정 파일, 빌드 산출물이 실수로 커밋되는 걸 첫 날부터 막아야 한다
• README 구조 선언: 레포 구조가 어떻게 나뉘어 있는지, 각 디렉토리가 무슨 역할인지 한눈에 보이게
• 플랫폼별 .gitignore 분리: 루트와 app/의 제외 패턴이 다르다. 섞으면 나중에 찾기 어려워진다
• 린트/분석 옵션 초기 선언: 스타일 기준을 코드보다 먼저 잡는다

모노레포 구조에서 이 선언들이 늦어지면, 나중에 "이 파일 커밋됐어야 했나?" 논쟁이 생기거나 린트 룰 소급 적용으로 diff가 지저분해진다. 팀 규모가 작을수록 초반 컨벤션 비용이 낮으니까 오히려 이 타이밍에 해두는 게 이득이다.

MVP 단계 모노레포의 시작점은 항상 이렇게 조용하다. 큰 코드 없이 .gitignore 몇 줄, README 몇 줄이지만, 이 커밋 이후로 모든 작업이 쌓인다. 첫 커밋을 나중에 되돌아보면 그때 선언한 구조가 얼마나 잘 버텼는지 보이는데, 그게 은근히 재밌다.

끝.

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

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

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