AI 코딩 도구로 복잡한 프로젝트를 진행하다 보면 어느 순간 결과물이 완전히 무너지는 경험, 다들 한 번쯤 해보셨을 겁니다. 저 역시 Claude CLI로 바이브 코딩을 시작했을 때 비슷한 벽에 부딪혔습니다. 일반적으로 프롬프트를 치고 바로 코드를 생성하는 방식이 효율적이라고 알려져 있지만, 제 경험상 이 방법은 작업이 조금이라도 복잡해지면 속수무책으로 무너집니다. 그래서 지금은 완전히 다른 워크플로우를 정착시켰고, 이 방식이 왜 실전에서 더 효과적인지 구체적으로 공유하려 합니다.
계획분리: 기획과 코딩을 나누는 이유
바이브 코딩에서 가장 흔한 실수는 AI에게 즉시 코드를 작성하게 하는 겁니다. 일반적으로 AI가 알아서 잘 판단해줄 거라는 믿음이 있는데, 실제로 써보니 전혀 그렇지 않았습니다. 복잡도가 올라가는 순간 AI는 기존 아키텍처를 무시하고 멀쩡하게 돌아가는 주변 시스템을 슬금슬금 망가뜨리기 시작합니다.
여기서 워크플로우(Workflow)란 작업을 수행하는 일련의 절차와 단계를 의미합니다. 쉽게 말해 AI 코딩을 할 때 어떤 순서로 작업을 진행하는지에 대한 체계적인 방법론입니다. 저는 이 워크플로우를 리서치-계획-주석-구현의 4단계로 분리했고, 핵심 원칙은 딱 하나입니다. 계획을 제가 직접 검토하고 승인하기 전까지 Claude에게 절대 코드를 쓰게 하지 않는 겁니다.
첫 번째 단계인 리서치에서는 코드베이스를 깊이 읽는 작업부터 시작합니다. Claude에게 관련 폴더를 철저히 이해하라고 지시하되, 반드시 별도의 마크다운 파일(research.md)에 상세 보고서를 작성하게 합니다. 채팅창 안에서 구두 요약으로 끝내면 안 됩니다. 프롬프트에 '깊이', '매우 상세히', '세부 사항' 같은 단어를 명시적으로 넣어야 Claude가 대충 훑어보고 넘어가는 걸 방지할 수 있습니다.
실제로 Claude CLI를 쓰면서 생각보다 결과물이 느릴 때가 많았는데, 이건 정확한 파일 구조를 파악하는 데 시간이 걸리기 때문입니다. 하지만 이 리서치 단계를 건너뛰면 나중에 훨씬 더 큰 삽질을 하게 됩니다. AI 코딩에서 가장 비싼 실패는 문법 에러가 아니라, 멀쩡하게 돌아가는데 주변 시스템을 망가뜨리는 구현입니다(출처: Google AI Research). 기존 추상화 레이어를 무시하는 함수나 ORM 트랜잭션 관리를 고려하지 않은 마이그레이션 같은 게 바로 그런 사례입니다.
주석피드백: 문서 기반 협업 방식
리서치가 끝나면 계획 단계로 넘어갑니다. 여기서도 별도의 마크다운 파일(plan.md)에 상세 구현 계획을 작성하게 합니다. Claude Code에 내장된 플랜 모드가 있긴 하지만, 솔직히 이건 별로입니다. 제가 자체 MD 파일을 고집하는 이유는 다음과 같습니다:
- 에디터에서 직접 편집하고 인라인 메모를 달 수 있습니다
- 프로젝트 안에 실제 산출물로 남아 연속성이 보장됩니다
- 채팅 세션이 날아가도 작업 맥락이 유지됩니다
계획서에는 접근 방식에 대한 설명, 실제 변경 사항을 보여주는 코드 스니펫, 수정될 파일 경로, 고려 사항과 트레이드오프까지 모두 담깁니다. Claude가 계획을 작성하면 저는 에디터에서 직접 주석을 답니다. 이 주석은 잘못된 가정을 수정하거나("아니, 이건 PUT이 아니라 PATCH여야 해"), 접근 방식을 거부하거나("이 부분 제거해. 여기는 캐싱 필요 없어"), 제약 조건을 추가하는 역할을 합니다.
여기서 중요한 건 명시적으로 "아직 구현하지 마"라고 써줘야 한다는 겁니다. 이 문장 없으면 Claude가 혼자 판단해서 바로 코드를 짜기 시작합니다. 주도권을 절대 넘기면 안 됩니다. 이 주석-수정 사이클이 보통 1~5회 정도 반복되는데, 이 과정에서 실제 코딩보다 훨씬 중요한 아키텍처 결정이 이루어집니다.
특히 제가 GitHub에 올리는 README.md 작성할 때도 이 방식을 썼습니다. 마크다운 문법을 일일이 배우지 않아도 Claude CLI를 통해 몇 분 만에 내용을 채우고 형식을 보기 좋게 만들 수 있었습니다. 비전공자들은 마크다운을 배울 기회가 많지 않은데, 이런 방식으로 포트폴리오 작성에 바로 활용할 수 있었습니다.
실전팁: 속도보다 정확성을 선택한 이유
계획이 완전히 준비되면 그제야 구현 명령을 내립니다. 저는 세션마다 재사용하는 표준 프롬프트를 만들어뒀는데, "전부 구현해라. 작업 완료하면 계획 문서에 완료 표시해라. any 타입 쓰지 마라. 지속적으로 타입 체크 실행해서 새 문제 만들지 마라" 같은 내용입니다.
이 시점에서 모든 결정이 이미 내려지고 검증된 상태이기 때문에, 구현은 기계적이 됩니다. 창의적이지 않습니다. 그리고 이게 바로 의도한 겁니다. 진짜 중요한 판단은 이미 주석 달기 사이클에서 끝났으니까요. Claude가 계획을 실행하는 동안 제 역할은 설계자에서 감독자로 바뀝니다. 프롬프트도 극적으로 짧아져서 "리밸런스 이벤트 함수 구현 안 했잖아", "설정 페이지를 메인 앱이 아니라 어드민 앱에 만들어" 같은 수준으로 간결해집니다.
CI/CD(Continuous Integration/Continuous Deployment)란 코드 변경사항을 자동으로 테스트하고 배포하는 개발 방법론입니다. 바이브 코딩도 비슷한 맥락에서, 계획과 실행을 분리해서 지속적으로 검증하는 파이프라인을 만드는 겁니다. 잘못된 방향으로 가고 있다면 절대 그 위에서 패치하려 하지 마세요. Git을 통째로 리셋하고 범위를 재설정하는 게 거의 항상 더 효과적입니다.
개인적으로는 추후에 더 빠르게 구조를 파악하고 답변을 내는 AI가 나오면 각광받을 거라고 생각합니다. 빨리빨리 문화가 강한 대한민국에서는 속도가 경쟁력이니까요. 하지만 현재로서는 정확성이 우선입니다. 바이브 코딩은 이제 엑셀처럼 그저 도구일 뿐입니다. 엑셀 공부가 아니라 바이브 코딩 공부가 필수가 될 시대가 오고 있습니다(출처: Stack Overflow Developer Survey).
정리하면 핵심은 이겁니다. Claude에게 코드를 잘 쓰게 만드는 게 아니라, 코드를 쓰기 전에 뭘 써야 하는지를 확실하게 만드는 것. 깊이 읽고, 계획을 작성하고, 계획이 맞을 때까지 주석을 달고, 그다음에 전부 실행하게 하되 타입 체크는 계속 돌리면서. 마법 같은 프롬프트도 없고 정교한 시스템 인스트럭션도 없습니다. 그냥 생각하는 것과 타이핑하는 것을 분리하는 규율 있는 파이프라인뿐입니다.