[바이브코딩] 01. AI와 일할 때 왜 문서가 필요할까? - SSOT, MECE, 컨텍스트

TL;DR

좋은 문서는 대화를 보관하는 기록이 아니라, 다음 대화를 더 정확하게 만드는 컨텍스트다.

AI와 긴 프로젝트를 진행할 때 결과가 흔들리는 이유는 코딩 능력만의 문제가 아니다.

서비스의 목적, 사용자 경험, 기술, 데이터, 기능을 한꺼번에 다루면 제안과 결정이 섞이고 무엇이 기준인지 모호해진다.

PRD, UX, 기술 스택, 데이터베이스, 도메인, API는 서로 다른 결정을 나누어 담는 문서다.

이 문서들을 SSOT와 MECE 원칙으로 정리하면 사람과 AI가 같은 기준을 볼 수 있다.

문서가 할루시네이션을 완전히 제거하지는 않지만, 충돌하는 정보와 불필요한 추측이 발생할 가능성을 줄여 준다.

 

ㅁ 들어가며

AI를 활용 방법에 대한 질문을 많이 받는다. 

단순히 AI에게 아이디어를 설명하고 “서비스로 만들어 줘”라고 요청하면 처음에는 놀라울 만큼 빠르게 결과가 나온다.

화면도 생기고, 기능도 붙고, 미처 생각하지 못했던 아이디어까지 제안받는다.

 

그런데 대화가 길어질수록 이상한 일이 생긴다.

처음에 중요하다고 했던 목적이 흐려지고, 잠깐 검토했던 아이디어가 꼭 필요한 기능처럼 바뀐다.

화면 이야기를 하다가 데이터 저장 방식이 등장하고, 기술을 정하다가 서비스의 대상 사용자까지 다시 바뀌기도 한다.

이 문제를 줄이려면 프롬프트를 무조건 길게 써야 할까?

꼭 그렇지는 않다. 긴 프로젝트에서 더 중요한 것은 결정을 주제별로 나누고, 확정된 내용을 문서로 남기는 일이다.

서비스를 만드는 일은 식당을 준비하는 일과 비슷하다.
각 문서는 서로 다른 결정을 담당하고, 확정된 문서는 다음 작업의 기준이 된다.

 

이 글에서는 개발 문서를 식당을 준비하는 과정에 비유해 살펴본다.

---

ㅁ AI에게 서비스를 한 번에 맡기면 왜 흔들릴까?

“친구들과 할 수 있는 게임 서비스를 만들어 줘.”

이 한 문장에는 아직 정해지지 않은 것이 많다.

누구를 위한 게임인지, 어떤 상황에서 사용하는지, 사용자는 어떤 화면을 보게 되는지, 어떤 정보를 저장해야 하는지 알 수 없다.

AI는 대답을 만들기 위해 비어 있는 부분을 추측하거나 여러 가능성을 한꺼번에 제안할 수밖에 없다.

 

제안 자체가 문제는 아니다. 문제는 제안과 결정이 섞이는 순간 시작된다.

사용자가 선택하지 않은 아이디어가 다음 대화에서 확정된 요구사항처럼 쓰이고,

서로 다른 단계의 이야기가 한 문서에 들어가면 무엇이 기준인지 알기 어려워진다.

그래서 서비스를 만드는 과정을 몇 개의 문서로 나눈다.

PRD, UX, 기술 스택, 데이터베이스, 도메인, API

문서를 많이 만들기 위해서가 아니라, 지금 어떤 질문에 답하고 있는지를 분명히 하기 위해서다.

개별 문서들이 왜 필요한지, 무엇을 위해 필요한지 이해를 돕기 위해 음식점에 비유를 들어 보았다.

 

ㅁ 서비스를 만드는 것은 왜 식당을 준비하는 일과 비슷할까?

식당을 준비한다고 생각해 보자.

“식당 하나 만들어 주세요”라는 말만으로는 바로 문을 열 수 없다.

먼저 어떤 손님을 위한 어떤 식당인지 정해야 한다.

손님이 보게 될 메뉴판과 주문 순서를 생각하고, 어떤 방식으로 요리할지 선택한다.

재료를 보관할 창고와 분류 기준을 만들고, 메뉴마다 레시피도 정해야 한다.

 

서비스도 마찬가지다.

개발 문서는 어려운 기술 용어를 늘어놓기 위한 설명서가 아니다.

서로 다른 종류의 결정을 나누어 담는 그릇이다.

어떤 식당인가?
      │
      ▼
손님은 어떻게 이용하는가?
      │
      ▼
어떤 방식으로 요리하는가?
      │
      ▼
재료를 어떻게 보관하고 분류하는가?
      │
      ▼
메뉴별로 어떻게 처리하는가?

서비스 문서	식당을 준비하는 일
PRD	어떤 식당을 만들 것인가
UX	손님에게 보여 줄 메뉴판과 음식 사진
기술 스택	한식·중식·일식과 같은 조리 방식
데이터베이스	음식 재료 창고
도메인	재료를 종류별로 정리한 공간
API	메뉴별 레시피

이 대응 관계를 알면 개발 지식이 많지 않아도 각 문서가 왜 필요한지 이해할 수 있다.

 

ㅇ PRD — 어떤 식당을 만들 것인가?

PRD는 어떤 식당을 만들지 정하는 문서다.

누구를 위한 식당인지, 어떤 음식을 제공할지, 손님에게 어떤 경험을 주고 싶은지를 먼저 정한다. 가족이 편하게 식사하는 한식당과 빠르게 한 끼를 해결하는 분식점은 메뉴와 공간, 운영 방식이 모두 다르다.

서비스도 목적과 대상 사용자가 먼저 정해져야 한다. Speed Quiz를 예로 들면, 중요한 질문은 어떤 기술을 쓸지가 아니다. “누가, 어떤 상황에서, 무엇을 더 편하게 하려고 이 서비스를 사용하는가?”가 먼저다.

PRD가 정리되지 않은 상태에서 화면이나 기술부터 결정하면 멋진 결과는 나올 수 있어도 처음 해결하려던 문제와는 멀어질 수 있다. PRD는 이후의 모든 판단이 돌아와 확인할 출발점이다.

 

ㅇ UX — 손님에게 무엇을 보여 줄 것인가?

식당의 방향을 정했다면 이제 손님이 무엇을 보고 어떻게 이용할지를 생각한다. 메뉴판은 어디에 있는지, 주문은 어떤 순서로 하는지, 음식이 나오기까지 손님은 무엇을 보게 되는지 정하는 일이다.

이것이 UX의 역할이다. UX는 화면을 예쁘게 꾸미는 일에만 머물지 않는다. 사용자가 서비스를 처음 만난 순간부터 목적을 달성할 때까지 어떤 행동을 하고 어떤 안내를 받는지 그려 보는 과정이다.

PRD가 “어떤 식당인가”에 답한다면 UX는 “손님이 그 식당을 어떻게 경험하는가”에 답한다. 이 단계에서는 조리도구나 재료 창고까지 결정하지 않는다. 손님의 경험이라는 한 가지 주제에 집중한다.

 

ㅇ 기술 스택 — 어떤 방식으로 요리할 것인가?

기술 스택은 음식을 만드는 조리 방식과 비슷하다.

한식, 중식, 일식은 필요한 도구와 재료를 다루는 방식이 다르다. 그렇다고 식당의 목적을 정하기도 전에 조리 방식부터 고르는 것은 자연스럽지 않다. 어떤 손님에게 무엇을 제공할지 정한 다음, 그 목적을 실현하기에 알맞은 방식을 선택해야 한다.

서비스에서도 기술은 목적을 이루기 위한 수단이다.

유행하는 기술을 먼저 선택한 뒤 서비스의 모습을 거기에 맞추는 것이 아니라,

만들고 싶은 경험이 정해진 뒤 그에 맞는 기술적 방향을 고른다.

비개발자가 모든 기술을 직접 비교할 필요는 없다.

다만 “왜 이 방식이 지금 만들려는 서비스에 맞는가?”라는 질문은 놓치지 않아야 한다.

 

ㅇ 데이터베이스 — 재료를 어디에 보관할 것인가?

데이터베이스는 식당에서 사용하는 재료를 보관하는 창고와 같다.

재료를 아무 곳에나 쌓아 두지 않고, 필요한 순간에 찾고 사용할 수 있도록 정해진 기준에 따라 보관한다.

서비스에도 계속 기억해야 하는 정보가 있다.

누가 참여했는지, 어떤 게임방인지, 어떤 문제가 나왔는지, 점수가 얼마인지 같은 정보다.

이런 정보를 어떤 형태로 저장하고 관리할지 정하는 것이 데이터베이스의 역할이다.

 

ㅇ 도메인 — 재료를 어떻게 분류할 것인가?

도메인은 창고 안의 재료를 성격에 따라 나누는 기준과 비슷하다.

채소, 고기, 해산물, 양념을 구분해 두면 필요한 재료를 쉽게 찾을 수 있다.

예를 들어, Speed Quiz에서도 사용자, 게임방, 문제, 점수처럼 서로 관련 있는 정보를 묶어서 생각할 수 있다.

데이터베이스가 “정보를 보관하는 곳”이라면 도메인은 “그 정보를 어떤 의미의 묶음으로 이해할 것인가”에 가깝다.

두 개념을 구분하면 저장할 정보와 서비스가 다루는 대상을 더 명확하게 바라볼 수 있다.

 

ㅇ API — 메뉴별 레시피

API는 메뉴별 레시피와 비슷하다.

주문이 들어오면 어떤 재료를 사용하고, 어떤 순서로 처리해, 어떤 결과를 내놓을지 정해져 있어야 한다. 같은 메뉴를 주문할 때마다 전혀 다른 음식이 나온다면 식당을 안정적으로 운영할 수 없다.

서비스의 기능도 비슷하다. 게임방 만들기, 참가하기, 게임 시작하기처럼 어떤 요청이 들어왔을 때 무엇을 확인하고 어떤 결과를 돌려줄지 약속이 필요하다. API는 기능들이 서로 요청과 결과를 주고받는 방식을 정리한다.

여기서 구체적인 규격이나 구현법까지 알 필요는 없다. API가 메뉴별 레시피처럼 기능의 동작을 일정하게 이어 주는 약속이라는 점을 이해하면 충분하다.

ㅁ 문서는 왜 다음 작업의 기준이 될까?

문서는 회의나 대화를 기록해 두는 메모에 그치지 않는다.

확정된 문서는 다음 작업이 시작될 기준이 된다.

식당의 콘셉트가 정리되어 있다면 메뉴판을 만드는 사람도, 주방을 설계하는 사람도 같은 식당을 상상할 수 있다.

담당자가 바뀌더라도 매번 “어떤 식당을 만들고 있었지?”라고 처음부터 추측할 필요가 없다.

 

AI와 일할 때도 마찬가지다. 문서는 다음과 같은 역할을 한다.

• 결정된 내용을 대화 밖에 보존한다.
• 사람과 AI가 같은 기준을 보게 한다.
• 다음 대화에서 다시 사용할 컨텍스트가 된다.
• 현재 작업의 범위를 분명하게 한다.
• 프로젝트가 임의로 확장되는 일을 줄인다.

따라서 문서는 이전 작업의 결과인 동시에 다음 작업의 입력이다. 한 단계에서 만든 문서가 다음 단계의 출발점이 된다.

ㅁ SSOT와 MECE는 왜 필요할까?

문서를 만든다고 해서 언제나 기준이 선명해지는 것은 아니다.

같은 결정을 여러 문서에 조금씩 다르게 적거나, 서로 다른 주제를 한 문서에 모두 넣으면 오히려 혼란이 커질 수 있다.

그래서 문서를 정리할 때 SSOT와 MECE라는 두 가지 원칙을 사용한다.

 

ㅇ SSOT — 하나의 결정은 하나의 기준에서 관리한다

SSOT(Single Source of Truth)는 하나의 사실과 결정을 하나의 기준 문서에서 관리한다는 뜻이다. 식당의 콘셉트를 메뉴 기획 문서와 주방 문서에서 서로 다르게 정하지 않고, 하나의 확정된 기준을 함께 보는 것과 같다. 서비스의 목적과 요구사항은 PRD에서 관리하고, 다른 문서는 그 내용을 다시 정의하기보다 기준으로 삼는다.

 

ㅇ MECE — 역할은 겹치지 않게, 내용은 빠짐없이 정리한다

MECE(Mutually Exclusive, Collectively Exhaustive)는 역할은 겹치지 않게 나누되 필요한 내용은 빠짐없이 담는다는 뜻이다.

PRD는 목적과 요구사항, UX는 사용자의 경험, 기술 문서는 기술적 선택을 맡는다.

동시에 각 문서 안에서는 그 주제를 이해하고 다음 작업을 진행하는 데 필요한 내용이 빠지지 않도록 정리한다.

이 원칙은 AI에게 매우 중요하다.

기준이 하나면 충돌하는 정보 중 무엇을 따라야 할지 해석하는 부담이 줄어든다.

역할이 나뉘고 필요한 내용이 갖춰져 있으면, 누락된 부분을 임의로 추측하거나 여러 문서의 내용을 억지로 결합할 가능성도 낮아진다.

 

다만 SSOT와 MECE가 할루시네이션을 완전히 제거하는 것은 아니다.

AI는 여전히 잘못 이해하거나 틀린 답을 만들 수 있다.

두 원칙은 AI가 참고할 기준을 더 선명하게 만들어 불필요한 추측과 정보 충돌의 가능성을 줄이는 방법이다.

 

ㅁ 좋은 문서는 왜 좋은 컨텍스트가 될까?

AI와 나눈 긴 대화에는 여러 종류의 정보가 섞여 있다.

확정된 결정도 있지만, 잠깐 검토한 아이디어와 제외하기로 한 제안, 중간에 잘못 이해한 내용도 들어 있다.

대화 전체를 다음 단계에 넘기면 AI는 그중 무엇이 진짜 기준인지 다시 추측해야 한다.

반대로 확정된 내용만 역할에 맞는 문서로 정리하면 다음 대화의 출발점이 분명해진다.

문서는 이전 결정을 보존하는 기억이 되고, 다음 작업의 범위를 알려 주는 안내판이 되며, 사람과 AI가 함께 보는 공통 기준이 된다.

 

ㅁ 마무리 — 좋은 문서는 다음 대화를 만든다

바이브 코딩에서 중요한 것은 처음부터 모든 개발 지식을 아는 것이 아니다.

지금 결정해야 할 주제를 구분하고, 그 결정을 문서로 남겨 다음 작업에 사용하는 것이다.

좋은 문서는 대화를 보관하는 기록이 아니라, 다음 대화를 더 정확하게 만드는 컨텍스트다.

그렇다면 이 문서를 실제 AI 협업에서는 어떻게 사용해야 할까?

다음 글에서는 하나의 주제를 선택하고, 역할을 부여하고, Plan Mode에서 논의한 뒤,

확정된 내용만 다음 컨텍스트로 넘기는 방법을 살펴본다.

 

ㅁ 함께 읽으면 좋은 글

ㅇ [바이브코딩] 02. AI와 오래 협업하려면 어떻게 해야 할까? - Plan Mode, 문서화, 컨텍스트

 - 하나의 주제, 페르소나, Plan Mode, 문서화를 반복하는 방법

ㅇ Context Note — AI 대화의 컨텍스트는 왜 “쌓지 않고 구조화”해야 할까?

 - ChatGPT와 함께 컨텍스트를 문서 중심으로 관리하기 위해 만든 도구이다.

 - GPT Atlas에서 트리 구조의 노트, 마크다운 편집기, ChatGPT 대화창을 함께 사용하며 필요한 컨텍스트를 구조화할 수 있다.