바이브코딩의 함정 — 쉬움이 오히려 어려움을 만든다.

처음 며칠은 정말 신기합니다. 아이디어를 말하면 코드가 생기고, 화면이 바뀝니다. 기능이 하나씩 추가될 때마다 성취감이 생깁니다. 그런데 일정 수준 프로젝트가 커지기 시작하면 점점 이 과정이 어려워지기 시작합니다.

예를 들어, “로그인 기능을 추가해줘”라고 했더니 한참 만든 코드가 기존 코드와 충돌하여 프로젝트 자체가 깨집니다. 어디서 충돌하는지 찾으며 AI서비스가 하루 종일 분석했는데, ‘찾았다’는 분석과는 달리 수정을 해도 계속 오류가 발생하고, 토큰과 시간만 낭비되며 문제가 좀처럼 해결되지 않습니다.

모든 것을 안다고 생각했던, 그렇게 생각하도록 메시지를 던지는 AI 서비스와 바이브코딩의 함정입니다.

바이브코딩으로 기능을 계속 추가하다 보면 프로젝트 구조가 무너지는 이유는 두 가지입니다.

AI는 생각보다 많은 것을 보지 않는다

AI 서비스는 현재 열려 있는 파일과 현 세션의 대화 내용, 그리고 CLAUDE.md 정도를 참조하여 코드를 작성합니다. 기존에 만든 것이나 변경한 것을 사용자는 기억하고 있고 당연히 만든 당사자인 AI도 기억할 거라 착각하지만, 실제로는 꼭 필요한 내용들만 파악할 뿐, 모든 내용을 매번 완벽하게 파악하며 새로운 코드를 작성하지는 않습니다.

만약 AI서비스가 모든 코드베이스와 스펙을 매 대화와 작성과정에서 파악했다면 현 시점의 형태보다 여러 모로 비효율적이었을 것이기 때문에 사실 이건 당연한 설계입니다. 문제는 이 때문에 특히 구축한지 오래된 코드와 충돌하는 설계를 주문했을 때 그 사실을 알지 못하고 오로지 현재 주문받은 작업을 잘 수행하는 데만 초점을 두어 작업합니다. 긍정적이고 자신감에 찬 어조와는 달리, 많이 알지 못하는 상태로 작업을 한다는 것입니다.

사용자도 구조를 모른다

바이브코딩이 쉽다는 것은 어디까지나 ‘주문’의 영역에서의 이야기입니다. 오히려 코드 자체는 사용자가 알지 못하는 스타일로, 제대로 보지 않은 상태에서 수없이 작성된 상태이기 때문에 어떻게 구성되어있고 어떤 위험이 있는 채로 만들어졌는지 알지 못하는 상태인 경우가 많습니다.

그래서 문제가 생겼을 때에도 결국 AI의 코드 분석 결과에 의존하게 되는데, 이 분석 결과가 오판인 경우 문제는 바로 옆에 두고 주변만 빙빙 돌면서 잘못된 문제 분석으로 수정된 코드가 새로운 문제를 낳는,무한대로 반복되는 오류의 루프에 빠지기 시작합니다.

기간	증상
프로젝트 시작	기능이 새롭게 만들어짐, 말하는대로 원활히 만들어짐.
프로젝트 성장	프로젝트가 커지고 복잡해짐, 점점 어떤 상태인지 모르는 블랙박스가 됨.
문제 발생	새 기능을 추가하니 기존 기능이 깨짐. AI가 원인을 분석하지만, 오판.
문제 확대	오판을 통해 수정된 내용이 새로운 버그를 만듬.
무한 루프	버그가 중첩되어 분석 자체가 어려워짐, 새로 만드는 게 더 나은 상태.

오류의 함정에 빠지지 않으려면

이 문제에 대한 직접적인 해결책은 물론 코딩 실력과 경험일 수 있습니다. 그러나 이 함정에 빠지는 것 자체가 문제이기 때문에 이것을 예방하는 게 중요한데, 이 때 필요한 게 프로젝트 구조를 이해하고 프롬프트에서 AI서비스에게 주의해야 할 내용을 같이 전달하는 것입니다.

무엇이 만들어졌는지, 무엇이 무엇에 연결되어 있는지, 언제 어떤 기능이 추가됐는지를 알고 새로운 구조가 어떻게 추가될지, 어떠한 위험이 도사리는지를 알면 AI에게 “새로 기능을 추가할 때 지금 우리 프로젝트 구조의 이러한 지점들을 감안해줘”라고 필요한 맥락을 제공할 수 있고, 이를 통해 함정을 미리 알고 피할 수 있습니다.

구조를 이해하고 기록하는 여러 가지 방법

아래의 방법들은 구조를 이해하고 기록하는데 널리 쓰이는 방법들입니다.

프로젝트 안의 문서 파일 — 앞선 3편에서 다룬 CLAUDE.md나 ARCHITECTURE.md 같은 마크다운 파일은 폴더 구조와 규칙을 기록하여 수정 과정에 생길 수 있는 충돌 문제를 수정해줍니다. 별도 도구 없이 바로 시작할 수 있고, Claude Code가 대화를 시작할 때 자동으로 읽어준다는 장점이 있습니다. 다만 단순 문서이기 때문에 검증 도구가 없는데, 실제와 다른 경우 오히려 문제를 만들수 있다는 점과 사용자가 읽고 파악하기에는 한계가 있다는 점이 단점입니다.

노트 도구 — Notion이나 Obsidian 같은 곳에 기능 추가 이력과 구조 메모를 남기는 방식입니다. 형식에 얽매이지 않고 자유롭게 쓸 수 있지만, 기록이 코드와 떨어져 있어서 기록이 ‘낡을’ 수 있습니다. 사용자가 꼼꼼하고 부지런히 관리해야 하며, 프롬프트에서 필요한 내용들을 정확히 전달해야 합니다.

다이어그램 도구 — Mermaid나 Excalidraw로 구조를 그림으로 그려두는 방식입니다. 사용자가 이해하기에는 가장 좋은 형태입니다. 전체 그림을 한눈에 파악하기 좋지만, 구조가 바뀔 때마다 그림을 다시 손봐야하고 CLAUDE.md와 중복인 내용이 되어 효율성이 떨어집니다.

Umtri.io — Umtri.io는 이러한 문제를 해결하기 위해 BEPULJANG이 제작한 프로젝트 추적 도구입니다. MCP(Model Context Protocol)를 통해 AI서비스와 직접 연결되어 AI서비스가 만든 프로젝트를 기록하고 UI를 통해 시각적으로 보여주며, 새로운 프로젝트 계획 시 추가되는 노드나 연결 관계 등을 분석하여 발생할 수 있는 오류 지점들도 자동으로 파악합니다. 프로젝트가 일정 수준 이상 성장했다면, 도입하여 위험을 줄이고 프로젝트에 대한 이해도를 높일 수 있습니다.

기록은 언제, 어떻게 시작할까

처음부터 완벽하게 구조를 정의할 필요는 없습니다. 기록을 시작하기 좋은 시점은 첫 번째 핵심 기능이 완성됐을 때입니다. 이때 현재 폴더 구조와 주요 파일의 역할을 CLAUDE.md에 한 번 정리해두고, 이후 기능을 추가할 때마다 바뀐 부분만 덧붙이면 됩니다.

핵심은 양이 아니라 꾸준함입니다. 새 컴포넌트를 만들었을 때 한 줄, 데이터 구조가 바뀌었을 때 한 줄. 이렇게 작은 기록이 쌓이면 몇 주 뒤 AI에게 “지금 우리 프로젝트 구조가 이래”라고 맥락을 건넬 수 있습니다.

다음 편에서는 Claude Code에 외부 도구를 연결하는 방법, 즉 MCP를 다룹니다. Umtri.io를 설명하면서 간략하게 언급되었는데, 다음 편을 통해 MCP가 무엇인지 자세히 살펴보겠습니다.