설계 문서 우선 개발 — AI 시대의 게임 체인저

 

코드를 한 줄도 쓰기 전에 문서를 먼저 쓴다. 개발자라면 누구나 아는 원칙이지만 실제로 지키는 사람은 드물다. 그런데 AI와 협업하면서 이 원칙이 단순한 모범 사례가 아니라 생산성의 핵심이라는 것을 깨달았다. 특히 사주명리처럼 복잡한 도메인에서는 설계 문서가 있고 없고의 차이가 하늘과 땅이었다.

타로 때의 방식 — 대화에서 코드로

타로 프로젝트를 돌이켜보자. 그때의 워크플로우는 이랬다. AI와 대화를 나누면서 "78장 카드의 데이터 구조를 어떻게 잡을까?"라고 묻고, AI가 제안하면 바로 코드로 옮긴다. 코드가 동작하면 다음 기능으로 넘어간다. 문제가 생기면 대화를 이어가며 수정한다.

이 방식은 빠르고 직관적이었다. 타로의 복잡도에서는 충분히 작동했다. 78장의 카드, 고정된 해석 텍스트, 비교적 단순한 리딩 로직. 전체 구조를 머릿속에 담을 수 있는 규모였기에 대화 기반으로도 일관성을 유지할 수 있었다.

하지만 사주 프로젝트에 들어가면서 이 방식의 한계가 드러났다. 천간지지 계산, 십신 관계, 합충형파해, 12운성, 지장간, 격국, 용신. 이 모든 요소가 서로 얽혀 있는 도메인에서 대화만으로 맥락을 유지하는 것은 불가능했다.

한계를 깨닫는 순간

사주 프로젝트 초기에도 타로 때와 같은 방식을 시도했다. AI와 대화하며 "십신 계산 로직을 구현해볼까"라고 하면 AI가 코드를 생성한다. 그런데 다음 세션에서 "지장간 분석을 추가하자"고 하면 AI가 이전 세션의 십신 로직과 일관되지 않는 구조를 제안하는 경우가 생겼다.

이유는 단순했다. AI의 대화 컨텍스트에는 한계가 있다. 이전 세션에서 어떤 결정을 내렸는지, 데이터 구조를 어떻게 잡았는지, 왜 그 방식을 선택했는지 — 이런 정보가 새 세션에서는 사라진다. 코드를 읽으면 "무엇"은 알 수 있지만 "왜"는 알 수 없다.

타로에서는 이 문제가 크지 않았다. 구조가 단순하니 코드만 봐도 맥락이 파악됐다. 사주에서는 달랐다. "이 십신 테이블에서 편인을 이렇게 정의한 이유"를 코드에서 읽어내기는 어렵다. 그 결정의 배경, 고려한 대안, 학파별 차이 — 이런 컨텍스트는 문서에만 담을 수 있다.

docs/ 폴더의 탄생

그래서 docs/ 폴더를 만들었다. 처음에는 단순히 "나중에 참고하려고" 시작한 것이었는데, 점점 이 폴더의 역할이 커졌다.

docs/ 폴더에는 다양한 문서가 들어갔다. 도메인 모델 정의서, 데이터 구조 명세, 각 기능의 설계 결정 기록, 학파별 계산 방식 차이 정리, API 스펙, UI 플로우 등. 문서의 형식은 마크다운으로 통일했다. 사람이 읽기에도 좋고 AI가 파싱하기에도 좋은 포맷이다.

핵심은 이 문서들이 "사람용 문서"와 "AI 컨텍스트"라는 이중 목적을 가진다는 것이다. 사람인 내가 몇 주 후에 읽어도 "왜 이렇게 설계했는지"를 이해할 수 있어야 하고, AI에게 로드시켰을 때도 전체 프로젝트의 맥락을 파악할 수 있어야 한다.

예를 들어 십신 관계 정의서에는 이런 내용이 들어있다. 십신의 정의, 각 십신의 계산 규칙, 학파별 차이점, 선택한 방식과 그 이유, 관련 코드 파일 경로. 이 문서 하나를 AI에게 로드시키면 AI는 "이 프로젝트에서 십신을 어떻게 다루고 있는지"를 완전히 이해한 상태에서 관련 코드를 작성하거나 수정할 수 있다.

@docs/ 로드 — AI가 전체 맥락을 아는 상태에서 코드 작성

실제 워크플로우는 이렇게 바뀌었다. 새로운 기능을 구현하기 전에, 관련 설계 문서를 AI에게 먼저 로드시킨다. "이 문서들을 읽고 이해한 상태에서 이 기능을 구현해줘."

예를 들어 궁합 분석 기능을 구현할 때. 먼저 십신 정의서, 오행 상생상극 규칙서, 합충형파해 규칙서를 로드한다. 그 상태에서 "두 사주 간의 궁합을 분석하는 로직을 구현해줘"라고 요청한다. AI는 이미 프로젝트의 십신이 어떻게 정의되어 있고, 오행 관계가 어떤 규칙을 따르는지 알고 있으니, 기존 코드베이스와 일관된 구현을 생성한다.

이전 방식에서는 "십신은 이렇게 계산하고, 오행은 이런 관계가 있고, 우리 프로젝트에서는 이런 구조를 쓰고 있어" 하고 매번 설명해야 했다. 설계 문서가 있으면 이 설명이 불필요하다. 문서를 로드하는 것으로 끝이다.

이 차이는 생산성에서 체감이 엄청났다. 매 세션마다 10~15분씩 컨텍스트를 설명하던 시간이 사라졌다. 그리고 설명이 매번 미묘하게 달라지면서 생기던 일관성 문제도 해결됐다.

설계 문서의 세 가지 실질적 이점

프로젝트를 진행하면서 체감한 설계 문서의 이점을 세 가지로 정리한다.

첫째, 사고의 구조화. 문서를 쓰는 행위 자체가 생각을 정리하는 과정이다. "궁합 분석에서 어떤 요소를 볼 것인가"를 문서로 정리하면, 코드 구현 전에 이미 설계의 빈틈이 보인다. 구현 단계에서 "아 이건 빠뜨렸네" 하는 상황이 크게 줄어든다.

코드를 바로 짜기 시작하면 "일단 동작하게 만들자"에 매몰되기 쉽다. 문서를 먼저 쓰면 "무엇을 만들 것인지"와 "어떻게 만들 것인지"를 분리해서 생각할 수 있다. 이 분리가 설계 품질에 큰 차이를 만든다.

둘째, AI 컨텍스트의 영속화. 대화는 세션이 끝나면 사라지지만 문서는 남는다. 다음 주에 이 프로젝트를 다시 열었을 때, 3개월 후에 유지보수가 필요할 때, 문서를 로드하면 AI는 즉시 프로젝트의 전체 맥락을 파악한다. 이것은 일종의 "AI를 위한 장기 기억"이다.

특히 사주 프로젝트처럼 도메인 지식이 방대한 경우, 이 영속적 컨텍스트의 가치는 매우 크다. 천간지지의 오행 배속, 십신 계산 규칙, 학파별 차이 — 이런 도메인 지식을 매번 새로 설명하는 것과 문서를 한 번 로드하는 것의 차이를 상상해보라.

셋째, 팀 확장의 기반. 현재는 1인 프로젝트지만, 미래에 다른 개발자가 합류한다면 이 문서들이 온보딩 자료가 된다. 코드만 있는 프로젝트에 새 개발자가 합류하면 "이 코드가 왜 이렇게 되어 있지?"를 코드를 뜯어보며 파악해야 한다. 설계 문서가 있으면 그 시간이 극적으로 줄어든다.

그리고 이것은 AI 팀원에게도 동일하게 적용된다. 새 AI 세션을 여는 것은 새 팀원이 합류하는 것과 같다. 그 팀원에게 프로젝트를 설명하는 가장 효율적인 방법이 설계 문서다.

"무엇을 만들 것인지 명확하게 정의하는 것"

AI 시대에 개발자에게 가장 중요한 역량이 무엇이냐고 묻는다면, 나는 "코딩 능력"이 아니라 "정의 능력"이라고 답하겠다. 무엇을 만들 것인지를 명확하게 정의하는 능력.

AI는 "어떻게"를 잘한다. "십신 계산 로직을 구현해줘"라고 하면 코드를 잘 짠다. 하지만 "무엇을"은 사람이 정해야 한다. 십신을 어떤 규칙으로 계산할 것인지, 어느 학파의 방식을 따를 것인지, 예외 케이스를 어떻게 처리할 것인지.

설계 문서는 이 "무엇을"을 명확하게 기록하는 도구다. 문서가 정확할수록 AI의 구현 품질이 올라간다. 모호한 지시에서는 모호한 결과가 나오고, 명확한 정의에서는 명확한 결과가 나온다. 이것은 프롬프트 엔지니어링의 본질이기도 하다.

복잡한 도메인일수록 설계 문서의 ROI가 증가한다

설계 문서를 쓰는 것은 비용이다. 시간이 든다. 코드를 바로 짜는 것보다 느리게 느껴진다. 그래서 많은 개발자가 문서 쓰기를 건너뛴다.

하지만 이 비용의 회수율(ROI)은 도메인의 복잡도에 비례해서 기하급수적으로 증가한다.

타로처럼 단순한 도메인에서는 문서 없이도 갈 수 있다. 전체 구조를 머릿속에 담을 수 있으니까. 투자 대비 회수가 적을 수 있다.

사주처럼 복잡한 도메인에서는 문서가 필수다. 전체 구조를 머릿속에 담을 수 없고, AI의 컨텍스트에도 한 번에 다 넣을 수 없다. 문서가 없으면 매 세션마다 컨텍스트를 재구성하는 비용이 발생하고, 일관성이 무너지는 리스크가 커진다. 문서를 쓰는 초기 비용보다 문서가 없어서 발생하는 반복 비용이 훨씬 크다.

이 프로젝트에서 체감한 바로는, docs/ 폴더에 투자한 시간 대비 절약한 시간이 대략 3~5배 정도였다. 문서를 쓰는 데 2시간이 걸렸으면, 그 문서가 이후 구현과 유지보수에서 6~10시간을 절약해준 셈이다.

설계 문서 우선 개발의 워크플로우

최종적으로 정리된 워크플로우는 이렇다.

1단계, 문제 정의. 어떤 기능을 왜 만드는지를 한 문단으로 정리한다. 2단계, 도메인 리서치. AI와 대화하며 도메인의 규칙과 예외를 파악한다. 3단계, 설계 문서 작성. 데이터 구조, 계산 규칙, UI 플로우, 예외 처리 방침을 문서로 작성한다. 4단계, 문서 리뷰. AI에게 문서를 로드시키고 "이 설계에 빈틈이 있어?"라고 물어본다. 5단계, 구현. 문서를 기반으로 AI와 함께 코드를 작성한다.

이 다섯 단계 중 3단계까지가 전체 시간의 60%를 차지한다. 코드 작성은 40%다. 전통적인 개발에서 코드 작성이 80% 이상이었던 것과 비교하면 비율이 완전히 뒤집힌 것이다.

하지만 이 비율의 역전이 오히려 전체 생산성을 높였다. 설계가 탄탄하면 구현에서 삽질이 줄고, 버그가 줄고, 리팩토링이 줄기 때문이다.

이 과정에서 배운 것

첫째, 설계 문서는 "쓰는 사람을 위한 것"이기도 하다. 남을 위해 문서를 쓴다고 생각하면 귀찮지만, 실제로는 쓰는 과정에서 본인의 사고가 가장 많이 정리된다.

둘째, AI 시대의 문서는 "사람 + AI" 이중 독자를 위한 것이다. 사람이 읽어도 이해되고, AI에게 로드시켜도 유효한 컨텍스트가 되는 문서. 이 두 가지를 동시에 만족시키는 것이 핵심이다.

셋째, 바이브 코딩의 다음 단계는 "바이브 설계"다. 코드를 AI와 함께 짜는 것이 바이브 코딩이라면, 설계를 AI와 함께 정리하고 그 설계를 기반으로 구현하는 것이 한 단계 진화한 방식이다.

다음 편 예고

19편의 이야기를 끝으로 방법론 이야기는 마무리된다. 20편, 시리즈의 마지막 편에서는 타로부터 사주까지의 여정을 되돌아본다. AI가 잘한 것, 사람이 해야 했던 것, 그리고 28년 개발 경력에서 AI가 바꾼 가장 큰 것. 시리즈의 마지막 이야기가 이어진다.