바이브코딩의 함정 — 빠를수록 구조를 잃는다
바이브코딩으로 빠르게 만들다 보면 반드시 마주치는 구조 붕괴 문제와, 이를 해결하는 방법을 소개합니다.
처음 며칠은 정말 신기합니다. 아이디어를 말하면 코드가 생기고, 화면이 바뀝니다. 기능이 하나씩 추가될 때마다 성취감이 생깁니다. 그런데 2~3주쯤 지나면 이런 상황이 찾아옵니다.
“로그인 기능을 추가해줘”라고 했더니 AI가 만들어준 코드가 기존 코드와 충돌합니다. 어디서 충돌하는지 찾으려고 파일을 열어봤더니, 파일이 500줄을 넘어가고 어떤 코드가 무엇을 하는지 파악하기 어렵습니다.
이것이 바이브코딩의 가장 흔한 함정입니다.
왜 바이브코딩은 구조를 무너뜨리는가
바이브코딩으로 빠르게 기능을 추가하다 보면 프로젝트 구조가 무너지는 이유는 두 가지입니다.
AI는 현재 대화만 기억한다
Claude Code는 현재 열려 있는 파일과 대화 내용을 바탕으로 코드를 작성합니다. 3주 전에 “컴포넌트는 반드시 components/ 폴더에 넣자”고 정했더라도, 새로운 대화에서 그 규칙을 언급하지 않으면 AI는 모릅니다.
결과적으로 비슷한 기능을 하는 코드가 여러 곳에 흩어지고, 폴더 구조가 점점 복잡해집니다.
기능 추가 요청이 구조 설계보다 빠르다
바이브코딩의 속도는 장점이자 단점입니다. 기능을 빠르게 만들 수 있기 때문에 설계를 충분히 생각하기 전에 구현부터 하게 됩니다.
| 기간 | 증상 |
|---|---|
| 1~2주 | 기능을 추가할수록 작동이 잘 됨. 생산성 최고 |
| 3~4주 | ”왜 이 부분이 안 되지?” 의문이 생기기 시작 |
| 5~6주 | 새 기능을 추가하면 기존 기능이 깨짐. AI도 원인 파악 어려워함 |
| 2개월+ | 처음부터 다시 만들자는 생각이 드는 상태 |
구조를 잃지 않으려면 무엇이 필요한가
이 문제에 대한 해결책은 코딩 실력이 아닙니다. 프로젝트 구조를 기록하고 추적하는 습관입니다.
무엇이 만들어졌는지, 무엇이 무엇에 연결되어 있는지, 언제 어떤 기능이 추가됐는지를 기록해두면 나중에 AI에게 “지금 우리 프로젝트 구조가 이렇게 생겼어”라고 맥락을 제공할 수 있습니다.
구조를 기록하는 여러 가지 방법
기록하는 방법이 하나만 있는 것은 아닙니다. 널리 쓰이는 방법 몇 가지를 살펴보겠습니다.
프로젝트 안의 문서 파일 — CLAUDE.md나 ARCHITECTURE.md 같은 마크다운 파일에 폴더 구조와 규칙을 적어두는 방식입니다. 별도 도구 없이 바로 시작할 수 있고, Claude Code가 대화를 시작할 때 자동으로 읽어준다는 장점이 있습니다. 다만 코드가 커질수록 문서도 손으로 함께 고쳐야 해서, 어느 순간부터 실제 구조와 문서가 어긋나기 쉽습니다.
노트 도구 — Notion이나 Obsidian 같은 곳에 기능 추가 이력과 구조 메모를 남기는 방식입니다. 형식에 얽매이지 않고 자유롭게 쓸 수 있지만, 기록이 코드와 떨어져 있어서 AI에게 맥락을 전달하려면 매번 내용을 복사해서 붙여넣어야 합니다.
다이어그램 도구 — Mermaid나 Excalidraw로 구조를 그림으로 그려두는 방식입니다. 전체 그림을 한눈에 파악하기 좋지만, 구조가 바뀔 때마다 그림을 다시 손봐야 해서 유지하는 부담이 있습니다.
작은 프로젝트라면 이 중 어떤 방법이든 충분합니다. 공통된 한계는 기록을 사람이 직접 관리해야 한다는 점이지만, 시작 단계에서는 그것으로 충분합니다. 이 시리즈에서는 별도 도구 없이 바로 시작할 수 있고 Claude Code가 대화를 시작할 때 자동으로 읽어주는 CLAUDE.md를 기본 기록 수단으로 삼습니다(3편에서 다뤘습니다).
프로젝트가 커져서 구조 추적을 자동화하고 싶어지면, 그것만을 목적으로 만들어진 전용 서비스(Umtri 같은)를 살펴봐도 됩니다. 다만 그건 나중 이야기고, 지금 필요한 것은 거창한 도구가 아니라 기록하는 습관입니다.
기록은 언제, 어떻게 시작할까
처음부터 완벽하게 구조를 정의할 필요는 없습니다. 기록을 시작하기 좋은 시점은 첫 번째 핵심 기능이 완성됐을 때입니다. 이때 현재 폴더 구조와 주요 파일의 역할을 CLAUDE.md에 한 번 정리해두고, 이후 기능을 추가할 때마다 바뀐 부분만 덧붙이면 됩니다.
핵심은 양이 아니라 꾸준함입니다. 새 컴포넌트를 만들었을 때 한 줄, 데이터 구조가 바뀌었을 때 한 줄. 이렇게 작은 기록이 쌓이면 몇 주 뒤 AI에게 “지금 우리 프로젝트 구조가 이래”라고 맥락을 건넬 수 있습니다.
다음 편에서는 Claude Code에 외부 도구를 연결하는 방법, 즉 MCP를 다룹니다.