소개
바이브 코딩은 빠르고 직관적이지만, 동시에 수정이 어렵고 유지보수가 힘들다는 평가가 많습니다. 그래서 저는 기존의 개발 방식처럼 요건 정의와 문서 작업을 매우 타이트하게 작성하면서 바이브 코딩을 하면 오류도 적고, 유지 보수까지도 가능한 바이브 코딩을 할 수 있지 않을까라는 가설을 테스트하기 위한 실험을 진행했습니다.
개발 생산성의 극대화라는 목표 는 같지만, 얼마나 문서를 준비해야 진짜 도움이 되는가에 대해 스스로 질문하며 시작한 여정이었습니다.
진행 방법
이번 실험에서 저는 다음과 같은 방식으로 문서를 정리하고 사용했습니다:
개발을 위해 필요한 문서의 종류를 llm에게 묻고 다음과 같은 문서가 필요하다는 결론을 냈습니다.
1. Product Requirements Document
2. Technical Architecture Document (TAD)
3. Database Schema Document (DSD)
4. API Specification Document
5. UI Component Library Document
6. User Flow & Wireframes Document
아주 상세하게 작성하려고 노력했고, 초기 작업물부터 버전 관리를 한 내용이 대략 정도가 되었습니다.
그래서 최종 개발을 위해 작성된 문서는 이 정도로 압축이 되었습니다.
하다가도 이건 정말 아닌가 싶은데도 이번에 한계치를 확인해야지 다음 번의 작업을 워크플로우를 개선해서 훨씬 더 효율적으로 할 수 있을거라는 믿음 아래, 빠지는 내용이 없게끔 열심히 준비해봤습니다.
그리고 아주 재미있었던 부분은 각각의 문서가 약 2만자~6만자 정도 되는 엄청난 분량이라서 아무리 llm이라도 이 정도 문서를 동시에 처리할 수 있을까라는 생각을 했는데 문서를 다 집어넣은 뒤
"서로 맞지 않는 부분, 정합성을 완벽하게 체크해. ultra deep thinking해. 너라면 할 수 있어!" 이런 프롬프트를 넣은 뒤에 결과를 봤는데 아주 작은 것의 하나를 잡아서 다른 서류와 맞지 않는걸 정확하게 찾아낸건 정말 놀라움 그 자체였습니다.
6만자 짜리 prd 문서에서 딱 이거 한 줄 밖에 없었습니다. 다른 어떠한 이 부분에 대해서 보충하거나 설명하는 글도 없고 딱 이 한 줄 뿐인데, api문서에서 대시보드 실시간 호출 기능이 없는데 prd에는 저거 한 줄이 있어서 정합성이 안맞는다고 이걸 수정하겠다고 하는 부분에서는 정말 놀라서 뒤집어 지는 줄 알았습니다ㅋㅋ
하지만 슬프게도, 이런 과정들을 거쳐서 모든 문서를 완벽하게 맞추고 나서 실제 개발에 들어갔는데 정작 개발을 할 때는 이 수많은 맥락을 참조도 다 못하고 결국에 자기가 또 지어내서 스키마 컬럼 이름 바꾸고 타입 바꾸고 이 런 만행을 저지르기 시작합니다.
그래서 제가 느낀 점은 서류 작업을 이렇게 까지 하는 건 오히려 낭비를 초래한다 이런 생각을 했습니다. 하지만 어떠한 오류가 발생했을 때,
"방금 이 오류를 원본 문서와 비교해봐"라고 프롬프트를 입력하면 아주 상당히 잘 맞추고 이거 땜에 문제가 있었구나 이런 적이 꽤 많습니다. 그래서 현재 저의 생각은 어차피 오류가 발생했을 때, 정확한 맥락을 주고 오류 수정을 시킨다면 방향성만 정확하다면 llm의 연산력으로 어떻게든 잡아내는 경우가 많은데 이걸 미리 부터 문서를 다 준비하고 들어가는 거 보다 개발 스피드를 올리고 빠르게 오류를 잡아내는 방법론이 훨씬 더 효율적이지 않 을까 라는 생각을 해봤습니다.
그래도 꼭 준비하면 좋은 부분은, 문제가 생겼을 때 바로 프로젝트를 폐기 시킬 수도 있고, 수정하려고 덤벼들어도 손도 못대고 그냥 새로 프로젝트를 시작하게 만드는 원흉! db 스키마와 api 호출은 이렇게 미리 셋팅하고 들어갔던 것은 아주 큰 도움이 되었습니다.
DB 스키마 명확화
initial_schema.sql,seed.sql파일을 프로젝트 초기에 작성Claude와 같은 AI가 이후 코드를 생성할 때 기준으로 삼을 수 있게 명확히 정의
실제로 코드 작성 중 혼란이 생기면 이 문서로 돌아와 참조
API 명세 및 테스트 파일 사전 작성
API 요청/응답 구조를 정리한 명세 문서 작성
테스트용 요청 파일(JSON, Curl 등)을 미리 구성해두어 반복적으로 검증
덕분에 API 설계 변경 없이 일관된 호출 가능
이렇게 미리 셋팅을 하고 들어가면 프로젝트가 통째로 날라갈 위험은 아주 상당히 줄어들 수 있을 거라고 생각합니다.
결과와 배운 점
이 실험은 명확한 교훈을 남겼습니다:
“모든 걸 다 문서화할 필요는 없다.”
시간이 많이 들었지만 반복적이고 불필요한 작업도 많았음
바이브 코딩 자체가 워낙 수정이 빠르기 때문에, 문서가 과하면 발목을 잡기도 함
“명확히 정리해야 할 것만 하자.”
DB 스키마와 API 명세는 꼭 필요하고 효과가 큼
이 두 가지가 틀어지면 프로젝트 전체가 흔들림
“바이브 코딩의 장점을 살리는 게 핵심이다.”
오류는 자주 나지만 오류 수정도 빠르다
이 장점을 극대화하려면 문서는 최소화하고, 핵심 구조만 명확히 하자
다음 프로덕트는 기존 레거시 제품들과 완전히 다른 구조, 다른 개발 방법론으로 바로 돈을 벌 수 있는 프로덕트를 만들자!