바이브코딩 입문 단계에서 대부분은 튜토리얼을 따라간다. 유튜브나 블로그에서 고수가 만든 코드를 보면서 따라 치다 보면 어찌저찌 작동은 한다. 그런데 그 순간을 넘기면 벽이 온다. 새 프로젝트를 시작했는데, 분명히 같은 기능인데 구조가 조금만 달라져도 어디서부터 손을 대야 할지 모른다. 이전에 성공했던 코드를 그대로 붙여넣어도 작동하지 않는다. 바이브코딩 입문자가 두 번째 프로젝트에서 반드시 만나는 벽이 바로 이것이다.
여기서 채팅형 AI에게 물어보면 또 막힌다. 코드를 파일 단위로 복붙해서 넘겨야 하고, 파일 간 연결 구조는 말로 설명해야 한다. AI는 전체 그림을 보지 못하고, 엉뚱한 곳을 수정한다.
Claude Code는 이 지점에서 결정적으로 다르다. 프로젝트 루트 폴더를 통째로 넘기면 파일 트리 전체를 읽고, 구조를 파악하고, 새 프로젝트에 맞게 재구성해준다. 고수의 튜토리얼이든, GitHub 오픈소스든, 내가 지난달에 만든 프로젝트든 — 로컬 폴더로 존재하기만 하면 레퍼런스가 된다. 그리고 이 방식으로 완성한 프로젝트는 다시 다음 프로젝트의 레퍼런스가 된다. 레퍼런스가 쌓일수록 만들 수 있는 것이 늘어난다.
레퍼런스란 무엇인가 — 내가 만든 코드만이 아니다
레퍼런스라고 하면 내가 과거에 만든 프로젝트만 떠올리기 쉽다. 하지만 범위는 훨씬 넓다.
| 레퍼런스 종류 | 예시 | 활용 방식 |
|---|---|---|
| 고수의 튜토리얼 | 유튜브·블로그 첨부 코드 | 따라 만든 폴더를 그대로 레퍼런스로 활용 |
| GitHub 오픈소스 | 공개된 FastAPI·Django 예제 | clone 후 로컬에서 구조 분석 |
| 내 성공 프로젝트 | 이전에 완성한 앱 | 동일 기능을 새 프로젝트에 이식 |
공통점은 하나다. 로컬 폴더로 존재하는, 작동이 검증된 구조라는 것이다. Claude Code는 이 폴더를 통째로 읽는다. 내가 직접 만들었는지, 튜토리얼을 따라 만들었는지, GitHub에서 clone했는지는 상관없다. 폴더가 있으면 분석이 시작된다.
Claude Code가 폴더를 읽는 방식 — 채팅형 AI와 결정적으로 다른 점
채팅형 AI에게 코드 문제를 물어볼 때는 코드를 직접 복사해서 붙여넣어야 한다. 파일이 여러 개라면 하나씩 가져와야 하고, 파일 간의 연결 관계는 말로 설명해야 한다. 컨텍스트가 쪼개지고, AI는 전체 그림을 보지 못한다.
Claude Code는 다르다. 프로젝트 루트 경로를 알려주면 파일 트리 전체에 직접 접근한다. 어떤 파일이 어떤 파일을 import하는지, 변수명이 어떻게 연결되는지, 설정 파일이 어디 있는지를 스스로 파악한다.
흐름을 정리하면 아래와 같다.
레퍼런스 폴더 경로를 알려준다
↓
Claude Code가 파일 트리 전체를 분석한다
↓
구조 파악 → 핵심 로직 추출 → 변수 매핑
↓
새 프로젝트 구조에 맞게 이식한다
코드를 한 줄도 붙여넣지 않아도 된다. 경로 하나가 전부다.
프롬프트 패턴 3가지 — 이렇게 요청하면 된다
패턴 1. 튜토리얼 레퍼런스 — 따라 만든 폴더를 그대로 쓴다
튜토리얼을 따라 만든 프로젝트는 그 자체로 레퍼런스가 된다. 완전히 이해하지 못해도 상관없다. 작동했다는 사실이 중요하다.
“
/path/tutorial-project폴더를 분석해줘. 이 프로젝트의 로그인 기능 구조를 파악하고, 내 프로젝트(/path/mine)에 똑같이 구현해줘. 변수명과 파일 구조는 내 프로젝트에 맞게 매핑해줘.”
튜토리얼 코드는 대부분 설명을 위해 단순화되어 있다. Claude Code는 그 단순한 구조에서 핵심 로직을 추출하고, 내 프로젝트의 복잡한 구조에 맞게 재조립한다. 따라 만들 때는 몰랐던 연결 구조가 이 과정에서 드러난다.
md 파일이 있으면 정확도가 올라간다
프로젝트에 README.md나 CLAUDE.md 같은 문서가 있다면 함께 넘기는 것이 좋다. 폴더 구조가 “어떻게 만들었나”를 알려준다면, md 파일은 “왜 이렇게 만들었나”를 알려준다. 설계 의도까지 파악한 상태에서 이식하면 변수 매핑 정확도와 완성도가 달라진다.
“
/path/tutorial-project의 CLAUDE.md와 폴더 구조를 먼저 읽고, 내 프로젝트(/path/mine)에 로그인 기능을 똑같이 구현해줘. 변수명과 구조는 내 프로젝트에 맞게 매핑해줘.”
md 파일이 없어도 진행은 된다. 단, 이식 후 동작을 한 번 더 확인하는 것이 좋다.
패턴 2. GitHub 오픈소스 이식 — clone 후 핵심만 추출한다
GitHub에서 발견한 코드를 내 프로젝트에 적용하고 싶을 때 쓰는 패턴이다. 전체를 가져오는 것이 아니라 필요한 기능만 골라서 이식한다.
먼저 clone으로 로컬에 받아온다. 그 다음 경로를 넘기면 된다.
“
/path/github-ref폴더를 분석해서 인증 기능 관련 핵심 로직만 추출해줘. 내 프로젝트(/path/mine)에 적용할 건데, 구조가 다른 부분이 있으면 어떻게 조율할지 설명해줘.”
레퍼런스 구조와 내 프로젝트 구조가 다를 때, Claude Code는 그 차이를 설명하면서 적용 방식을 제안한다. 오픈소스를 그대로 복붙하다가 전체가 꼬이는 상황을 막을 수 있다.
패턴 3. 비교 진단 — A에서는 됐는데 B에서는 안 된다
같은 기능을 새 프로젝트에 구현했는데 작동하지 않을 때 쓰는 패턴이다. 오류 메시지를 혼자 분석하는 것보다 두 프로젝트를 직접 비교하는 것이 빠르다.
“A에서는 잘 됐는데 B에서는 안 된다.
/path/A와/path/B두 루트를 비교해서 차이점과 원인을 찾아줘.”
Claude Code는 두 폴더를 동시에 읽고, 구조·설정·변수·의존성을 비교해서 어디서 차이가 생겼는지를 짚어준다. 혼자 디버깅에 몇 시간을 쓰는 문제를 이 한 줄로 좁혀낼 수 있다.
이 방식이 바이브코딩 입문자에게 강력한 3가지 이유
첫째, 정답이 눈앞에 있는 상태로 시작한다. 레퍼런스가 있다는 것은 이미 작동하는 코드가 존재한다는 뜻이다. 백지에서 시작하는 것이 아니라, 정답을 보면서 문제를 푸는 구조다. 실패 범위가 줄어든다.
둘째, 구조를 몰라도 일단 작동시킬 수 있다. 바이브코딩 입문자가 가장 힘든 순간은 “어떤 파일을 어떻게 연결해야 하는지” 모를 때다. Claude Code가 두 프로젝트의 구조를 비교하고 매핑해주면, 그 판단을 AI에게 위임할 수 있다.
셋째, 레퍼런스가 쌓인다. 튜토리얼로 시작해서 완성한 프로젝트는 다음 프로젝트의 레퍼런스가 된다. GitHub에서 이식한 기능이 잘 작동했다면, 그 프로젝트도 레퍼런스가 된다. 레퍼런스가 하나씩 늘어날수록, 만들 수 있는 것의 범위가 넓어진다. 입문자가 성장하는 구조가 자연스럽게 만들어진다.
작동하는 프로젝트 폴더 하나가 있다면, 그것이 가장 강력한 교과서다. 경로를 알려주고, 뭘 원하는지 말하면 된다.
[링크 제안]
레퍼런스 기반 이식을 시도하기 전에, 바이브코딩 워크플로우 전체 구조를 먼저 잡아두면 실패 확률이 낮아진다.
Claude Code에게 넘길 CLAUDE.md를 어떻게 작성하는지 궁금하다면 이 글이 이어진다.
Claude Code 공식 문서는 Claude Code 공식 사이트에서 확인할 수 있다.
