바이브코딩은 틀렸다: 클로드에게 코드를 짜기 전에 반드시 해야 할 3단계

프롬프트를 치고, 에러가 나면 고치고, 또 프롬프트를 치고... 대부분의 사람이 AI 코딩 도구를 이렇게 쓴다. 하지만 작업이 조금만 복잡해지면 결과물이 통째로 무너진다. 이 글에서는 바이브코딩의 함정을 짚고, 코드 한 줄 짜기 전에 반드시 거쳐야 할 3단계 워크플로우를 소개한다.

바이브코딩이 실패하는 진짜 이유

"AI한테 말만 하면 코드가 뚝딱 나온다"는 바이브코딩(Vibe Coding)의 매력적인 약속 뒤에는 치명적인 함정이 숨어 있다.

간단한 투두리스트 앱이라면? 잘 된다. 하지만 인증 시스템을 붙이고, 외부 API를 연동하고, 기존 데이터베이스 스키마와 맞춰야 하는 순간 — 결과물이 완전히 무너지기 시작한다.

이유는 단순하다. AI는 "무엇을 만들어야 하는지"에 대한 판단 없이, "어떻게 타이핑할지"만 최적화하기 때문이다. 기획 없는 코딩은 설계도 없는 건축과 같다. 아무리 빠르게 벽돌을 쌓아도, 어디에 쌓아야 하는지 모르면 무의미하다.

하나의 핵심 원칙

이 문제를 해결하는 원칙은 딱 하나뿐이다.

"기획과 코딩의 분리: 작성된 계획을 내가 직접 검토하고 승인하기 전까지는, 클로드에게 절대 코드를 짜게 하지 마라."

이 원칙을 지키면 세 가지가 달라진다.

삽질이 사라진다 — 방향이 정해진 상태에서 코드를 짜므로, "이거 아닌데..." 하며 되돌리는 시간이 제로에 수렴한다
아키텍처 주도권을 개발자가 쥔다 — 기술 선택, 설계 방향, 기능 범위를 AI가 아닌 인간이 결정한다
토큰은 줄고, 품질은 올라간다 — 같은 비용으로 더 나은 결과물을 얻는다

1단계: 코드 리서치 (Deep Research)

모든 의미 있는 작업은 기존 코드베이스를 깊이 읽고 파악하는 것에서 시작한다. 이 단계를 건너뛰는 것이 대부분의 AI 코딩 실패의 근본 원인이다.

실행 방법

클로드에게 관련 폴더나 파일을 철저하게 읽고 이해한 뒤, 반드시 별도의 마크다운 파일(리서치.md)로 상세 보고서를 작성하게 한다.

프롬프트 예시:

"src/auth/ 폴더와 database/models/ 폴더를 깊이 읽고,
 매우 상세하게 모든 세부 사항을 파악해라.

 특히 다음을 분석해서 research.md에 보고서로 작성해:
 - 현재 인증 흐름 (토큰 발급 → 검증 → 만료 처리)
 - DB 스키마와 모델 간 관계 (FK 참조, 인덱스)
 - 기존 미들웨어 체인과 에러 핸들링 방식
 - 사용 중인 외부 라이브러리와 그 선택 이유"

프롬프트의 핵심 키워드

"깊이 읽고", "매우 상세히", "모든 세부 사항을 파악해라" — 이 단어들을 반드시 포함해야 한다. 왜?

이 키워드들이 없으면 AI는 사람과 똑같이 행동한다. 파일 하나만 대충 훑어보고 "이해했습니다"라고 말하며 넘어가 버린다. 깊이를 명시적으로 요구해야 진짜 리서치가 시작된다.

절대 금지 사항

채팅창 안에서 구두로 요약받고 끝내면 안 된다. 반드시 문서 파일로 남겨야 한다.

이유는 세 가지다.

채팅 컨텍스트는 휘발된다 — 세션이 길어지면 초반 대화 내용이 압축되거나 밀려난다
검증이 불가능하다 — 채팅 요약은 AI가 맞든 틀리든 확인할 방법이 없다
재사용이 안 된다 — 다음 단계로 넘어갈 때 "아까 뭐라고 했지?" 하며 다시 물어봐야 한다

왜 이 단계가 필수적인가

AI 코딩에서 가장 치명적인 실패는 단순한 문법 에러가 아니다. 코드는 멀쩡하게 돌아가지만, 기존 레이어를 무시하거나, ORM 관리를 망치거나, 이미 존재하는 API를 중복으로 또 만드는 — "주변 시스템을 슬금슬금 망가뜨리는 구현"이 가장 위험하다.

❌ AI가 리서치 없이 만든 코드의 전형적 참사:

1. 이미 utils/auth.ts에 토큰 검증 함수가 있는데
   → 새로운 검증 함수를 처음부터 작성 (중복)

2. Prisma ORM으로 관리되는 스키마인데
   → raw SQL로 직접 테이블을 만들어버림 (ORM 우회)

3. 전역 에러 핸들러가 있는데
   → 각 라우트에 try-catch를 일일이 추가 (패턴 파괴)

철저한 문서 기반 리서치는 이 모든 대참사를 사전에 차단한다.

2단계: 계획 수립 및 검토 (Plan & Review)

이 단계가 전체 워크플로우의 심장이다. 여기서 시간을 투자한 만큼, 3단계에서 되돌리는 시간이 줄어든다.

마크다운 파일로 계획 작성

클로드에게 별도의 마크다운 파일(플랜.md)에 상세 구현 계획을 작성하라고 지시한다.

프롬프트 예시:

"research.md를 참고하여, 소셜 로그인 기능 추가에 대한
 상세 구현 계획을 plan.md에 작성해라.

 포함할 내용:
 - 접근 방식 (왜 이 방식을 선택했는지)
 - 변경/생성할 파일 목록과 각 파일의 변경 내용
 - 수정될 코드 스니펫 (before/after)
 - 트레이드오프 (장단점 분석)
 - 예상되는 엣지 케이스

 ⚠️ 아직 구현하지 마. 계획 문서만 작성해."

왜 내장 모드가 아니라 MD 파일인가?

에디터의 Plan 모드나 채팅 내 구조화 기능 대신 별도 마크다운 파일을 고집하는 이유가 있다.

비교	채팅/내장 모드	마크다운 파일 (plan.md)
편집	채팅에서 다시 요청해야 함	에디터에서 직접 수정
메모/주석	불가능	원하는 곳에 인라인 추가
영구성	세션 종료 시 날아감	프로젝트에 영구 보존
버전 관리	불가능	Git으로 이력 추적
팀 공유	불가능	파일 공유로 즉시 협업

채팅창에 흘러가는 텍스트와 프로젝트에 남는 산출물은 차원이 다르다.

검토 및 피드백 루프 (1~6회 반복)

이 루프에서 개발자의 설계자(Architect) 역할이 100% 발휘된다.

피드백 루프의 흐름:

1. 클로드가 plan.md를 작성
   ↓
2. 에디터에서 열어 검토
   ↓
3. 잘못된 가정, 비즈니스 제약, 도메인 지식을
   문서의 '정확한 위치'에 인라인 메모로 추가
   ↓
4. 클로드에게 다시 보냄
   ↓
5. (반복) 계획이 완벽해질 때까지 1~6회 반복

인라인 메모 예시:

### 3. OAuth 토큰 저장

Redis에 세션 토큰을 캐싱합니다.

<!-- 메모: Redis는 이 프로젝트에서 사용하지 않음.
     기존 PostgreSQL sessions 테이블을 활용할 것.
     이 부분 전면 재작성 필요. -->

### 4. 콜백 URL 처리

새로운 /api/auth/callback 엔드포인트를 생성합니다.

<!-- 메모: 이미 /api/oauth/callback이 있음.
     research.md의 기존 라우트 분석 참고.
     새로 만들지 말고 기존 것을 확장할 것. -->

절대 빠뜨리면 안 되는 한 문장

피드백을 보낼 때 반드시 이 문장을 포함해야 한다.

"메모를 반영해서 문서를 업데이트해. 아직 구현하지 마."

이 말을 빼먹으면? AI는 "피드백을 반영한다 = 바로 코딩을 시작한다"고 해석해버린다. 그리고 반영되지 않은 계획으로 코드를 짜기 시작해서, 결국 처음부터 다시 해야 한다.

주도권을 절대 뺏기지 마라

이 루프의 핵심은 기술 선택, 기능 제외, 아키텍처 방향 등 중요한 판단을 전부 이 단계에서 끝내는 것이다. 이 패턴을 '공유된 가변 상태(Shared Mutable State) 패턴'이라 부른다. 에이전트 코딩에서 가장 실용적인 인간 주도 방법론이다.

AI는 도구이지, 의사결정자가 아니다. 설계의 주도권은 반드시 개발자에게 있어야 한다.

3단계: 구현 및 감독 (Implementation)

계획 문서가 완벽하게 다듬어졌다면, 드디어 코드를 작성할 시간이다. 이 단계에서 개발자의 역할이 극적으로 변한다.

표준 프롬프트

계획이 끝났으므로, 이제는 기계적으로 실행만 시키면 된다.

"plan.md에 작성된 계획대로 전부 구현해라.
 작업 완료 시 계획 문서에 ✅ 완료로 표시해라.
 끝날 때까지 멈추지 마라.
 코드 수정 후 반드시 타입 체크를 실행해라."

이 한 번의 프롬프트로 모든 구현이 시작된다. 방향 설정은 이미 끝났으므로, AI는 삽질 없이 계획서를 따라 코드를 찍어낸다.

역할의 전환: 설계자 → 감독자

2단계 (계획)	3단계 (구현)
설계자(Architect)	감독자(Supervisor)
아키텍처 결정	실행 상태 모니터링
기술 선택	코드 품질 확인
기능 범위 결정	디테일 수정 지시

코딩 자체는 계획대로 찍어내는 기계적이고 지루한 작업이 되며, 창의적인 판단은 이미 이전 단계에서 모두 끝났다.

피드백은 최소한으로

이 단계에서 프롬프트는 극적으로 짧아진다.

✅ 좋은 피드백 예시:
- "버튼 간격 2px 틀어짐"
- "설정 페이지 위치 메인 앱으로 옮겨"
- "에러 메시지 한국어로"
- (스크린샷 한 장 첨부)

❌ 나쁜 피드백 예시:
- "전체적으로 좀 더 깔끔하게 다시 만들어줘" (모호함)
- "이 기능 다른 방식으로 바꿔줘" (계획에 없는 변경)
- "좀 더 좋은 코드로 작성해" (기준 불명확)

프론트엔드나 디자인 이슈는 말로 설명하기보다 스크린샷 한 장을 첨부하는 것이 훨씬 빠르고 정확하다.

📝 요약 (치트시트)

단계	산출물	핵심 행동
1. 리서치	`research.md`	"깊이 읽고, 모든 세부사항을 파악해라" + 문서로 남기기
2. 계획	`plan.md`	인라인 메모로 검토 + "업데이트해. 아직 구현하지 마"
3. 구현	실제 코드	계획대로 실행 + 감독자 역할 + 짧은 피드백만

한 줄 요약: AI가 코드를 잘 쓰게 만드는 것이 비결이 아니다. 코드를 쓰기 전에 무엇을 써야 할지 확실하게 정해두는 것이 비결이다.