바이브코딩에 문서가 왜 필요한데?
— MD 31개 만들고 나서야 알게 된 것
코드가 3000줄을 넘기니까 AI가 어제 고친 버그를 오늘 다시 만들었습니다. 프롬프트를 더 잘 써야 하는 줄 알았는데 — 답은 문서 설계에 있었죠.
처음 3일은 마법이었죠
바이브코딩을 시작하면 누구나 비슷한 경험을 하게 됩니다. 말로 설명하면 코드가 나오고, 에러를 붙여넣으면 알아서 고쳐주고. “이거 진짜 되네?” 싶은 순간이 하루에도 열 번씩 찾아오죠.
근데 Day 4부터 분위기가 달라졌어요.
어제 분명히 고친 버그를 AI가 오늘 다시 만들더라고요. 합의한 네이밍 컨벤션을 무시하고, 파일 구조를 까먹고, 심지어 삭제한 코드를 다시 작성하는 경우까지. 처음엔 제 프롬프트가 부족한 줄 알았어요. 그래서 프롬프트를 더 길게, 더 자세하게 썼죠.
소용없었습니다.
AI는 “능력은 시니어급인데 30분마다 기억을 잃는 신입”과 같았습니다. 문제는 프롬프트가 아니라, AI에게 기억 장치가 없다는 것이었죠.
프롬프트 장인이 되면 해결될 줄 알았는데
“프롬프트만 잘 쓰면 AI가 알아서 한다” — 바이브코딩 관련 글을 읽으면 거의 다 이 얘기거든요. 프롬프트 템플릿, 프롬프트 체이닝, 시스템 프롬프트 최적화. 근데 실제로 2주짜리 프로젝트를 굴려보면 금방 한계가 보여요.
대화가 끝나면 맥락도 끝나잖아요. 다음 세션에서 AI는 백지 상태입니다. 아무리 완벽한 프롬프트를 써도, 지난주에 합의한 데이터 스키마를 기억하게 만들 수는 없죠. Context window라는 물리적 한계가 있으니까요. 코드 전체를 매번 읽히는 것도 불가능하고.
“프롬프트는 ‘오늘의 지시’이고, 문서는 ‘영구 매뉴얼’이다. AI에게 진짜 필요한 건 후자였다.”
전환점은 간단했어요. “프롬프트에 맥락을 넣는다”에서 “문서에 맥락을 넣고, AI에게 문서를 읽히라고 한다”로 바꾼 것. 이 차이가 생각보다 크더라고요.
“이 프로젝트는 Next.js 16 기반이고, 서버 컴포넌트 우선이고, Tailwind CSS 쓰고, 네이밍은 PascalCase이고, 이 파일 구조는…”
매번 프롬프트에 500자씩 붙여넣기
“CLAUDE.md 읽고 코드 수정해”
한 줄이면 끝. 문서가 맥락을 담고 있으니까
우리가 만든 구조 — 3계층 31개 파일
S 프로젝트(AI SaaS MVP)를 2주간 만들면서 최종적으로 만들어진 바이브코딩 문서 설계 구조입니다. 처음부터 계획한 게 아니에요. 터질 때마다 하나씩 추가하다 보니 이렇게 됐죠.
| 계층 | 파일 수 | 역할 | 비유 |
|---|---|---|---|
| L1: CLAUDE.md | 1 | AI의 행동 규칙 — 네이밍, 컴포넌트 룰, 디렉토리 구조 | 신입 첫 출근 날 사내 규정집 |
| L2: claudedocs/ | 17 | 기획 + 엔지니어링 가이드 — PRD, 데이터 스키마, QA 플레이북 | 팀 위키 + 기술 문서 |
| L3: design/ | 13 | UI/UX 디자인 시스템 — 랜딩, 대시보드, 모션, 상태 매트릭스 | 디자인 시스템 핸드북 |
L1: CLAUDE.md — AI가 자동으로 읽는 규칙서
Claude Code에는 프로젝트 루트에 CLAUDE.md를 두면 매 세션 시작 시 자동으로 읽히는 기능이 있거든요. 우리는 여기에 9개 섹션을 넣었어요.
이것만으로도 AI가 “갑자기 CSS-in-JS를 쓴다거나” “변수를 snake_case로 바꾼다거나” 하는 실수가 사라졌어요. 사내 규정집을 한 번 읽힌 셈이죠.
L2: claudedocs/ — 기획과 엔지니어링의 분리
코드가 길어지면서 CLAUDE.md만으로는 부족해지더라고요. “이 기능의 사용자 플로우가 뭐였지?”, “결제 로직의 멱등성 규칙이 뭐였지?” — 이런 질문에 CLAUDE.md가 답할 수는 없잖아요.
그래서 claudedocs/ 폴더에 문서를 분리했습니다. 17개 파일인데, 크게 세 종류예요.
| 유형 | 파일 | 역할 |
|---|---|---|
| 기획 MD | MAIN_PRD, AI_SPEC, DATA_SCHEMA, BILLING, 사업계획서, v3_변경사항 | “무엇을 만들 것인가” |
| 코드 수정 MD | ENGINEERING_GUIDE, QA_DEBUG, QA_DEBUG_PLAYBOOK, REALITY_STATUS, PROJECT_STATUS | “어떻게 고칠 것인가” |
| 전환기 MD | v3_변경사항, mvp-gap-analysis, api-less-mvp, simple-input-mvp 등 | “왜 바꿨는가” |
재밌는 건 “전환기 MD”예요. v3로 피벗할 때 “왜 바꿨는가”를 문서로 남겨뒀거든요. 실제 v3_변경사항.md에는 이런 내용이 있습니다.
이 문서가 없었으면? 피벗 이후에 AI가 v2 스펙대로 코드를 짜는 사고가 났을 거예요. “v3_변경사항.md 읽고 수정해”라고 한 줄 쓰는 것과, 피벗 배경을 매번 프롬프트로 설명하는 것 — 차이가 얼마나 큰지 직접 겪어봐야 알죠.
L3: design/ — UI 스펙의 독립
Day 12쯤 되니까 UI 관련 지시와 코드 로직 지시가 뒤섞이기 시작했어요. “대시보드 레이아웃은 이렇게”라는 내용이 ENGINEERING_GUIDE에 들어가 있고, “에러 처리 규칙”이 LANDING.md에 들어가 있고. 이러면 AI도 혼란스러워하거든요.
그래서 design/ 하위 폴더로 13개를 분리했습니다. LANDING.md, DASHBOARD_SHELL.md, MOTION_SYSTEM.md, STATES_MATRIX.md 같은 파일들이죠.
“이 저장소에서 제품/기획/구현/테스트/결제에 대한 정본(Single Source of Truth)은 claudedocs/ 폴더 내 문서들이다. 문서와 코드가 충돌하면, 문서를 먼저 수정한 뒤 코드를 수정한다.“
31개 문서에도 ‘지도’가 필요하더라고요
문서가 20개를 넘어가니까 새로운 문제가 생겼어요. “이 작업은 어느 문서를 참고해야 하지?” AI한테 “claudedocs 전부 읽어”라고 하면 토큰 폭탄이고, 특정 파일만 지정하자니 뭘 지정해야 할지 모르겠고.
그래서 index.md를 만들었습니다. 문서의 지도죠. 핵심은 7단계 필독 순서와 5가지 절대 규칙이에요.
7단계 필독 순서
PRD.md
사용자 플로우, 화면/퍼널, 루즈함 방지 규칙. “무엇을 만드는가”의 출발점.
AI_SPEC.md
Evidence/출처 정책, 할루시네이션 방지, Loop Safety. AI가 거짓말하지 않게 만드는 규칙.
DATA_SCHEMA.md
프로젝트/문서/리포트/증거/점수/구독 데이터 모델. 코드의 뼈대.
QA_DEBUG_PLAYBOOK.md
“한 곳 수정 → 다른 곳 오류” 방지 프로토콜.
QA_DEBUG.md
테스트 매트릭스 — 무한루프, 가짜 경쟁사, 출처 깨짐, PDF 실패, 비용 폭주 시나리오.
BILLING.md
Free/Basic/Pro 정책, 결제 confirm/webhook 멱등성.
ENGINEERING_GUIDE.md
코드 구조, 리팩터 우선순위, 클린 코드 규칙, 테스트 최소 세트.
5가지 절대 규칙
index.md에는 “이것만은 절대 안 된다”는 규칙이 있어요. AI가 아무리 자신감 넘치게 코드를 써도, 이 규칙을 어기면 안 되는 거죠.
1. 루즈함 금지 — 최대 6턴 제한. 동일 질문 2회 반복 금지. 부족한 입력은 “가설 + 선택지 + 확인 질문 1개”로 처리.
2. 출처 없는 단정 금지 — 경쟁사/뉴스/정부사업 정보는 링크 없이 확정 표기 금지.
3. 현실성 강제 — STOP 기준(수치) + 실행 WBS(2시간~2일) 없으면 저장 불가.
4. 비용 폭주 방지 — 기능별 비용/사용량 로그 없으면 배포 금지.
5. 서버가 단일 진실 — 구독/권한/언락 상태는 서버(DB)가 정본. 클라이언트는 표시만.
이 규칙들이 실제로 코드에 반영됐는지는 REALITY_STATUS.md로 검증했어요. 문서에 “출처 없으면 저장 금지”라고 써놨으니까, 코드에서도 hallucination-filter.ts가 가짜 경쟁사 13개 패턴을 감지하고 URL 없는 경쟁사를 “미확실”로 분류하는지 확인한 거죠.
2주 안에 31개 문서가 쌓인 과정
솔직히 말하면 31개를 계획해서 만든 게 아니에요. 터질 때마다 하나씩 생긴 겁니다.
CLAUDE.md 하나면 충분했다
코드가 500줄도 안 될 때. 네이밍 규칙이랑 디렉토리 구조 정도만 적어두면 AI가 잘 따라왔어요. “문서 시스템? 그런 거 왜 필요해?” 싶었죠.
AI가 합의를 까먹고, DB를 중복 생성했다
코드 1500줄 돌파. 어제 “온보딩은 3턴 내에 끝내자”고 합의했는데, 오늘 AI가 7턴짜리 온보딩을 만들어 놨더라고요.
근데 더 심각한 건 DB였어요. 온보딩 데이터를 저장하는 테이블이 이미 있는데, 컨텍스트가 초기화되니까 AI가 새 JSON을 또 만들어버린 거죠. 경쟁사 분석 결과를 기존 프로젝트 테이블에 연결해야 하는데, AI는 그걸 모르니까 별도 테이블을 하나 더 만들고. 일주일도 안 돼서 DB가 파편화됐어요 — 어디에 뭐가 있는지 저도 모르겠더라고요.
그래서 PRD.md와 함께 DATA_SCHEMA.md를 만들었습니다. 프로젝트/문서/리포트/증거/점수/구독 — 모든 데이터 모델을 한 곳에 정의해놓고, AI에게 “DATA_SCHEMA.md 읽고 기존 테이블에 연결해”라고 지시하는 방식으로 바꿨죠.
AI가 존재하지 않는 회사를 만들어냈다
경쟁사 분석 기능을 넣었는데, AI가 “OO테크”라는 회사를 경쟁사로 제시하더라고요. 검색해보니 존재하지 않는 회사. 전형적인 할루시네이션이죠. 그래서 AI_SPEC.md에 Evidence 정책을 넣었어요. “출처 링크 없이 경쟁사 확정 금지.”
v3 피벗 — 문서가 꼬이기 시작한 순간
제가 직접 “갈아엎자”고 했어요. 이유는 단순했죠. 정작 가장 중요한 청년들은 아이디어가 있는지 없는지도 모르는 사람이 대다수거든요. 기존 v2는 “아이디어가 있는 사람”만을 위한 도구였고.
피벗하고 나니까 기존 문서 절반이 쓸모없어졌어요. 근데 삭제하면 안 되더라고요. AI가 “왜 바꿨는지”를 모르면 v2 스펙으로 돌아가니까. 그래서 v3_변경사항.md를 만들고, index.md에 정본 선언을 도입했습니다. “문서와 코드가 충돌하면 문서를 먼저 수정한다.”
“한 곳 고치면 다른 곳이 깨진다”
이 시기가 제일 힘들었어요. 결제 로직을 수정했더니 온보딩이 깨지고, 온보딩을 고치면 대시보드가 이상해지고. 전문 개발자 파트너가 “회귀 방지 프로토콜을 문서화하자”고 했죠.
그래서 나온 게 QA_DEBUG_PLAYBOOK.md예요. “변경 전 영향 범위 선언”, “1 PR = 1 목적”, “스키마 변경은 타입/테스트를 먼저 업데이트” 같은 규칙을 정리했습니다.
UI 스펙과 코드 가이드가 뒤섞이다
“대시보드 사이드바 우선순위”가 ENGINEERING_GUIDE에, “에러 바운더리 규칙”이 LANDING.md에 들어가 있는 걸 발견했어요. 목적이 다른 문서가 섞이면 AI도 헷갈려하거든요. design/ 폴더를 만들고 UI 관련 13개 파일을 독립시켰습니다.
이 시스템, 만능 아닙니다
여기까지 읽으면 “문서 설계가 답이구나!” 싶을 수 있는데 — 솔직히 말하면 대가가 있어요. 비판적으로 따져봐야 할 것 3가지.
반론 1: 메타워크의 함정
“AI를 통제하기 위한 문서를 쓰는 데 드는 시간이, 직접 코딩하는 시간보다 길어지면 어떡하죠?”
솔직한 답변? 실제로 Day 9 피벗 때 문서 절반을 폐기했습니다. 그 시간이 아까웠느냐고 묻는다면 — 아까웠어요.
근데 문서 없이 피벗했으면 더 끔찍했을 거예요. 기존 스펙을 매번 프롬프트로 설명하면서 “이건 v2 방식이니까 하지 마”라고 500자씩 써야 했을 테니까. 문서가 있으니까 “v3_변경사항.md 읽고 수정해” — 한 줄로 끝났죠.
문서 작성 시간이 아깝다고 느껴지면, 아직 프로젝트가 충분히 복잡하지 않은 겁니다. 코드 1000줄 이하면 CLAUDE.md 하나면 됩니다.
반론 2: 토큰 비용 증가
“매번 문서를 읽히면 API 토큰을 엄청 쓰는 거 아닌가요?”
맞아요. 31개를 한 번에 읽히면 토큰 폭탄입니다. 실제로 그렇게 하면 안 돼요.
그래서 분리한 거예요. “BILLING.md만 읽고 결제 로직 수정해”, “QA_DEBUG_PLAYBOOK.md 읽고 이 PR 검토해” — 이렇게 작업에 필요한 문서만 지정하는 거죠. 31개를 쪼갠 이유가 정리를 위해서가 아니라 비용 최적화 때문이었어요.
2주간 총 API 비용 ~$10. 외주를 맡기면 5,900만 원짜리 프로젝트였는데. 문서를 잘게 나눠서 필요한 것만 읽힌 덕분이죠.
반론 3: 모든 프로젝트에 필요한가?
“사이드 프로젝트에 문서 31개? 오버엔지니어링 아닌가요?”
맞는 말이에요. 1주일 안에 끝나는 프로젝트라면 CLAUDE.md 하나면 충분해요. 토이 프로젝트에 QA_DEBUG_PLAYBOOK을 만드는 건 시간 낭비죠.
31개가 필요해진 건 이런 조건이 겹쳤기 때문입니다.
| 조건 | 우리 프로젝트 | 문서 추가 시점 |
|---|---|---|
| 코드 1000줄 돌파 | Day 4 | L2 시작 (PRD, DATA_SCHEMA) |
| 할루시네이션 발생 | Day 7 | AI_SPEC에 Evidence 정책 추가 |
| 피벗 (방향 전환) | Day 9 | index.md 정본 선언 도입 |
| 회귀 버그 반복 | Day 10 | QA_DEBUG_PLAYBOOK 생성 |
| UI/코드 문서 혼선 | Day 12 | design/ 폴더 분리 |
반론 4: 문서로도 못 막는 것 — DB 파편화
“DATA_SCHEMA.md를 만들었는데도 DB 통합은 결국 못 했습니다.”
MVP 초반에 AI가 만들어놓은 중복 테이블과 JSON들 — DATA_SCHEMA.md를 도입한 이후로 새로운 중복은 막았지만, 이미 파편화된 기존 데이터를 통합하는 건 별개의 문제였거든요. 테이블 간 참조 관계가 꼬여 있고, 어디까지가 v2 잔재이고 어디부터가 v3인지 구분이 안 됐어요.
솔직히 이건 문서의 한계가 아니라 초기 설계의 문제였죠. DB 스키마를 처음부터 문서화했으면 파편화 자체가 안 생겼을 텐데, “MVP니까 일단 돌아가면 됐지” 하고 넘어간 게 화근이었어요. 나중에 정리하려고 하면 이미 코드 곳곳에서 그 중복 테이블을 참조하고 있어서 건드리기가 무섭더라고요.
DB 스키마만큼은 Day 1부터 문서화해야 합니다. 다른 문서는 “터질 때 만들어도 되지만”, DATA_SCHEMA.md는 예외예요. 한번 꼬인 DB는 문서를 아무리 잘 써도 되돌리기 어렵거든요.
교훈 3가지
AI는 시스템 위에서만 똑똑한 도구입니다
바이브코딩을 하다 보면 “AI가 멍청해졌다”고 느끼는 순간이 옵니다. 근데 멍청해진 게 아니에요. 기억을 못 하는 거죠. 그리고 그건 AI의 잘못이 아니라, 기억할 수 있는 구조를 안 만들어준 우리 잘못이더라고요.
프롬프트를 깎는 장인에서, 문서를 설계하는 아키텍트로. 그 전환이 바이브코딩의 진짜 레벨업이었습니다.
이 문서 시스템으로 실제로 MVP를 만든 이야기가 궁금하다면
바이브코딩으로 13일 만에 MVP 만든 과정 →
