2편: 설계 문서가 먼저다 — docs/ 폴더로 시작하는 개발

 

시리즈: AI 협업 개발기: 사주명리 프로젝트
키워드: 설계 문서, docs/ 폴더, AI 컨텍스트, 개발 프로세스, Claude Code

---

터미널을 열지 않은 이유

1편에서 아키텍처와 기술 스택이 결정됐다. React + TypeScript + Vite, 하이브리드 해석 엔진, 오픈소스 만세력 라이브러리. 개발 체크리스트 7단계도 나왔다. 보통이라면 npm create vite@latest saju-app을 칠 차례다.

그런데 사주학이라는 도메인의 복잡도를 마주한 순간, 바로 코드를 치면 안 되겠다는 직감이 왔다. 타로는 78장 카드, 정방향/역방향, 세 가지 리딩 모드. 머릿속에 전체 그림이 들어왔다. 사주는 달랐다. 천간과 지지가 만나서 60갑자가 되고, 각 기둥의 천간과 지지가 서로 합을 이루거나 충을 일으키고, 지지 안에 숨은 천간(지장간)이 또 다른 관계를 만든다. 코드부터 치면 중간에 반드시 "아, 이 구조가 아니었어"라는 순간이 온다.

"전체 설계 문서를 먼저 만들고 시작하자." 이 결정이 프로젝트의 성격을 근본적으로 바꿨다.

네 개의 문서, 프로젝트의 지도

Claude와 함께 작성한 설계 문서는 총 네 개였다. 각 문서가 프로젝트의 특정 영역을 담당한다.

01-ARCHITECTURE.md는 전체 아키텍처와 기술 스택, 디렉토리 구조, 데이터 흐름도를 담았다. 이 문서의 핵심은 데이터 흐름도였다. 사용자 입력에서 최종 해석까지의 파이프라인이 한 장의 다이어그램으로 정리되니, 프로젝트의 전체 모양이 비로소 손에 잡혔다. 가장 중요한 설계 원칙도 여기에 명시했다. core/ 폴더는 순수 로직만 담아서 React 의존성이 없게 하고, 기초 데이터는 as const로 불변성을 보장하고, 만세력 변환과 사주 계산은 반드시 단위 테스트를 거친다.

02-DOMAIN-MODEL.md는 이 프로젝트의 심장이었다. 천간 10개, 지지 12개, 60갑자 순환표, 오행 상생상극, 십신 관계표, 지장간 매핑, 12운성, 합충형파해까지 — 사주학의 기초 데이터를 전부 TypeScript 타입과 상수로 정의했다. 이 문서 하나만 35페이지가 넘었다. 하지만 이 35페이지가 있어야 이후의 구현이 "문서를 코드로 옮기는 작업"이 될 수 있다.

03-CALCULATION-ENGINE.md는 실제 계산 알고리즘을 다뤘다. 연주는 입춘 기준, 월주는 절기 기준, 일주는 60갑자 순환, 시주는 2시간 단위 시진. 각 기둥의 계산 공식과 엣지 케이스(야자시 처리, 윤달, 절기 당일 출생, 서머타임 보정, 진태양시 보정)를 정리했다. 만세력 라이브러리 비교 분석도 이 문서에 포함했다.

04-AI-INTERPRETATION.md는 AI 해석 연동 전략이었다. 시스템 프롬프트 설계, 카테고리별 해석 프롬프트 7종(성격, 직업, 재물, 건강, 대인관계, 대운, 종합), 스트리밍 API 구조, 비용 최적화 전략, 면책 조항까지 포함했다.

왜 설계 문서가 코드보다 먼저여야 했는가

가장 직접적인 이유는, 내가 사주학 전문가가 아니기 때문이다.

타로 프로젝트에서는 도메인이 단순해서 코드를 치면서 동시에 구조를 잡을 수 있었다. 사주는 그렇지 않다. 십신(十神)의 판정 규칙을 모르는 상태에서 분석 함수를 작성할 수는 없다. 지장간(地藏干)이라는 개념의 존재 자체를 모르면, 데이터 구조에 빈칸이 생긴다. 설계 문서를 쓰는 과정은 곧 "내가 무엇을 이해하고 무엇을 모르는지"를 정리하는 과정이었다.

여기서 AI의 역할이 가장 빛났다. Claude는 사주학의 도메인 지식을 TypeScript 타입 시스템의 언어로 "번역"해줬다. 지장간이라는 개념을 설명하면서 동시에 그것이 인터페이스로는 어떤 모양이 되는지를 보여주는 것이다. 12개 지지 각각의 지장간을 정확하게 나열하고, 학파별 차이가 있는 부분은 명시적으로 표시해줬다.

학파별 차이라는 벽을 처음 만난 것이 이 설계 문서 단계였다. 지장간의 구성이 문헌마다 미묘하게 다르고, 12운성에서 음간의 순행/역행은 학파마다 해석이 갈리고, 용신 판단법도 억부법, 조후법, 통변법으로 나뉜다. AI는 이런 차이를 구체적으로 설명하면서 "가장 보편적인 기준을 채택하되, 설정에서 학파 선택이 가능하도록 확장 여지를 두라"는 실용적 제안까지 해줬다.

이 제안을 설계 문서에 명시적으로 기록해둔 것이 나중에 큰 도움이 됐다. 구현 단계에서 "이 부분은 왜 이렇게 했지?"라는 의문이 생길 때, 설계 문서에 돌아가면 의사결정의 맥락이 고스란히 남아 있었다.

설계 문서는 AI를 위한 컨텍스트이기도 하다

설계 문서의 두 번째 가치는, 그것이 AI에 대한 "영구적 컨텍스트"로 기능한다는 점이다.

대화형 AI의 근본적 한계는 컨텍스트 윈도우에 있다. 대화가 길어지면 앞에서 나눈 이야기가 밀려난다. 타로 프로젝트에서는 프로젝트 규모가 작아서 이게 큰 문제가 아니었다. 사주 프로젝트에서는 도메인 모델 하나만 해도 35페이지다. 한 세션의 대화로 전체 맥락을 유지하는 것이 불가능하다.

설계 문서를 별도 파일로 유지하면, 새로운 대화를 시작할 때마다 필요한 문서를 컨텍스트로 로드할 수 있다. Claude Code에서 @docs/02-DOMAIN-MODEL.md를 로드하고 "이 모델에 맞춰 십신 분석 함수를 구현해줘"라고 하면, AI가 프로젝트의 전체 데이터 구조를 이해한 상태에서 코드를 작성한다.

이것과 "매번 같은 설명을 반복하는 것"의 차이는 극적이다. 설계 문서 없이 대화만으로 진행했다면, 매 세션마다 "천간은 10개이고, 지지는 12개이고, 십신은 일간을 기준으로..."부터 다시 설명해야 한다. 설계 문서는 이 반복을 제거하고, 모든 대화가 동일한 기반 위에서 시작되게 만든다.

결과적으로 docs/ 폴더는 이중 목적을 가진다. 사람이 읽기 위한 문서이면서, 동시에 AI가 프로젝트 맥락을 파악하기 위한 참조 자료다. 이 이중 목적을 처음부터 의식하고 작성하면, 문서의 구조와 상세도가 자연스럽게 올라간다.

구현 순서라는 나침반

설계 문서의 마지막에 README.md를 추가했다. 여기에 20단계의 구현 순서를 정리했다.

Phase 1은 기반 구축으로, 프로젝트 셋업과 타입 정의, 기초 데이터 테이블이다. Phase 2는 계산 엔진으로, 만세력 모듈과 사주 기둥 계산, 단위 테스트다. Phase 3은 분석 엔진으로, 오행, 십신, 용신, 합충형파해, 12운성, 대운을 차례로 구현한다. Phase 4는 AI 해석 연동이고, Phase 5가 UI, Phase 6이 검증과 고도화다.

이 순서가 존재한다는 것 자체가 프로젝트에 안정감을 준다. "다음에 뭘 해야 하지?"라는 질문이 사라진다. 매일 작업을 시작할 때 체크리스트에서 다음 항목을 확인하면 된다. 그리고 이 체크리스트는 AI와의 대화에서도 유용하다. "Phase 2의 ⑤번, 사주 기둥 계산을 구현하자. @docs/03-CALCULATION-ENGINE.md를 참조해줘"라고 말하면, 정확히 어떤 맥락에서 어떤 코드를 작성해야 하는지 AI가 즉시 파악한다.

원천 데이터 소스까지 조사하다

설계 문서를 만드는 과정에서 한 걸음 더 나간 것이 있다. 전문 앱들이 어떤 데이터 소스를 사용하는지 조사한 것이다.

1편에서 벤치마킹 때 앱마다 결과가 달랐던 이유를 파고들자, 데이터의 출처 차이가 근본 원인이라는 것을 알게 됐다. 한국천문연구원(KASI) 데이터를 사용하는 앱과 그렇지 않은 앱의 정확도 차이가 확연했다.

다섯 번째 문서(05-DATA-SOURCES.md)를 추가로 작성했다. KASI 공공 API의 구조와 활용법, NPM에 이미 정리된 KASI 데이터 패키지(@kokr/date), 오픈소스 만세력 라이브러리 5개의 비교 분석, 명리학 3대 고전(적천수, 자평진전, 궁통보감)의 핵심 원리와 구조화 방안까지 담았다.

특히 궁통보감(窮通寶鑑)의 구조화가 중요했다. 일간 10개와 월지 12개의 120가지 조합별로 필요한 오행을 정의한 이 고전 텍스트는, AI 해석 프롬프트에 참조 데이터로 제공하면 해석 품질이 극적으로 올라간다. "잘 써줘"보다 "이 데이터를 참고해서 써줘"가 훨씬 효과적이라는 것을 나중에 확인했다.

신살(神煞) 데이터도 이 과정에서 필수 기능으로 격상됐다. 원래 설계에서는 P3(향후)로 분류했었는데, 전문 앱들이 예외 없이 20종 이상의 신살을 표시하고 있었다. 역마살, 천을귀인, 도화살 같은 것들이다. 사용자 관점에서 "내 사주에 역마살이 있는가"는 가장 궁금해하는 항목 중 하나였다.

설계 문서 작성에서 배운 것

첫째, 도메인 복잡도가 높을수록 설계 문서의 가치가 기하급수적으로 올라간다. 간단한 프로젝트에서는 코드가 곧 설계여도 괜찮다. 하지만 사주처럼 비개발 영역의 전문 지식이 필요한 프로젝트에서는 "무엇을 코드로 옮길 것인가"를 먼저 정리하는 것이 필수다.

둘째, AI는 도메인 지식을 빠르게 구조화하는 데 탁월하다. 명리학이라는 수천 년 된 지식 체계를 TypeScript 타입 시스템으로 번역하는 과정에서, AI는 "번역가"이자 "도메인 전문가" 역할을 동시에 수행했다.

셋째, 설계 문서의 이중 목적(사람용 + AI 컨텍스트)을 처음부터 의식하면 문서의 품질과 활용도가 모두 올라간다. 타입 정의를 포함하고, 의사결정의 맥락을 기록하고, 학파별 차이를 명시하는 것은 사람에게도 AI에게도 유용하다.

넷째, 구현 순서를 문서화하면 프로젝트의 불확실성이 크게 줄어든다. "다음에 뭘 하지?"라는 질문이 사라지고, AI와의 대화도 정확한 맥락에서 시작할 수 있다.

다음 편 예고

네 개의 설계 문서가 완성됐으니, 이제 진짜 코드를 작성할 차례다. 3편에서는 도메인 모델을 TypeScript로 옮기는 과정, 만세력이라는 거대한 벽, 그리고 절기·진태양시·서머타임이라는 정밀도 전쟁을 다룬다.

---

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