장례 서비스 신규 프로젝트 초기 구조 셋업 완료

새 서비스 하나의 뼈대를 처음 잡은 날이었다.

funeral.hedvion.com — 도메인 이름만 봐도 어떤 성격의 서비스인지 대략 그림이 그려진다. Astro 기반의 프론트엔드 + 별도 봇 레이어가 함께 올라가는 구조로, 초기 scaffold 커밋 하나에 꽤 다양한 레이어가 동시에 잡혔다.

이번 scaffold에 들어간 파일들

파일 목록을 보면 구조가 꽤 명확하다. Astro가 정적/하이브리드 렌더링을 담당하는 프론트, Python 봇이 데이터를 끌어오는 백엔드 레이어, 그리고 둘 다 각자의 .env.example을 갖고 있다. 모노레포 성격은 아니지만 단일 레포 안에 두 레이어가 공존하는 구조다.

scaffold 커밋에서 제일 신경 쓰는 것들

초기 scaffold는 사실 코드보다 컨벤션과 경계선을 잡는 작업에 가깝다. 나중에 팀원이 붙었을 때 "이게 어떤 프로젝트야?", "어떻게 로컬 띄워?" 라는 질문이 나오지 않게 하려면 첫 커밋부터 아래 세 가지가 반드시 들어가야 한다고 생각한다.

• .env.example 완비: 실제 .env는 절대 커밋되면 안 되고, example은 반드시 커밋되어야 한다. 이게 없으면 새로 합류한 사람이 어떤 환경변수가 필요한지 리버스 엔지니어링해야 하는 상황이 생긴다. 이번엔 프론트와 봇 레이어 양쪽에 각각 example을 뒀다.
• .gitignore 선행: scaffold 시점에 .gitignore가 없으면 IDE 설정, __pycache__, .env 같은 것들이 다음 커밋에 슬그머니 딸려 들어오는 사고가 발생한다. Python 봇이 있으니 __pycache__, .pyc, venv/ 등도 빠짐없이 잡아야 한다.
• README.md 최소 뼈대: "나중에 쓰지 뭐" 하고 미루면 영원히 안 쓴다. 처음엔 프로젝트 설명 두 줄, 로컬 셋업 방법 정도면 충분하다. 이 시점의 README는 완성도가 목적이 아니라 존재 자체가 목적이다.

Astro + Python 봇 조합에 대해

Astro를 프론트로 선택한 건 이 서비스의 성격상 정적 콘텐츠 비중이 높고, 빌드 타임에 데이터를 끌어와 렌더링하는 패턴이 잘 맞기 때문이라고 본다. bot/data_source.py가 데이터를 수집/가공하는 역할을 하고, 그 결과물을 Astro가 소비하는 구조가 될 가능성이 높다.

# bot/data_source.py 가 담당할 역할 예상 흐름
# 1. 외부 소스에서 데이터 수집
# 2. 정제/변환
# 3. Astro가 읽을 수 있는 포맷(JSON, Markdown 등)으로 저장

// astro.config.mjs 기본 scaffold 예시
import { defineConfig } from 'astro/config';

export default defineConfig({
  // 이후 integrations, output, adapter 등이 붙어나갈 자리
});

두 레이어가 같은 레포에 있으면 배포 파이프라인 설계가 나중에 약간 복잡해질 수 있다. 봇은 Python 런타임, 프론트는 Node 빌드 환경이 필요하니까. 그래도 초기엔 한 레포에서 전체를 조망할 수 있다는 게 팀 입장에서 훨씬 편하다. 나눠야 할 시점이 오면 그때 분리하면 된다.

회고

scaffold 커밋은 작업량 대비 의사결정의 밀도가 가장 높은 커밋이다. 디렉터리 구조, 레이어 분리 방식, 환경변수 관리 전략이 전부 이 한 커밋에 녹아 있고, 이걸 나중에 바꾸려면 팀 전체가 영향을 받는다. 그래서 나는 scaffold 커밋일수록 커밋 메시지와 README에 "왜 이 구조로 잡았는지" 한 줄이라도 남기려 한다. 코드는 나중에 바뀌지만 의도는 기록해두지 않으면 사라진다.

funeral.hedvion.com의 첫 줄을 그었다.

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

• 외장SSD 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →
• 노이즈캔슬링헤드폰 쿠팡에서 보기 →

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