프로젝트가 커질수록 위험합니다! 바이브코딩 폴더 구조와 파일 관리법

프로젝트가 커질수록 위험합니다! 바이브코딩 폴더 구조와 파일 관리법

처음 바이브코딩을 시작할 때는 index.html, style.css, script.js 세 파일만으로도 충분합니다. 하지만 로그인, 검색, 저장, 통계 같은 기능이 늘어나면 한 파일에 수백 줄의 코드가 쌓이고 AI도 수정할 위치를 정확히 찾기 어려워집니다. 작은 변경이 다른 기능을 망가뜨리거나 같은 이름의 함수가 여러 곳에 생기는 이유도 여기에 있습니다.

 
프로젝트가 커질수록 필요한 폴더 구조와 파일 관리법을 미리 익혀 두면 코드가 늘어나도 원하는 기능을 빠르게 찾고 안전하게 수정할 수 있습니다.
 
 

파일이 많아지는 것보다 역할이 섞이는 것이 문제입니다

프로젝트가 복잡해지는 원인은 단순히 파일 개수가 늘어나서가 아닙니다. 화면 코드, 데이터 처리, 버튼 동작, 서버 요청이 한 파일 안에 섞일 때 문제가 커집니다.
 

예를 들어 script.js 하나에 아래 기능이 모두 들어 있다고 가정해 보겠습니다.

• 로그인 처리
• 일정 추가와 삭제
• 데이터 저장
• 검색과 정렬
• 알림창 표시
• 서버 통신

이 상태에서 AI에게 “검색 기능만 수정해 주세요”라고 요청해도 다른 함수까지 함께 바꿀 가능성이 있습니다.
파일은 코드 길이가 아니라 역할을 기준으로 나누는 것이 좋습니다.
 
 

작은 프로젝트는 기본 구조부터 정리하세요

HTML, CSS, 순수 자바스크립트로 만든 소규모 웹페이지라면 아래 구조로 시작할 수 있습니다.

project/
├─ index.html
├─ css/
│  └─ style.css
├─ js/
│  └─ app.js
├─ images/
└─ data/

 

css에는 디자인 파일을 넣고, js에는 동작을 담당하는 파일을 보관합니다. 사진과 아이콘은 images, 직접 만든 JSON 자료는 data에 넣을 수 있습니다.

파일이 몇 개 없더라도 종류별 폴더를 만들어 두면 프로젝트가 커졌을 때 구조를 다시 바꾸는 일을 줄일 수 있습니다.

폴더 이름은 image, img, pictures처럼 여러 표현을 섞지 말고 하나의 규칙으로 통일하세요.

 
 

기능이 늘어나면 자바스크립트부터 분리하세요

자바스크립트 파일이 길어졌다면 기능별로 나누는 것이 좋습니다.
일정 관리 서비스라면 아래처럼 구성할 수 있습니다.

js/
├─ app.js
├─ todo.js
├─ storage.js
├─ ui.js
└─ validation.js

 
각 파일의 역할은 다음과 같습니다.

• app.js: 프로그램 시작과 기능 연결
• todo.js: 일정 추가, 수정, 삭제
• storage.js: 데이터 저장과 불러오기
• ui.js: 화면 표시와 알림 문구
• validation.js: 빈 입력과 잘못된 값 검사

한 파일에는 하나의 주요 책임만 두는 것이 관리하기 쉽습니다.

AI에게도 “storage.js의 저장 함수만 수정해 주세요”라고 요청할 수 있어 수정 범위가 명확해집니다.

 
 

화면이 여러 개라면 페이지와 공통 요소를 구분하세요

홈, 로그인, 마이페이지처럼 화면이 늘어나면 페이지별 파일과 공통 요소를 나눠야 합니다.

src/
├─ pages/
│  ├─ home/
│  ├─ login/
│  └─ profile/
├─ components/
│  ├─ header/
│  ├─ modal/
│  └─ button/
├─ services/
├─ utils/
└─ assets/

 

pages에는 각 화면에만 쓰이는 코드를 넣습니다. components에는 여러 화면에서 반복 사용하는 버튼, 메뉴, 팝업을 보관합니다.

services는 서버 요청이나 데이터베이스 연결을 담당하고, utils에는 날짜 변환이나 금액 표시처럼 여러 기능에서 공통으로 쓰는 도구를 넣습니다.

어디에도 넣기 애매하다는 이유로 모든 코드를 utils에 몰아넣으면 다시 복잡해질 수 있습니다. 공통으로 두 번 이상 사용되는 코드만 옮기는 편이 안전합니다.

 
 

파일 이름만 봐도 역할을 알 수 있게 만드세요

test.js, new.js, final2.js 같은 이름은 처음에는 편하지만 시간이 지나면 내용을 알기 어렵습니다.

아래처럼 기능이 드러나는 이름을 사용하세요.

• userAuth.js
• todoStorage.js
• dateFormatter.js
• profilePage.css
• loginValidation.js

 
날짜나 상태를 파일 이름에 계속 붙이는 방식도 피하는 것이 좋습니다.

• script_최종.js
• script_진짜최종.js
• script_최종수정2.js

이런 방식 대신 Git이나 별도 백업 폴더로 버전을 관리하세요.
좋은 파일 이름은 열어 보지 않아도 무엇이 들어 있는지 예상할 수 있어야 합니다.
 
 

임시 파일과 사용하지 않는 코드는 바로 정리하세요

AI와 코드를 수정하다 보면 비슷한 파일이 여러 개 생기기 쉽습니다.

• app-old.js
• app-copy.js
• app-test.js
• app-final.js

어떤 파일이 실제로 연결되어 있는지 모르면 AI도 잘못된 파일을 수정할 수 있습니다.

사용하지 않는 파일은 삭제하기 전에 archive 폴더로 옮기거나 Git에 저장하세요. 현재 실행에 필요한 파일만 프로젝트 폴더에 남기는 것이 좋습니다.

주석으로 막아 둔 오래된 코드도 계속 쌓아 두지 마세요. 복구가 필요하다면 버전 기록에서 찾는 편이 더 정확합니다.
 
 

경로 오류를 막으려면 이동 후 바로 확인하세요

폴더를 정리하면서 파일을 옮기면 HTML의 연결 경로나 자바스크립트의 import 주소도 바뀝니다.
 

예를 들어 style.css를 css 폴더로 옮겼다면 다음처럼 수정해야 합니다.

<link rel="stylesheet" href="./css/style.css">

 
이미지는 CSS 파일의 위치를 기준으로 경로가 달라질 수 있으므로 주의해야 합니다.
파일을 여러 개 이동한 뒤 한꺼번에 확인하지 말고 파일 하나 이동 → 경로 수정 → 실행 확인 순서로 진행하세요. 화면이 깨졌다면 콘솔과 네트워크 탭에서 404 오류가 있는지 살펴보는 것이 빠릅니다.
 
 

프로젝트 설명 문서를 함께 만들어 두세요

폴더 구조가 깔끔해도 각 파일의 역할을 기록하지 않으면 새 대화에서 AI에게 처음부터 다시 설명해야 합니다.

프로젝트 최상단에 README.md 파일을 만들고 아래 내용을 적어 보세요.

• 프로젝트 목적
• 사용 기술
• 실행 방법
• 폴더별 역할
• 핵심 기능
• 수정하면 안 되는 파일
• 현재 알려진 오류
• 다음 작업 목록

 
간단한 설명만 있어도 충분합니다.

js/storage.js: localStorage 저장과 불러오기
js/todo.js: 일정 추가, 수정, 삭제
js/ui.js: 목록 화면과 안내 문구 출력

 
README는 사람뿐 아니라 AI가 프로젝트를 빠르게 이해하도록 돕는 작업 지도입니다.
 
 

AI에게 파일 구조를 바꾸게 할 때는 먼저 계획을 받으세요

프로젝트 전체를 한 번에 재구성하도록 요청하면 파일 연결이 끊기거나 함수 이름이 달라질 수 있습니다.
아래처럼 요청하는 것이 안전합니다.

“현재 파일 구조를 분석하고 역할이 섞인 파일을 찾아 주세요. 아직 파일을 이동하거나 코드를 수정하지 말고 새로운 폴더 구조, 이동할 파일, 변경해야 할 경로를 먼저 표로 정리해 주세요.”

 
계획을 확인한 뒤에는 한 단계씩 진행하세요.

“이번에는 storage 관련 함수만 storage.js로 분리해 주세요. 기존 기능과 함수 이름은 유지하고 변경한 import 경로와 테스트 방법을 알려 주세요.”

 
구조 변경도 기능 개발처럼 작은 단위로 나누어야 합니다.
 
 

커질수록 필요한 것은 복잡한 구조가 아니라 명확한 기준입니다

모든 프로젝트에 거대한 폴더 구조가 필요한 것은 아닙니다. 파일이 세 개뿐인데 지나치게 세분화하면 오히려 찾기 어려워질 수 있습니다.
 
파일을 나눌 시점은 아래 기준으로 판단하세요.

• 한 파일에서 서로 다른 기능을 자주 수정함
• 원하는 코드를 찾는 데 시간이 오래 걸림
• 같은 함수나 스타일이 반복됨
• AI가 수정 범위를 자주 벗어남
• 한 기능을 고치면 다른 기능이 망가짐

프로젝트가 커질수록 필요한 폴더 구조와 파일 관리법의 핵심은 종류별 분리 → 기능별 분리 → 공통 요소 분리 → 이름 규칙 통일 → 버전 기록 유지입니다.
 
처음부터 완벽한 구조를 만들려고 하지 마세요. 기능이 늘어나는 속도에 맞춰 한 단계씩 정리하면 됩니다.
 
 
오늘 프로젝트에서 가장 긴 파일 하나를 열고 서로 다른 역할이 몇 개 섞여 있는지 확인해 보세요. 그 역할을 분리하는 것부터 시작하면 AI와의 협업도 한층 안정적으로 바뀔 것입니다.