바이브코딩 실전 가이드: Claude Code 리서치-계획-구현 3단계

바이브코딩, 단순히 AI에게 코드를 시키는 게 아닙니다. Claude Code를 수개월간 주력으로 써온 개발자가 실제로 정착한 워크플로우는 대부분의 사람들과 꽤 다릅니다. 프롬프트 치고 에러 나면 고치고 반복하는 패턴, 작업이 조금이라도 복잡해지면 결과물이 무너지는 경험은 누구나 한 번쯤 겪어봤을 겁니다. 이 글에서는 리서치, 계획, 주석달기, 구현으로 이어지는 4단계 AI 코딩 워크플로우를 정리합니다.

바이브코딩이란 무엇인가

바이브코딩이라는 용어는 2025년 2월, Andrej Karpathy가 트위터에서 처음 제시한 개념입니다. 인간이 직관과 큰 그림을 담당하고 AI가 코드 작성을 맡는 협업 방식입니다. Anthropic이 개발한 터미널 기반 Claude Code는 이 워크플로우에 가장 잘 맞는 도구로 주목받고 있습니다. 구조화된 과정 없이 AI에게 바로 코드를 맡기면, 겉으로는 돌아가지만 주변 시스템을 조금씩 망가뜨리는 구현이 쌓입니다.

핵심 원칙: 기획과 코딩의 분리

수개월간 정착한 핵심 원칙은 하나입니다. "작성된 계획을 내가 직접 검토하고 승인하기 전까지 Claude에게 코드를 절대 쓰게 하지 마라." AI 코딩에서 가장 비싼 실패는 문법 에러가 아닙니다. 기존 레이어를 무시하는 함수, ORM 관리를 고려하지 않은 마이그레이션, 이미 있는 로직을 중복 구현한 API. 이런 것들이 쌓이면 아키텍처가 서서히 침식됩니다. 기획과 코딩을 분리하면 삽질이 사라지고 아키텍처 결정 주도권이 개발자 손에 남습니다.

1단계: 코드 리서치로 Claude가 전체를 파악하게 하라

모든 의미 있는 작업은 코드베이스를 깊이 읽는 것부터 시작합니다. Claude에게 관련 부분을 철저히 이해시키고, 발견한 내용을 반드시 research.md에 작성하게 합니다. 채팅창 구두 요약으로 끝내면 안 됩니다. 프롬프트는 이렇게 씁니다.

 

"이 폴더를 깊이 읽고 어떻게 동작하는지 깊이 이해하고 모든 세부사항을 파악해라. 끝나면 research.md에 상세 보고서를 작성해라."

'깊이', '매우 상세히', '세부사항' 같은 강조 단어가 생각보다 중요합니다. 이 단어 없이 시키면 Claude는 파일 하나 훑고 함수 시그니처 수준에서 넘어갑니다. 리서치 단계가 바로 무지한 구현을 막아줍니다.

2단계: 계획 작성, 내장 Plan Mode보다 직접 MD 파일이 낫다

리서치가 끝나면 plan.md에 상세 구현 계획을 작성하게 합니다. 접근 방식 설명, 코드 스니펫, 수정될 파일 경로, 트레이드오프까지 담겨야 합니다. Claude Code의 내장 Plan Mode 대신 별도 마크다운 파일을 쓰는 이유가 있습니다. 에디터에서 직접 편집할 수 있고, 원하는 위치에 인라인 메모를 달 수 있으며, 프로젝트 안에 실제 산출물로 남습니다. 세션이 날아가도 파일은 그대로입니다. 계획이 나오면 반드시 개발자가 직접 검토하고 승인해야 합니다.

3단계: 주석달기 사이클, 진짜 판단은 여기서 끝난다

전체 워크플로우의 핵심입니다. Claude가 plan.md를 작성하면 에디터에서 열고 문서 안에 직접 인라인 메모를 추가합니다. 잘못된 접근을 수정하거나 도메인 지식을 주입합니다. 실제 메모 예시를 보면, "아니, 이건 PUT 아니라 PATCH여야 해." "패런트가 재시도 처리하니까 이 재시도 로직은 중복이야. 제거해." 메모를 추가한 뒤 Claude에게 보낼 때는 이 문구가 필요합니다.

 

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

'아직 구현하지 마'를 빠뜨리면 Claude가 혼자 판단해서 바로 코드를 짜기 시작합니다. 이 사이클은 보통 1번에서 수번 반복되며 창의적인 판단은 모두 여기서 끝납니다.

4단계: 구현, 기계적으로 진행하라

계획이 준비되면 구현 명령을 내립니다. 표준 프롬프트: "전부 구현해라. 단계를 완료하면 계획 문서에서 표시해라. 모든 단계가 끝날 때까지 멈추지 마라. any나 unknown 타입을 쓰지 마라." 모든 결정이 내려진 상태라 구현은 기계적입니다. 창의적이지 않습니다. 의도한 겁니다. 잘못된 방향이면 git reset으로 되돌리고 범위를 재설정하는 게 점진적으로 패치하는 것보다 낫습니다.

운전대를 놓지 마라: 방향 통제 전략

바이브코딩에서 개발자의 역할은 실행을 맡기되 방향 결정권을 넘기지 않는 것입니다. 방향 조정은 plan.md 위에서 이루어집니다. 좋은 접근은 취합니다. "어싱크로 깔끔하게 가자." 불필요한 건 쳐냅니다. "다운로드 기능은 계획에서 빼." 선을 긋습니다. "이 세 함수의 시그니처는 절대 바꾸면 안 돼." 기술 선택은 항상 개발자가 합니다. "그 모델 말고 이 모델 써." 이 네 가지가 개발자가 쥐고 있어야 할 운전대입니다.

 

"Claude한테 코드를 잘 쓰게 만드는 게 아니라, 코드를 쓰기 전에 뭘 써야 하는지를 확실하게 만드는 것. 그게 전부입니다." 리서치, 계획, 주석달기, 구현. 오늘 바로 적용해볼 수 있는 방법론입니다.