1편: 사주를 코드로 만들 수 있을까 — 도메인 탐색과 아키텍처 결정

 

시리즈: AI 협업 개발기: 사주명리 프로젝트
키워드: AI 협업, 도메인 탐색, 아키텍처, 사이드 프로젝트, Claude

---

타로 다음으로 떠오른 아이디어

"혹시 사주에 필요한 데이터를 가지고 있어? 사주 프로그램을 만들고 싶어."

타로 마스터 프로젝트를 끝낸 직후였다. 타로를 만들면서 AI와의 협업 프로세스가 손에 익었고, 한국 문화와 더 깊이 연결된 무언가를 만들고 싶었다. 사주명리(四柱命理)는 자연스러운 다음 주제였다.

그런데 프로젝트를 시작하자마자 한 가지 사실이 분명해졌다. 이건 타로와는 차원이 다른 복잡도라는 것이다.

타로와 사주, 같은 듯 전혀 다른 세계

타로 마스터는 비교적 단순한 구조였다. 78장의 카드 데이터, 정방향/역방향 해석 텍스트, 세 가지 리딩 모드. 도메인 자체가 잘 정리되어 있고, 카드를 섞어서 뽑으면 되는 직관적인 흐름이었다.

사주는 완전히 다르다. 천간(天干) 10개, 지지(地支) 12개, 60갑자 순환, 오행(五行) 상생상극, 십신(十神) 관계, 지장간(地藏干), 12운성, 합충형파해(合沖刑破害)... 기초 데이터만 나열해도 머리가 어지럽다. 거기에 만세력(萬歲曆)이라는, 양력을 음력으로 변환하고 절기(節氣) 기준으로 월을 구분하는 천문학적 계산이 필요하다.

그리고 결정적으로, 사주의 "풀이"는 타로의 카드별 고정 텍스트와는 비교할 수 없을 만큼 복잡하다. 네 개의 기둥에 배치된 여덟 글자의 관계를 종합적으로 읽어야 한다. 이걸 어떻게 구현할 것인가?

Claude에게 사주 프로그램을 만들겠다고 말하자, AI는 먼저 사주의 핵심 구성요소를 정리해줬다. 필수 데이터(천간, 지지, 60갑자, 오행, 십신, 지장간, 12운성), 가장 어려운 부분(만세력 데이터와 절기 기반 월 구분), 그리고 풀이 엔진의 구현 방식. 혼자서 이 전체 그림을 파악하려면 명리학 입문서를 한 권 훑어봐야 했을 것이다. AI와의 대화로 10분 만에 프로젝트의 지형도가 그려졌다.

AI가 던진 세 가지 질문

도메인의 윤곽이 잡히자, Claude가 구현 방향을 결정짓는 핵심 질문 세 가지를 던져왔다.

첫째, 사주 풀이 엔진을 어떤 방식으로 구현할 것인가. 선택지는 세 가지였다. 전통 이론을 코드로 직접 구현하는 룰 기반, 사주 데이터를 AI에 넘겨서 해석하는 AI API 활용, 그리고 기본 분석은 룰 기반으로 하되 종합 해석은 AI에 맡기는 하이브리드 방식.

둘째, 프로젝트 목표 수준. 학습용 토이 프로젝트, 실서비스 수준, MVP 후 점진적 고도화 중 어디를 겨냥할 것인가.

셋째, 만세력 데이터 처리 방식. 오픈소스 라이브러리 활용, 직접 구현, 외부 API 활용 중 선택.

이 세 질문이 프로젝트의 전체 골격을 결정짓는 질문이었다. 타로 프로젝트에서도 느꼈지만, AI가 명시적으로 선택지를 제시하면 개발자 자신이 원하는 것을 명확히 인식하게 된다. "뭘 만들어야 하지"라는 막연한 생각이 "이 세 가지 축에서 각각 어디에 서겠는가"라는 구체적 판단으로 바뀐다.

세 가지 선택, 그리고 그 이유

하이브리드, 실서비스 수준, 오픈소스 라이브러리 활용을 골랐다.

하이브리드를 선택한 이유는 현실적인 판단 때문이었다. 사주학의 모든 해석 규칙을 코드로 직접 구현하려면, 말 그대로 명리학 박사 과정을 밟는 셈이다. 학파마다 해석이 다르고, 예외 규칙이 산더미다. 반면 AI에만 의존하면 정확도를 검증할 방법이 없다. 기본적인 분석(오행 비율, 십신 관계, 용신 판단)은 명확한 규칙이 있으니 코드로 구현하고, 이 구조화된 데이터를 AI에 넘겨서 자연어로 종합 해석하게 만드는 것이 최선이었다.

실서비스 수준을 목표로 잡은 건, 타로 프로젝트에서 "제대로 만들면 실제로 쓸 수 있다"는 확신을 얻었기 때문이다. 만세력 정확도가 떨어지면 사주 자체가 틀리고, 사주가 틀리면 이후의 모든 해석이 무의미하다. 여기서 타협하면 안 된다.

오픈소스 라이브러리는 시간 대비 효율의 문제였다. 양력-음력 변환 알고리즘을 직접 구현하는 것은 사이드 프로젝트의 범위를 넘어선다.

아키텍처의 뼈대가 그려지다

세 가지 선택이 끝나자 Claude가 곧바로 전체 아키텍처를 제안했다.

기술 스택은 React 18 + TypeScript + Vite + Mantine UI를 프론트엔드로, korean-lunar-calendar로 만세력을 처리하고, Zustand으로 상태를 관리하며, Claude API로 AI 해석을 연동하는 구조였다. 타로 프로젝트와 비슷한 스택이지만, 사주의 복잡도를 반영하여 모듈 분리가 훨씬 정교했다.

핵심은 디렉토리 구조였다. src/ 아래에 core/ 폴더를 두고, 그 안에 data(기초 데이터), calendar(만세력/절기), pillar(사주 기둥 계산), analysis(분석 엔진)를 분리했다. ai/ 폴더는 core/와 완전히 독립시켰다. 이 관심사 분리가 중요한 이유가 있다. core/ 폴더는 순수 로직이므로 React나 DOM과 무관하게 독립 테스트가 가능하고, AI 해석은 core/의 분석 결과를 입력으로 받기만 한다.

데이터 흐름도 명확했다. 사용자 입력(생년월일시, 성별) → 만세력 모듈(양력-음력 변환, 절기 판정) → 사주 기둥 계산(연주/월주/일주/시주) → 룰 기반 분석(오행/십신/용신/합충형파해) → 구조화된 JSON → UI 시각화 + AI 해석. 파이프라인의 각 단계가 이전 단계에 의존하는 구조다.

7단계의 개발 체크리스트도 나왔다. 기초 데이터 모듈, 만세력 모듈, 사주 기둥 계산, 룰 기반 분석 엔진, AI 해석 연동, UI 구현, 검증 및 고도화. 각 단계가 다음 단계의 기반이 되므로, 순서를 건너뛸 수 없는 파이프라인이었다.

이번에는 코드부터 치지 않기로 했다

아키텍처 논의가 끝나자, 자연스러운 다음 단계가 뭐냐는 질문이 나왔다. 세 가지 선택지가 있었다. 프로젝트 셋업부터 3단계까지 한번에 가는 방법, 한 단계씩 차근차근 검증하며 진행하는 방법, 그리고 전체 설계 문서를 먼저 만들고 시작하는 방법.

타로 프로젝트에서는 기획이 끝나자마자 코드를 작성하기 시작했다. 그것도 나쁘지 않았다. 하지만 사주의 복잡도를 보는 순간 같은 방식으로는 안 되겠다는 직감이 왔다.

세 번째, 설계 문서 우선을 골랐다.

이 결정이 프로젝트의 성격 자체를 바꿔놓았다. "코드를 작성하는 프로젝트"에서 "설계를 정리하고, 그 설계를 코드로 옮기는 프로젝트"로 전환된 것이다. 2편에서 이 결정이 어떤 결과를 만들었는지 이야기한다.

전문 앱을 열어본 순간

아키텍처를 잡는 과정에서 한 가지 더 한 일이 있다. 기존 사주 앱들을 벤치마킹한 것이다.

"만세력 천을귀인"(iOS 인기 1위급), "고전 사주", 네이버 만세력 등을 설치하고 같은 생년월일시를 입력해봤다. 발견한 것은 충격적이었다. 앱마다 결과가 다르게 나오는 경우가 있었다. 같은 사람의 사주인데 시주가 다르거나, 용신 판단이 다르거나.

AI와 함께 원인을 분석했다. 대부분 진태양시(True Solar Time) 보정 여부, 야자시(23:00~00:00) 처리 방식, 서머타임 적용 여부가 원인이었다. "정답이 여러 개인 도메인"이라는 것을 이 시점에서 처음 실감했다.

더 흥미로운 발견도 있었다. 원광디지털대학교 동양학과에서 의뢰하여 개발된 앱이 있었다. 대학 학과 수준의 학술 검증을 거친 데이터를 사용한다는 것이다. 그리고 정확도에서 차별화되는 앱들은 예외 없이 한국천문연구원(KASI) 데이터를 사용하고 있었다.

이 벤치마킹이 이후의 설계 문서에 직접적인 영향을 미쳤다. "우리도 KASI 데이터를 쓰자", "진태양시 보정은 필수다", "학파별 차이는 설정으로 제공하자"라는 결정이 여기서 나왔다.

이 과정에서 배운 것

첫째, AI에게 열린 질문을 던지면 도메인의 전체 지형도가 빠르게 그려진다. "사주 프로그램을 만들고 싶어"라는 한 문장에서 기초 데이터 구조, 만세력 문제, 풀이 엔진 선택이라는 세 축의 의사결정으로 분해되기까지 10분이 안 걸렸다.

둘째, 프로젝트의 복잡도를 인지하는 것 자체가 첫 번째 설계 결정이다. 사주가 타로보다 복잡하다는 것을 파악하고, 그래서 "코드부터 치지 않겠다"고 결정한 것이 이후 프로젝트의 품질을 결정지었다.

셋째, 기존 서비스 벤치마킹은 "무엇을 만들 것인가"뿐 아니라 "어떤 정밀도를 목표로 할 것인가"를 결정하는 데 핵심적이다. 전문 앱들의 결과 차이를 분석하는 것이 데이터 소스 선택과 보정 로직 설계에 직접 반영됐다.

다음 편 예고

아키텍처와 기술 스택이 결정되고, 개발 체크리스트가 나왔다. 보통이라면 여기서 터미널을 열고 npm create vite@latest를 칠 차례다. 하지만 이번에는 다르게 했다. 코드 한 줄 쓰기 전에, docs/ 폴더에 네 개의 설계 문서를 먼저 만들었다. 2편에서 왜 이 접근이 AI 시대의 개발에서 게임 체인저가 되는지 이야기한다.

---

이 글은 "AI 협업 개발기: 사주명리 프로젝트" 시리즈의 1편입니다.