보험료 계산기 코어 아키텍처를 처음부터 설계한 날

새 서비스 도메인 기반으로 보험료 계산기 코어를 처음부터 스캐폴딩한 날.

왜 이걸 지금 만들었나

사내 서비스 중에 보험료 계산이 필요한 흐름이 있었는데, 매번 담당자가 수동으로 수치를 뽑거나 외부 도구를 쓰고 있었다. 2026년 요율(rates)이 바뀌는 시점이 맞물리면서 "이 참에 제대로 만들자"는 흐름이 생겼고, 내가 직접 초기 아키텍처를 잡기로 했다.

스캐폴딩 커밋은 보통 사람들이 가볍게 보는 편인데, 나는 오히려 이 단계가 제일 중요하다고 생각한다. 초기 구조가 이후 팀 전체의 작업 방식을 결정짓기 때문이다. 잘못 잡힌 폴더 구조나 설정 파일 하나가 나중에 "이게 왜 여기 있어요?"로 돌아온다.

스캐폴딩에서 실제로 결정한 것들

변경된 파일 목록을 보면 이 커밋이 단순한 "폴더 만들기"가 아님을 알 수 있다.

Astro를 선택한 건 계산기라는 특성상 인터랙티브한 부분은 제한적이고, 콘텐츠와 계산 결과 표시가 주가 되기 때문이다. 무거운 SPA 프레임워크를 가져올 필요가 없었고, 필요한 곳에만 JS를 얹는 island 아키텍처가 딱 맞는 상황이었다.

코어 로직: insurance.ts 에 뭘 담았나

src/lib/insurance.ts 가 이 커밋의 실질적인 무게중심이다. 2026년 요율을 하드코딩이 아니라 구조화된 형태로 관리하는 게 첫 번째 목표였다.

// 요율 테이블을 상수로 분리 — 매년 업데이트 포인트가 명확해야 함
export const RATES_2026 = {
  base: 0.0xx,
  // 구간별 요율, 조건별 계수 등
} as const;

// 계산 함수는 요율 테이블을 인자로 받도록 설계
// → 연도별 요율 교체가 함수 시그니처 변경 없이 가능
export function calculatePremium(
  input: InsuranceInput,
  rates: typeof RATES_2026
): PremiumResult {
  // ...
}

핵심은 요율 테이블과 계산 로직을 분리하는 것이다. 매년 요율이 바뀔 때 계산 함수를 건드리지 않고 테이블만 교체할 수 있어야 한다. 이걸 처음부터 안 잡으면 내년에 "2027 요율 반영"이라는 커밋이 함수 내부 하드코딩을 수정하는 형태로 들어온다. 리뷰할 때 가장 싫어하는 패턴 중 하나.

타입도 초기에 엄격하게 잡았다. InsuranceInput과 PremiumResult를 interface로 명시해두면, 나중에 UI 레이어에서 연결할 때 컴파일 타임에 오류가 잡힌다. 팀원이 처음 이 파일을 열었을 때 "이 함수에 뭘 넣어야 하지?"를 타입에서 바로 읽을 수 있게.

스캐폴딩 커밋에서 팀장으로서 챙기는 것

이런 초기 셋업 커밋은 내가 직접 하거나, 내가 리뷰하면서 아주 꼼꼼하게 본다. 이유가 있다.

• .gitignore 누락: 초반에 node_modules나 .env 가 한 번이라도 커밋되면 히스토리 정리가 귀찮아진다. 이건 첫 커밋 전에 무조건 확인.
• README.md 초안: 아무것도 없는 것보다 "이 프로젝트가 무엇인지 한 줄"만 있어도 나중에 온보딩이 달라진다. 완성형이 아니어도 된다. 기준점이 있어야 팀원이 업데이트할 수 있다.
• package-lock.json 포함 여부: 라이브러리 프로젝트라면 제외, 애플리케이션이라면 포함. 이 서비스는 배포되는 앱이니 lock 파일을 커밋에 포함시켰다. CI에서 npm ci로 재현 가능한 빌드를 보장하기 위해서.
• 초기 의존성 미니멀하게: 스캐폴딩 시점에 "나중에 필요할 것 같아서" 라이브러리를 잔뜩 추가하는 경우가 있는데, 이건 나중에 쓰지도 않는 패키지가 남는 원인이 된다. 실제로 쓰는 것만.

돌아보면

2026 요율 적용이라는 데드라인이 있는 작업이라 초기 구조를 잡는 데 들이는 시간이 아깝게 느껴질 수도 있었다. 근데 계산기 도메인은 특성상 요율 변경, 예외 케이스 추가, UI 연결이 계속 반복된다. 첫날 구조를 제대로 잡지 않으면 세 번째 요율 업데이트쯤에 "이거 어떻게 고쳐요?"가 나온다. 그 질문을 받지 않으려고 첫 커밋에 시간을 더 쓰는 게 맞다고 생각했다.

다음은 UI 레이어에서 이 코어를 연결하는 작업.

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

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

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