코드 한 줄 쓰기 전에 — 설계 문서 우선 개발

 

사이드 프로젝트에서 설계 문서를 먼저 쓴다고? 과한 것 아닌가? 대부분의 개발자는 그렇게 생각할 것이다. 나도 타로 프로젝트 때는 그랬다. 그런데 사주 프로젝트에서는 코드 한 줄 쓰기 전에 docs/ 폴더에 4개의 설계 문서를 먼저 작성했다. 그리고 이 결정이 AI 협업의 판도를 완전히 바꿨다.

타로에서는 바로 코드였다

타로 마스터 프로젝트를 떠올려보자. 1편에서 아이디어를 던지고, 도메인을 파악하고, 바로 코드를 쓰기 시작했다. 그리고 그것이 잘 작동했다. 타로는 구조가 비교적 단순해서, AI와 대화하면서 바로 구현해도 큰 문제가 없었다.

그런데 사주 프로젝트 초반, AI와 대화하면서 도메인을 파악하는 과정에서 느낀 것이 있다. 이 도메인은 한 번의 대화 세션에 담기지 않는다는 것이다. 천간지지, 오행, 십신, 지장간, 합충형파해, 12운성. 하나하나가 독립적인 체계이면서 서로 얽혀 있다. 대화 한 세션에서 이 모든 것을 다루면 컨텍스트가 흐려진다.

더 근본적인 문제는 세션이 바뀔 때 생긴다. AI와의 대화는 세션 단위다. 새 세션을 시작하면 이전 대화의 맥락이 사라진다. 타로에서는 이게 큰 문제가 아니었다. 78장 카드 구조 정도는 몇 줄로 다시 설명할 수 있으니까. 하지만 사주의 도메인 지식을 매 세션마다 처음부터 설명하는 건 현실적이지 않다.

설계 문서라는 해법

이 문제의 해법이 설계 문서였다. 코드 대신 문서를 먼저 작성하면, 그 문서가 AI를 위한 "영구적 컨텍스트"로 기능할 수 있다.

아이디어는 단순했다. 도메인 지식과 설계 결정을 문서로 정리해두면, 새 대화 세션에서 @docs/ 한 번으로 AI가 전체 맥락을 이해한 상태에서 시작할 수 있다. 매번 "이 프로젝트는 사주명리 분석 웹앱이고, 하이브리드 아키텍처를 쓰고, 진태양시 보정이 있고..." 이런 설명을 반복하지 않아도 된다.

이것은 단순히 "편의성"의 문제가 아니었다. AI 협업의 품질 자체가 달라졌다. 컨텍스트를 모르는 AI에게 코드를 요청하는 것과, 전체 아키텍처와 도메인 모델을 이해한 AI에게 코드를 요청하는 것은 결과물의 수준이 완전히 다르다.

docs/ 폴더의 4개 문서

프로젝트의 docs/ 폴더에는 4개의 핵심 설계 문서가 들어갔다.

첫 번째는 아키텍처 문서다. 전체 시스템의 구조를 다룬다. React 19 + TypeScript + Vite + Zustand 기반의 프론트엔드, Cloudflare Workers + Groq API 기반의 AI 해석 서버, 룰 기반 분석 엔진과 AI 해석의 하이브리드 구조. 각 계층이 어떻게 통신하고, 데이터가 어떤 흐름으로 이동하는지를 정리했다.

두 번째는 도메인 모델 문서다. 이것이 가장 방대했다. 35페이지에 달하는 이 문서에는 사주명리의 핵심 개념이 개발자 관점에서 정리돼 있다. 천간 10개와 지지 12개의 속성, 60갑자 체계, 오행 상생상극 관계, 십신 분류 체계, 지장간 배속, 12운성 표, 합충형파해의 모든 조합. 각 개념이 무엇인지, 어떤 데이터 구조로 표현해야 하는지, 학파별 차이가 있다면 어떤 것인지까지 포함된다.

세 번째는 계산 엔진 문서다. 만세력 변환 로직, 진태양시 보정 알고리즘, 서머타임 보정, 야자시 처리, 절기 기반 월 결정 로직 등 "입력(생년월일시)을 사주 팔자로 변환하는 과정"의 모든 계산을 다룬다.

네 번째는 AI 해석 문서다. 룰 기반 엔진이 생성한 분석 데이터를 AI에게 전달하여 자연어 해석을 생성하는 구조. 프롬프트 설계, 해석의 톤과 깊이, 구조화된 분석 데이터의 포맷 등을 정리했다.

35페이지짜리 도메인 모델

4개 문서 중 가장 공을 들인 것이 도메인 모델 문서다. 35페이지. 사이드 프로젝트 문서치고는 과하다고 느낄 수 있다. 하지만 이 35페이지에는 사주명리의 핵심 체계가 빠짐없이 들어 있다.

왜 이렇게까지 상세해야 했을까. 사주명리는 수천 년간 축적된 체계다. 그리고 그 체계에는 수많은 "규칙"이 있다. 甲(갑)은 양목이고, 乙(을)은 음목이다. 甲과 己(기)가 만나면 합이 된다. 寅(인), 午(오), 戌(술)이 모이면 삼합 화국이다. 이런 규칙 하나하나가 코드의 매핑 테이블이 된다.

이 규칙들을 문서로 정리하지 않고 AI와 대화하면서 하나씩 구현하면 어떻게 될까. "갑과 기가 합이 되는 거 맞지?" "맞습니다." "그럼 을과 경은?" "합입니다." "병과 신은?" 이런 식으로 하나씩 물어보면서 코드를 쓰게 된다. 비효율적일 뿐 아니라, 전체 체계의 일관성을 유지하기 어렵다.

반면, 도메인 모델 문서에 천간합 5쌍, 삼합 4조, 방합 4조, 육합 6쌍, 육충 6쌍이 모두 정리돼 있으면, AI는 이 문서를 한 번 읽고 전체 구조를 파악한 상태에서 코드를 작성한다. 개별 규칙을 하나씩 확인하는 게 아니라, 체계 전체를 이해한 상태에서 구현하는 것이다.

@docs/의 마법

설계 문서의 진짜 가치는 새 세션에서 드러난다. 새 대화를 시작하고, @docs/ 폴더를 컨텍스트로 로드한다. 그 순간 AI는 이 프로젝트의 아키텍처, 도메인 모델, 계산 로직, AI 해석 구조를 모두 이해한 상태가 된다.

이 상태에서 "십신 분석 함수를 구현해줘"라고 요청하면, AI는 다음을 이미 알고 있다. 십신이 일간을 기준으로 다른 글자와의 오행/음양 관계를 분류하는 체계라는 것. 같은 오행이면 비겁, 내가 생하는 오행이면 식상, 나를 생하는 오행이면 인성 같은 분류 규칙. 음양이 같으면 "편", 다르면 "정"이 되는 규칙. 도메인 모델 문서에 이 모든 것이 정리돼 있기 때문이다.

이것을 문서 없이 하려면 어떻게 되는가. "십신이 뭔지 알아?" "네, 십신은..." "일간이 갑(甲)이고 상대가 병(丙)이면 뭐야?" "식신입니다." "왜?" "갑은 양목이고 병은 양화인데, 목이 화를 생하니까 식상이고, 양과 양이라 편이 아니라... 아, 양과 양이면 편이 맞으니까 식신입니다." 이런 식의 대화가 매 세션마다 반복된다. 문서를 로드하면 이 반복이 사라진다.

매 세션마다 반복 설명 vs 문서 기반 컨텍스트

두 방식의 차이를 좀 더 구체적으로 비교해보자.

문서 없이 작업하는 경우: 새 세션 시작 → 프로젝트 개요 설명(5분) → 현재 작업 맥락 설명(5분) → 이전 세션에서의 결정 사항 설명(5분) → 실제 작업 시작. 매 세션마다 15분의 컨텍스트 세팅 시간이 필요하다. 그리고 이 설명이 매번 완벽하지 않다. 빠뜨리는 것이 있고, 잘못 기억하는 것이 있다.

문서 기반으로 작업하는 경우: 새 세션 시작 → @docs/ 로드(1분) → "이전 세션에서 합충형파해까지 구현했고, 이번에는 12운성을 구현하려 한다" 한 줄 설명 → 실제 작업 시작. 컨텍스트 세팅이 2분이면 끝난다. 그리고 문서에 모든 것이 정리돼 있기 때문에 빠뜨릴 것이 없다.

사주 프로젝트는 수십 번의 세션을 거쳐 완성됐다. 세션당 13분의 절약이 수십 번 반복되면, 순수하게 절약된 시간만 해도 상당하다. 하지만 시간 절약보다 더 큰 이점은 컨텍스트의 품질이다. 매번 구두로 설명하면 불완전하고 일관성 없는 컨텍스트가 전달되지만, 문서를 로드하면 완전하고 일관된 컨텍스트가 전달된다.

문서가 코드 품질을 높이는 메커니즘

설계 문서가 단순히 시간을 절약하는 것 이상의 역할을 한다는 것을 깨달은 것은 프로젝트 중반이었다.

AI가 전체 아키텍처를 이해한 상태에서 코드를 작성하면, 개별 함수의 인터페이스가 전체 구조와 일관된다. 오행 분석 함수가 반환하는 데이터 형태가 십신 분석 함수의 입력과 자연스럽게 연결된다. 각 모듈이 "전체를 모른 채 독립적으로 만들어진 조각"이 아니라 "전체를 알고 자기 자리에 맞게 만들어진 퍼즐 조각"이 된다.

이것은 사람이 코드를 작성할 때도 마찬가지다. 전체 설계를 모르는 개발자가 작성한 모듈과, 전체 설계를 이해한 개발자가 작성한 모듈은 품질이 다르다. AI에게도 같은 원리가 적용된다. 다만, AI는 문서를 주면 "완전히" 이해하기 때문에, 사람보다 이 효과가 더 극적이다.

설계 문서를 AI와 함께 작성하다

한 가지 중요한 점을 강조하고 싶다. 이 4개의 설계 문서를 혼자 작성한 것이 아니다. AI와 함께 작성했다.

도메인 모델 문서를 예로 들면, 작성 과정은 이랬다. 먼저 AI에게 사주명리의 핵심 개념을 설명해달라고 한다. 그 설명을 바탕으로 문서의 초안을 AI가 작성한다. 나는 그 초안을 읽으면서 이해가 안 되는 부분을 질문하고, 개발자 관점에서 필요한 정보를 추가 요청한다. AI가 수정본을 작성한다. 이 과정을 반복해서 35페이지의 문서가 완성됐다.

이 과정 자체가 도메인 학습이었다. 문서를 작성하면서 사주명리의 체계를 깊이 이해하게 됐다. 코드를 쓰기 전에 도메인을 충분히 이해하는 것, 이것이 "설계 문서 우선 개발"의 숨겨진 장점이다.

타로 vs 사주: 접근 방식이 달라야 하는 이유

타로에서는 바로 코드를 쓰는 방식이 잘 작동했다. 사주에서는 설계 문서 우선 방식이 필요했다. 이 차이는 도메인 복잡도의 차이에서 비롯된다.

타로의 도메인 지식은 한 세션의 대화에 충분히 담긴다. 78장, 정방향/역방향, 리딩 방식 세 가지. 사주의 도메인 지식은 여러 세션에 걸쳐도 전달하기 어렵다. 문서라는 "외부 기억 장치"가 필요하다.

이 경험에서 얻은 교훈은, AI 협업의 방법론이 프로젝트마다 달라야 한다는 것이다. 단순한 프로젝트에서 과도한 문서 작업은 오버엔지니어링이고, 복잡한 프로젝트에서 문서 없이 진행하는 것은 같은 설명을 반복하는 비효율이다. 도메인의 복잡도가 접근 방식을 결정한다.

이 과정에서 배운 것

첫째, 설계 문서는 "사람을 위한 문서"인 동시에 "AI를 위한 영구적 컨텍스트"다. 이 이중 역할이 AI 시대의 문서화에 새로운 가치를 부여한다.

둘째, 복잡한 도메인일수록 코드 전에 문서가 먼저다. 문서를 작성하는 과정 자체가 도메인 학습이고, 완성된 문서는 이후 모든 세션의 컨텍스트가 된다.

셋째, AI와 함께 문서를 작성하면, 혼자 쓸 때보다 훨씬 빠르고 체계적인 문서가 나온다. AI가 도메인 지식을 제공하고, 내가 개발 관점에서 구조화한다.

다음 편 예고

설계 문서가 완성됐다. 이제 드디어 코드를 쓸 차례다. 첫 번째 과제는 천간 10개와 지지 12개를 TypeScript 타입으로 표현하는 것이다. 수천 년 된 음양오행 체계를 현대 프로그래밍 언어로 "번역"하는 과정에서 어떤 설계 결정이 필요했는지, 그리고 첫 번째 학파 차이를 코드에서 어떻게 처리했는지, 4편에서 이어진다.