바이브코딩이 익숙해지면 자연스럽게 이런 패턴이 생겨요. AI에게 “만들어줘”라고 하면 만들어주고, 좀 이상하면 “수정해줘”라고 하고… 이렇게 즉흥적으로 작업하는 게 편하거든요. 그런데 Docs 드리븐 개발이라는 방식을 한 번 써보면 생각이 바뀌어요. AI와 함께할 때 문서를 먼저 쓰는 이유가 있어요.
Docs 드리븐 개발이란 무엇인가요
Docs 드리븐 개발(Documentation-Driven Development, DDD)은 코드를 작성하기 전에 무엇을 만들지 문서로 먼저 정리하는 방식이에요. 코드보다 문서가 먼저예요.
예를 들어 사용자 인증 기능을 만든다면, 코드를 짜기 전에 이런 내용을 문서로 먼저 써요.
- 어떤 인증 방식을 쓸 것인가 (이메일/비밀번호, 소셜 로그인 등)
- 어떤 엔드포인트가 필요한가 (POST /auth/login, POST /auth/register 등)
- 성공/실패 시 어떻게 응답하는가
- 토큰 관리는 어떻게 할 것인가
AI와 함께할 때 문서가 특히 중요한 이유
AI는 컨텍스트 없이 시작하면 나름대로 판단해서 만들어요. 처음에는 괜찮아 보여도 프로젝트가 커지면서 불일치가 생겨요. 인증 모듈은 JWT를 쓰고, 다른 모듈은 세션을 쓰고, 또 다른 데서는 다른 방식을 쓰는 식으로요.
문서를 먼저 만들면 AI에게 “이 문서를 기준으로 구현해줘”라고 할 수 있어요. AI가 매번 다른 판단을 하는 게 아니라 일관된 방향으로 작업해줘요. API가 어떻게 동작하는지를 이해하면, API 스펙을 문서로 먼저 정의하는 게 얼마나 중요한지 더 잘 보여요.
실전에서 쓰는 문서의 종류
README.md: 프로젝트 개요, 기술 스택, 로컬 실행 방법. AI에게 “이 프로젝트는 이런 거야”를 설명하는 첫 번째 문서예요.
SPEC.md 또는 PRD: 무엇을 만드는지, 어떤 기능이 있는지 정의해요. Cursor의 Rules for AI나 프로젝트 루트에 넣어두면 AI가 항상 참고해요.
API 스펙: 백엔드 API를 만든다면 엔드포인트, 요청/응답 형식을 먼저 정의해요. AI가 이 스펙을 기준으로 구현하면 프론트엔드-백엔드 간 불일치가 줄어요.
데이터 모델: 어떤 데이터를 어떻게 저장할지 먼저 정의해요. 데이터베이스 개념을 이해하면 이 과정이 훨씬 명확해져요.
문서 작성도 AI와 함께해요
문서를 직접 다 쓸 필요는 없어요. AI에게 이렇게 요청해보세요. “독서 기록 공유 앱을 만들려고 해. 기술 스택은 Next.js, Supabase야. 이 프로젝트의 기술 스펙 문서를 작성해줘. API 엔드포인트, 데이터 모델, 주요 컴포넌트 구조를 포함해줘.”
AI가 초안을 만들어주면 여러분이 검토하고 수정해요. 이 문서가 이후 모든 개발의 기준이 돼요.
문서가 있는 프로젝트는 다르게 진행돼요
문서 없이 즉흥적으로 만들면 처음엔 빨라 보여요. 하지만 어느 순간 “왜 이렇게 만들었지?”, “이게 어떻게 작동하는 거지?”를 스스로 물어보게 돼요. 문서가 있으면 AI에게 “이 문서를 보고 이 부분 업데이트해줘”라고 할 수 있어요. 프로젝트가 커질수록 문서의 가치가 빛을 발해요. 지금 만들고 있는 프로젝트가 있다면, 오늘 간단한 README라도 써보세요. 시작이 반이에요.
댓글 0