반려동물 서브도메인 프로젝트 초기 구조 설계

새 서브도메인 프로젝트 스캐폴딩을 했다. pet.hedvion.com 이라는 이름으로, 프론트 쪽 Astro 세팅과 봇 쪽 Python 레이어가 공존하는 구조로 초기 뼈대를 잡아뒀다.

왜 지금 이 프로젝트를 시작했나

팀 입장에서 신규 서브 프로젝트를 시작할 때 가장 먼저 해야 할 결정이 "초기 구조를 어떻게 잡느냐"다. 나중에 고치려면 이미 그 위에 코드가 쌓여 있고, 팀원들이 "이게 왜 이렇게 돼 있어요?"를 물어보는 타이밍은 항상 리팩터링하기 애매한 시점이다. 그래서 초기 스캐폴딩 커밋은 단순히 "빈 파일 생성"이 아니라, 이 프로젝트가 어떤 방향으로 흘러갈지 팀 전체에게 신호를 보내는 커밋이라고 생각한다.

이번 케이스에서 눈에 띄는 건 단일 레포 안에 두 개의 레이어가 같이 들어간다는 점이다.

Astro와 Python 봇이 한 레포에 공존하는 구조는 모노레포라고 부를 만큼 거창하지는 않지만, 두 레이어 간 의존 관계가 명확하지 않으면 나중에 배포 파이프라인이나 환경 변수 관리가 꼬이기 쉽다. 그래서 초기에 .env.example을 루트와 bot/ 아래 각각 분리해둔 건 꽤 의식적인 결정이었다.

스캐폴딩에서 놓치면 후회하는 것들

초기 스캐폴딩 커밋에서 항상 챙겨야 한다고 생각하는 파일들이 있다.

• .env.example: 실제 시크릿은 절대 올리지 않되, 필요한 키의 이름과 용도는 명시. 팀원이 온보딩할 때 이게 없으면 "어떤 환경 변수가 필요한지" 물어보는 사이클이 생김
• .gitignore: 언어/프레임워크별 기본 제외 목록은 기본이고, 이 프로젝트 특성에 맞는 항목을 초기부터 추가해두는 게 나중에 실수로 올라가는 사고를 막음
• README.md: 빈 파일이라도 존재하는 것 자체가 "이 레포에는 문서가 있어야 한다"는 팀 규범을 만드는 것. 나는 초기 README에 최소한 "이 프로젝트가 뭔지", "로컬 실행 방법"은 적어두는 편

이번에 bot/.env.example이 별도로 존재한다는 건, 봇 레이어가 독립적인 환경 변수 세트를 가진다는 의미다. 배포 환경에서 봇 프로세스와 프론트 빌드가 다른 컨텍스트에서 실행될 가능성이 있다는 뜻이기도 하다. 초기에 이걸 분리해두면 나중에 "왜 봇 전용 키가 프론트 .env에 섞여 있지?" 같은 상황을 방지할 수 있다.

Astro를 선택한 맥락

astro.config.mjs가 들어왔다는 건 프론트를 Astro로 간다는 선택이 이미 됐다는 거다. Astro는 콘텐츠 중심 사이트에 특히 잘 맞는 프레임워크인데, SSR 모드와 정적 빌드 모드를 프로젝트 요구사항에 따라 유연하게 전환할 수 있다는 게 장점이다. 초기 astro.config.mjs는 보통 이런 형태로 시작한다.

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  // output: 'static' | 'server' | 'hybrid'
  output: 'static',
});

이 output 설정 하나가 배포 방식을 결정하기 때문에, 초기 스캐폴딩 단계에서 팀이 어느 방향으로 갈지 합의하고 박아두는 게 나중에 인프라 작업할 때 훨씬 편하다.

회고

스캐폴딩 커밋은 "아직 아무것도 없는 커밋"처럼 보이지만, 사실 이게 제일 의사결정이 많이 담긴 커밋이다. 파일 구조, 환경 변수 분리 방식, 프레임워크 선택이 전부 이 한 커밋에 들어있다. 팀원이 이 레포를 처음 클론했을 때 무엇을 먼저 보게 되는지를 생각하면서 짜야 하는 커밋이기도 하다.

bot/data_source.py 라는 이름이 이미 이 레이어의 역할을 꽤 명확하게 드러내고 있는데, 초기 파일명부터 의도를 드러내는 네이밍을 하는 게 나중에 코드 리뷰할 때 "이게 뭐 하는 파일이에요?" 질문을 줄여준다. 작은 디테일이지만 팀 커뮤니케이션 비용에 꽤 영향을 준다.

다음 커밋부터 실제 기능이 쌓이기 시작할 텐데, 뼈대가 잘 잡혀 있으면 그다음부터는 팀원들이 "어디에 뭘 넣으면 되는지" 직관적으로 파악할 수 있다. 결국 초기 스캐폴딩에 쓰는 시간이 아깝지 않은 이유가 거기 있다.

끝

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

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

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