바이브코딩의 함정 — 빠를수록 구조를 잃는다
바이브코딩으로 빠르게 만들다 보면 반드시 마주치는 구조 붕괴 문제와, 이를 해결하는 방법을 소개합니다.
처음 며칠은 정말 신기합니다. 아이디어를 말하면 코드가 생기고, 화면이 바뀝니다. 기능이 하나씩 추가될 때마다 성취감이 생깁니다. 그런데 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로 구조를 그림으로 그려두는 방식입니다. 전체 그림을 한눈에 파악하기 좋지만, 구조가 바뀔 때마다 그림을 다시 손봐야 해서 유지하는 부담이 있습니다.
작은 프로젝트라면 이 중 어떤 방법이든 충분합니다. 다만 공통된 한계는 기록을 사람이 직접 관리해야 한다는 점입니다. 그래서 프로젝트 구조 추적 자체를 목적으로 만들어진 서비스들도 나오고 있는데, 이 시리즈에서는 그중 하나인 Umtri를 소개합니다.
Umtri — 프로젝트 성장을 기록하는 방법
Umtri는 프로젝트의 구조가 시간이 지나면서 어떻게 변해왔는지를 기록하고 시각화해서 보여주는 서비스입니다.
Umtri.io
Track your project growth history and configuration.
app.umtri.io
핵심 아이디어는 이렇습니다. 프로젝트는 식물처럼 자란다. 처음에는 작은 씨앗에서 시작해, 줄기가 생기고, 가지가 뻗고, 잎이 달립니다. Umtri는 이 성장 과정을 트리(tree) 형태로 기록합니다.
| 단계 | 식물 비유 | 프로젝트에서의 의미 |
|---|---|---|
| Trunk (줄기) | 굵은 줄기 | 앱·서비스 전체 또는 주요 도메인 |
| Limb (큰 가지) | 주요 가지 | 기능 묶음 또는 주요 작업 영역 |
| Twig (잔가지) | 잔가지 | 세부 기능 그룹, 모듈 |
| Leaf (잎) | 잎 | 실제 파일, 컴포넌트, 서비스 단위 |
| Vein (잎맥) | 잎맥 | 함수, 메서드 등 구체적인 동작 |
이 구조를 Umtri에 기록해두면 나중에 “태그 시스템에 문제가 생겼어”라고 했을 때 어떤 컴포넌트들이 연관되어 있는지 바로 볼 수 있습니다.
언제부터 기록을 시작해야 할까
처음부터 완벽하게 구조를 정의할 필요는 없습니다. 기록을 시작하기 좋은 시점은 첫 번째 핵심 기능이 완성됐을 때입니다. 이때 현재 구조를 한 번 정리해두고, 이후 기능을 추가할 때마다 트리를 업데이트하면 됩니다.
다음 편에서는 Umtri를 실제로 Claude Code와 연결하는 방법, 즉 MCP 설정을 다룹니다.