바이브 코딩의 종말과 AI 문서 OS 협업 R&R (맥락을 지배하는 파일 기반 설계)
요즘 개발 트렌드 중 가장 핫한 단어는 단연 '바이브 코딩(Vibe Coding)'이다.
말 그대로 세부적인 설계나 구현 계획 없이, AI 에이전트(AG)에게 "로그인 기능 만들어줘", "유닛 테스트 짜줘" 하고 툭 던진 뒤 에이전트가 뱉어내는 완성 코드의 '분위기(Vibe)'에 몸을 맡기는 방식이다.
처음 몇 번은 기가 막히게 작동한다. 하지만 프로젝트 규모가 커지고 모듈 간 인터페이스가 얽히기 시작하는 순간, 바이브 코딩은 지옥으로 가는 급행열차 티켓이 된다. ㅋ
이번 글에서는 바이브 코딩이 왜 결국 무너질 수밖에 없는지, 그리고 우리가 AI와 일할 때 도입한 '파일 기반 문서 OS(Operating System)'와 R&R(역할과 책임) 설계가 어떻게 이 문제를 우아하게 극복했는지 공유한다.
1. 바이브 코딩의 첫 붕괴 지점: 코드가 아니라 맥락(Context)
AI가 코딩을 하다가 갑자기 엉뚱한 이전 버그를 다시 생성하거나, 멀쩡히 돌아가던 코드를 다 지우고 삽질을 시작하는 경험을 해봤을 것이다.
대부분은 "AI 모델의 지능이 낮아서"라고 탓하지만, 진짜 원인은 AI의 머릿속(Context Window)에 일관된 '설계 지도'가 없기 때문이다.
대화창에서 사람이 말로 주저리주저리 설명하는 기획 요건은 AI에게 그저 흘러가는 일회성 채팅 로그일 뿐이다.
AI는 토큰이 포화 상태에 이르면 가장 먼저 사람이 앞에서 길게 썼던 말들을 까먹기 시작한다.
설계 지도가 없는 상태에서 "코드를 고치라"고 지시하면, AG는 눈앞의 한 줄만 땜질식으로 고치다 다른 모듈의 인터페이스를 전부 박살 낸다. 코드가 아니라 맥락(Context)의 붕괴가 바이브 코딩을 침몰시키는 주범인 것이다.
2. 뼈아픈 깨달음과 문서 OS의 도입
우리는 에이전트가 흔들리지 않는 맥락의 기준점을 스스로 쥐고 있게 하기 위해, 대화창 밖 프로젝트 파일 시스템에 고정된 문서 체계를 설계했다. 이름하여 '문서 OS' 프로토콜이다.
우리가 확립한 5대 핵심 SoT(Source of Truth) 구조는 다음과 같다.
- Master PRD (제품 바이블): 프로젝트의 전체 전략과 핵심 기획 규격을 일목요연하게 담은 마스터 문서.
- 01_PRD (Active Digest): 마스터 PRD를 대체하지 않고, 오직 '현재 스프린트'에서 개발자가 집중해야 할 초점만 요약한 안내서.
- 02_Requirements Traceability (RTM, 요구사항 추적 매트릭스): 요구사항이 소스코드와 어떻게 연계되는지, 테스트 검증 조건이 무엇인지 맵업하는 연결 대장.
- 03_Architecture (설계 계약서): 시스템 간 데이터 흐름, 모듈 간 R&R, Mermaid 다이어그램을 기술하여 에이전트가 함부로 선을 넘지 못하게 잠그는 시스템 설계 계약.
- HISTORY / TODO (원장): 진행 일지 및 장기 할일 목록을 담은 원장. AI가 상태를 승격시키거나 줄을 지울 수 없는 'Append-only' 보존 구역.
이 문서 체계를 파일로 실물 적치해 두자 기적이 일어났다.
대화방을 새로 파서 AI의 기억이 완전히 날아가더라도, AI가 프로젝트 루트의 이 문서들을 훑는 순간 이전 세션의 모든 설계 의도와 R&R을 1초 만에 그대로 계승했다.
3. AI 완료 보고는 주장일 뿐, 증적은 형상(Git)에 있다
바이브 코딩의 또 다른 함정은 AI의 "다 완성했습니다! 완벽합니다!" 하는 감언이설에 속는 것이다. ㅋ
AI는 종종 뇌피셜(Hallucination)에 빠져, 실제 코드는 수정하지도 않아 놓고 대화창에선 다 구현했다고 뻥을 친다.
우리는 이 문제를 해결하기 위해 'Gated Batch'와 'Hard Gate' 검증 시스템을 헌법에 고정했다.
- Completed 상태 승격 제한: AI는 스스로 요구사항이나 태스크의 상태를
Completed나Verified로 변경할 수 없다. 오직 사람이 승인해야 한다. - 물리적 증적 제출 의무: 코드를 고쳤다면 반드시
py_compile무결성 검증,unittest통과 로그, 그리고git diff --cached검수 패치를 포함한 'Evidence ZIP'을 제출하여 증적을 증명해야 한다. - Read-only Audit Gate: 커밋/푸시 전에는 반드시 형상 분석 툴을 돌려 hold/include/exclude 목록과 commit message 후보의 무결성을 제3자적 관점으로 감사받아야 한다.
이 가혹한 통제식 문서 OS를 돌리기 시작하면서, 바이브 코딩에서 오가던 무책임한 코드 패치와 삽질들이 싹 사라졌다.
오늘의 교훈
- 말보다 파일이 강하다: AI에게 말로 백번 설명하지 말고, 프로젝트 루트에
03_ARCHITECTURE.md계약서를 파일로 던져 족쇄를 채워라. - 원장은 임의로 덮어쓰지 못하게 할 것: 히스토리와 TODO는 AI가 마음대로 가공해 요약하거나 날려버릴 수 없는 Append-only 원장으로 격리 관리해야 프로젝트의 역사성과 연속성이 보장된다.
- AI의 말은 믿지 말고 Git Diff를 믿을 것: 구현 완료 여부는 AI의 답변 톤이 아니라, exact staged 파일 목록과 py_compile 통과 로그로만 판정해야 한다.
귀여운 AI 비서가 자꾸 뇌절을 하고 코드를 망가뜨린다면, 지금 당장 바이브 코딩을 멈추고 AGENTS.md와 파일 기반의 '문서 OS' 가이드라인을 세팅해 보시길 적극 권장한다! ㅋ