바이브코딩이 망하지 않으려면: Claude Code에 '계획 먼저' 시키는 plan-first 워크플로우

바이브코딩에서 가장 비싼 실수는 코드 한 줄을 잘못 쓰는 일이 아닙니다. 문제를 잘못 이해한 채 여러 파일을 건드리고, 나중에 처음부터 되돌리는 일입니다. 그래서 Claude Code에게 처음부터 구현을 맡기기보다, 먼저 계획을 쓰게 하는 편이 안전합니다.

계획은 거창한 PRD가 아닙니다. 무엇을 바꾸고, 무엇은 바꾸지 않으며, 어떻게 성공 여부를 확인할지 정리한 짧은 작업 문서입니다. 이 문서가 있으면 AI의 제안도 검토할 수 있고, 구현 중 방향이 흔들릴 때 돌아갈 기준도 생깁니다.

왜 바로 구현하면 되돌림이 커질까

자연어로 “로그인 기능을 추가해줘”라고만 요청하면 AI는 로그인 화면, 데이터 모델, 인증 방식, 오류 처리까지 추측합니다. 추측이 틀려도 코드는 그럴듯하게 만들어지기 때문에 문제를 늦게 발견하기 쉽습니다.

특히 기존 코드의 규칙이나 데이터 흐름을 충분히 읽지 않고 수정하면 변경 범위가 예상보다 커집니다. 새 기능 하나를 넣었는데 라우트, 타입, 테스트, 환경변수까지 연쇄적으로 바뀌는 식입니다.

조코헌트에 출시된 프로덕트 중 출시 첫 24시간 안에 업보트나 댓글 같은 반응을 하나라도 받은 비율은 59%입니다. 빠른 피드백을 받으려면 빨리 만드는 것도 중요하지만, 되돌림이 큰 구현을 줄여 출시 가능한 상태까지 가는 속도 역시 중요합니다. 계획 단계는 개발을 늦추는 시간이 아니라 재작업을 줄이는 시간에 가깝습니다.

1. 계획 단계에서 결정할 것

문제와 완료 조건

먼저 Claude Code에게 코드를 수정하지 말고 현재 구조를 읽은 뒤 계획서만 작성하라고 지시합니다. 계획에는 다음 질문의 답이 들어가야 합니다.

• 사용자가 겪는 문제는 무엇인가?
• 이번 작업의 완료 조건은 어떤 동작으로 확인하는가?
• 이번 작업에서 제외할 범위는 무엇인가?
• 실패하거나 예외가 발생할 때 어떤 결과를 보여줄 것인가?

“검색 기능 추가”보다 “제목과 본문에서 검색하고, 결과가 없을 때 빈 상태를 보여준다”가 좋은 완료 조건입니다. 동작을 관찰할 수 있는 문장으로 바꾸면 구현 후 검증도 쉬워집니다.

영향 범위와 위험

계획서에는 수정 후보 파일과 각 파일의 역할을 적게 하세요. 데이터베이스, API, 화면, 테스트를 한 덩어리로 묶지 말고 분리하면 누락이 보입니다. 인증, 결제, 삭제, 개인정보처럼 되돌리기 어려운 영역은 별도의 위험 항목으로 표시합니다.

이때 파일을 실제로 확인하지 않은 상태에서 경로를 단정하지 않게 하는 것도 중요합니다. Claude Code에는 “추측하지 말고 저장소에서 확인한 파일만 계획에 포함하라”고 명시하세요. 프로젝트의 공통 규칙은 CLAUDE.md 작성법처럼 별도 문서로 관리해 두면 계획의 일관성도 높아집니다.

2. Claude Code에 계획만 시키기

첫 프롬프트의 구조

다음처럼 작업의 순서를 제한해 요청할 수 있습니다.

지금은 코드를 수정하지 마세요.
1. 저장소 구조와 관련 파일을 먼저 읽으세요.
2. 현재 동작과 제약을 요약하세요.
3. 구현 계획을 단계별로 작성하세요.
4. 변경 파일, 데이터 흐름, 예외 케이스, 검증 방법을 포함하세요.
5. 불확실한 부분은 추측하지 말고 질문 목록으로 분리하세요.

여기에 제품 요구사항을 붙이고, 계획 결과를 계획.md 같은 파일에 남기게 할 수 있습니다. 중요한 점은 “계획을 세운 뒤 바로 실행하지 말라”는 문장입니다. 계획과 실행을 한 번에 요청하면 검토할 틈이 사라집니다.

검토 루프

계획을 받은 뒤에는 코드를 다시 생성시키기보다 먼저 다음을 확인하세요.

• 완료 조건이 사용자의 실제 행동과 연결되는가?
• 수정 범위가 필요 이상으로 넓지 않은가?
• 데이터 손실이나 권한 누락 가능성이 있는가?
• 테스트 또는 수동 확인 절차가 구체적인가?

빠진 항목이 있으면 “계획의 2단계를 수정하고, 변경 이유만 설명해줘”처럼 계획만 고칩니다. 이 과정은 AI 코딩 도구에 컨텍스트 잘 주는 법과 함께 적용하면 프로젝트 규칙과 이번 작업의 요구사항을 분리해서 관리하는 데 도움이 됩니다.

3. 계획을 코드로 옮기는 실행 순서

작은 단위로 구현

계획이 승인되면 전체를 한 번에 실행하지 말고 가장 작은 수직 단위부터 진행합니다. 예를 들어 데이터 구조를 준비하고, 그다음 서버 동작을 만들고, 마지막에 화면을 연결합니다. 각 단계 뒤에는 변경 내용을 요약하게 하고 테스트나 타입 검사를 실행합니다.

Claude Code에 “계획의 1단계만 구현하고 멈춰라. 수정한 파일과 확인한 결과를 보고하라”고 요청하면 작업 범위를 통제하기 쉽습니다. 중간 결과가 틀렸다면 다음 단계로 오류를 전파하지 않고 바로 수정할 수 있습니다.

검증과 중단 기준

각 단계에는 통과 기준과 중단 기준을 함께 둡니다. 예를 들어 “기존 테스트가 실패하면 다음 단계로 가지 않는다”, “스키마 변경이 필요하면 먼저 영향 범위를 다시 계획한다”처럼 정합니다.

코드가 실행된다는 사실만으로 완료라고 판단하지 마세요. 정상 입력, 빈 값, 권한 없는 사용자, 중복 요청처럼 실패하기 쉬운 경우도 확인해야 합니다. 구현 결과 검증은 AI가 짠 코드를 믿어도 될까에서 다룬 체크리스트와 연결해 점검할 수 있습니다.

4. 계획서를 살아 있는 문서로 유지하기

계획서는 구현이 끝나면 버리는 메모가 아닙니다. 실제로 바뀐 파일, 계획과 달라진 결정, 아직 남은 위험을 짧게 갱신하세요. 다음 작업에서 Claude Code가 같은 맥락을 다시 추측하지 않아도 됩니다.

다만 모든 작업에 긴 문서를 만들 필요는 없습니다. 작은 문구 수정이나 스타일 변경은 짧은 체크리스트로 충분하고, 여러 계층을 건드리거나 실패 비용이 큰 작업일수록 plan-first 흐름을 적용하는 편이 좋습니다.

핵심은 간단합니다. 먼저 읽게 하고, 계획을 쓰게 하고, 사람이 범위를 승인한 뒤, 작은 단위로 구현하고 검증합니다. AI의 속도를 포기하지 않으면서도 방향을 사람이 통제하는 가장 가벼운 안전장치입니다.