바이브코딩을 오해하기 쉬운 지점이 있다. AI에게 “만들어 줘”라고 던지면 알아서 서비스가 나온다고 생각하는 순간, 결과물의 완성도는 급격히 떨어진다. 진짜 바이브코딩은 코드를 찍어내는 단계가 아니라, 코드를 찍어내기 직전까지의 기획 과정에 있다. 코딩 자체는 프린터 출력에 가깝다. 인쇄할 문서를 얼마나 제대로 만들어 두었느냐가 품질을 결정한다
기획은 사전 준비가 아니라 개발의 시작점이다
기획을 “코딩 전에 잠깐 하는 일”로 분류하면 안 된다. 서비스에 어떤 기능을 넣을지, 그 기능이 어떤 흐름으로 동작할지 결정하는 작업은 개발의 본 게임이다. 그리고 이 회의의 최종 결과물은 언제나 하나로 수렴한다. 바로 프롬프트다
잘 만든 프롬프트 하나가 수천 줄의 코드를 결정한다. 반대로 흐린 프롬프트는 수정의 수정을 반복하게 만든다. 그래서 설계 단계는 짧게 끝낼 일이 아니다. 개인 프로젝트 기준으로 2주 정도는 설계에만 매달리는 것이 오히려 정상이다
맨땅에서 출발하지 말고 이상형 URL부터 정한다
웹 디자인에 능숙하거나 서비스 기획 경력이 길지 않은 이상, 처음부터 모든 것을 직접 설계하는 것은 비효율적이다. 이럴 때 가장 빠른 길은 “이상형에 가까운 서비스의 URL”을 먼저 정하는 것이다
출발 순서는 다음과 같다
1) 내가 원하는 결과물의 이상형을 먼저 정의한다 2) 그 이상형에 근접한 서비스의 URL을 확보한다 3) URL을 Claude Desktop에 붙여 기능과 UI/UX를 분석시킨다 4) 분석 결과를 기반으로 프롬프트 초안을 받는다
직접 사이트를 뒤지며 분석할 필요는 없다. Claude Desktop에 URL을 전달하면서 “바이브코딩으로 웹서비스를 만들고 싶은데, 이 URL을 분석해서 프롬프트 작성을 도와달라”고 요청하면 된다. 결과물은 기능 요구사항과 UI 구성을 정리한 마크다운 파일로 나온다
UI/UX에서 반드시 확보해야 하는 두 가지
분석 결과에서 꼭 챙겨야 하는 정보는 두 가지다. 컬러 팔레트와 컴포넌트다
컬러 팔레트는 한 번 정하고 끝내지 않는다. 초기에는 알록달록한 조합이 괜찮아 보여도, 개발이 진행되면서 모노톤으로 바꾸고 싶어질 수 있다. 그래서 프롬프트에는 “테마 변경이 손쉽게 가능하도록 구조를 잡아 달라”는 요구를 반드시 포함해야 한다
컴포넌트는 더 중요하다. 버튼, 셀렉트박스, 카드, 모달 같은 기본 UI 요소의 모양과 동작을 먼저 정의해 두면 이후 전체 화면을 만들 때 일관성이 유지된다. 프롬프트에 “UI는 컴포넌트로 분리해서 구현해 달라”는 항목을 빠뜨리지 않아야 한다
글꼴도 같이 챙긴다. UX에 미치는 영향이 크고, 유료 글꼴을 잘못 사용하면 저작권 문제가 발생한다. 무료로 사용 가능한 범위를 명시적으로 지정하는 것이 안전하다
| 항목 | 확보해야 하는 이유 | 프롬프트에 포함할 요구 |
|---|---|---|
| 컬러 팔레트 | 테마 변경 가능성 대비 | 스킨 교체가 쉬운 구조로 분리 |
| 컴포넌트 | 일관된 UI, 재사용성 | 버튼·셀렉트·카드 단위로 구현 |
| 글꼴 | 저작권 리스크, UX 영향 | 무료 사용 가능한 글꼴만 사용 |
컴포넌트 테스트 페이지를 먼저 만든다
본격적인 화면을 만들기 전에 컴포넌트가 한눈에 보이는 테스트 페이지부터 생성해야 한다. 이 페이지에서 색상, 둥글기, 간격, 상태별 스타일을 확인한 뒤에 본 화면에 적용하면, 전체 화면을 뒤엎는 일을 피할 수 있다
테스트 페이지는 일종의 디자인 확인용 진열대다. 개발을 진행하다가 컬러 톤이나 컴포넌트 형태가 마음에 들지 않을 때 이 페이지만 수정하면 전체에 반영된다
Claude Desktop은 시니어, Claude Code는 주니어다
설계와 구현에 사용하는 도구는 역할을 분리해야 한다
Claude Desktop → 시니어 개발자 / 설계·의사결정·회의록 담당 Claude Code → 주니어 개발자 / 지시받은 코드 생성 담당 사용자 본인 → 주니어 코더 / 지시와 검증을 함께 수행
Claude Desktop을 설계용으로 사용해야 하는 이유는 명확하다. GUI 기반이라 이미지 첨부가 쉽고, 대화 기록이 자동으로 보관된다. 설계 회의는 흔적이 남아야 한다. 중간에 내용을 잊어도 다시 찾아볼 수 있어야 하고, 팀원 또는 다른 세션의 AI에게 인수인계도 가능해야 한다
Claude Code는 CLI 기반이라 설계용으로는 불편하다. 이미지 처리가 매끄럽지 않고, 지난 대화를 되짚기가 어렵다. 세션 관리에 실패하면 프리징도 발생한다. 그래서 Claude Code의 역할은 “설계 과정에서 정리된 프롬프트를 받아 코드로 찍어내는 것”에 한정하는 것이 안전하다
주의할 점은 본인의 역할 위치다. 시니어가 설계하고 주니어가 구현하는 구조에서, 설계의 핵심 방향이 AI 쪽에 넘어간다면 자신의 역할은 시니어라기보다는 주니어 또는 코더에 가까워진다. 그래도 문제가 되지 않는다. 좋은 질문을 던지고, 결과물을 검증하고, 필요한 요구사항을 집어넣는 것이 본인의 실제 가치다
설계 단계에서 반드시 생성해야 하는 문서 4종
설계가 끝나는 시점에 만들어 두어야 하는 문서는 다음 네 가지다
1) PRD (Product Requirements Document) - 기능 요구사항, 기술 스택, 코딩 컨벤션 포함 2) 로드맵 - 구현 단계를 1, 2, 3, 4 단위로 분할 - 형상관리(커밋 단위)의 기초가 됨 3) CLAUDE.md에 넣을 내용 - 세션이 바뀌어도 유지되는 핵심 규칙 - 토큰 사용량을 고려해 컴팩트하게 유지 4) DB 스키마 생성 스크립트 - SQL 스크립트 형태로만 생성 - 스키마명은 반드시 영문 소문자 - 현재 스키마(current schema) 지정을 CLAUDE.md에 명시
PRD는 기능적 요구사항을 상세하게 적을수록 완성도가 올라간다. 단순히 “로그인 기능” 수준이 아니라, 인증 방식, 세션 유지 정책, 실패 시 처리까지 구체적으로 기술하는 편이 좋다
로드맵은 개발 순서를 결정하는 문서이자 커밋 단위를 나누는 기준이다. 이후 형상관리와 배포 절차에 직결된다
CLAUDE.md는 세션이 바뀌어도 유지되는 규칙이 들어간다. 매 세션마다 반복 전달되므로 불필요한 내용이 많으면 토큰을 잠식한다. 꼭 필요한 규칙만 최소한으로 적는다
최초 프롬프트에 포함해야 할 고정 항목
최초 프롬프트에는 프로젝트 전반을 지배하는 규칙이 모두 들어가야 한다
- 기술 스택: 프론트엔드/백엔드/DB/런타임 버전 - 코딩 컨벤션: 카멜 표기법, 변수명 규칙, 파일 구조 - 언어 규칙: "한국어로 답하라" - 기능 요구사항: 상세할수록 좋음 - 구현 절차: 단계 분할 (커밋 단위의 기초) - UI 규칙: 컴포넌트 단위 구현, 테마 교체 가능 구조 - 저작권: 무료 글꼴·라이브러리만 사용
프롬프트는 마크다운 파일로 저장한다. Claude Code를 포함한 대부분의 AI 도구는 마크다운 인식률이 가장 높다. 프로젝트 폴더 안에 별도의 DOC 디렉터리를 두고, 여기에 PRD, 로드맵, 회의록, 분석 문서, CLAUDE.md 초안을 모두 넣어 두는 것을 권장한다. 이 문서들이 곧 프로젝트의 인수인계 자산이다
DB 스키마는 스크립트로만 생성한다
데이터베이스 설계에서 한 가지 원칙만 지키면 대형 사고를 피할 수 있다. Claude Code가 DB 서버에 직접 연결해 작업하지 못하게 하는 것이다
❌ 위험한 방식: Claude Code에 DB 접속 정보를 주고 직접 실행시키기 ✅ 안전한 방식: SQL 스크립트만 생성받아 사람이 확인하고 실행
DB는 한 번 잘못 건드리면 되돌리기 어렵다. 반드시 SQL 스크립트 파일만 생성하도록 요청하고, 스키마명을 포함한 생성 코드를 직접 확인한 뒤 실행한다. PostgreSQL을 사용한다면 스키마명은 영문 소문자로 통일하고, current_schema를 CLAUDE.md에 명시해 둔다. 그래야 테이블이 의도한 위치에 만들어진다
스크립트가 길어질 경우 단계별로 나눠 달라고 요청한다. 스텝 1, 2, 3, 4로 구분된 스크립트가 나오면 하나씩 끊어서 실행하고 결과를 검증한다. 에러가 발생하면 해당 단계만 되돌리면 된다
AI는 불평 없는 동료다
설계 회의를 오래 하다 보면 특이한 경험을 하게 된다. AI는 잠을 자지 않고, 질문이 많다고 불평하지도 않는다. 내가 모르는 영역에 대해 “너무 복잡하니 혼자 하기 어렵다”고 솔직한 피드백을 주기도 한다
이 과정에서 가장 중요한 태도는 질문이다
- AI에게 추천을 받을 때는 반드시 “왜 그것을 추천했는지” 근거를 묻는다
- 하나의 AI 답변을 다른 모델로 교차 검증한다
- 창피함 없이 기본 개념부터 설명을 요청한다
이 과정 자체가 학습이다.오래된 경력이 있어도, 내가 실무로 경험하지 않은 분야라면 모호한 지식으로 잘못된 설계를 할 수 있다. AI와의 설계 회의는 모호했던 지식을 명확한 이해로 바꿔 주는 학습 과정이다
중요한 대화는 반드시 문서로 남긴다. 특히 왜 이 기술을 선택했는지, 왜 이 구조로 설계했는지에 대한 근거는 워드 문서 같은 형태로 따로 보관해 두는 것이 좋다. 이 문서들은 훗날 AI가 만들어 낸 코드를 내가 이해하지 못하는 “기술 부채” 상황이 왔을 때, 나 자신을 구하는 자료가 된다
정리
정리하면, 바이브코딩의 무게 중심은 코드 생성이 아니라 기획에 있다. Claude Desktop으로 설계와 학습을 끝내고, PRD·로드맵·CLAUDE.md·DB 스크립트 4종 문서를 완성한 뒤에야 Claude Code에게 구현을 맡긴다. 이 순서를 지키면 바이브코딩은 “AI에게 떠맡기는 자동화”가 아니라 “AI와 함께 성장하는 학습 프로세스”로 바뀐다