바이브 코딩 프로젝트의 폴더 구조를 이해하는 가장 쉬운 순서

바이브 코딩 프로젝트의 폴더가 복잡해 보이는 이유

바이브 코딩 도구로 웹사이트나 애플리케이션을 만들면 짧은 시간 안에 많은 파일과 폴더가 생성된다. 개발 경험이 많지 않은 사람에게는 어떤 파일을 먼저 열어야 하는지 판단하는 것부터 어렵다.

프로젝트 폴더를 위에서부터 하나씩 모두 읽으려고 하면 금방 지칠 수 있다. 직접 작성하지 않은 코드가 많고, 설정 파일과 자동 생성 파일까지 섞여 있기 때문이다.

하지만 프로젝트 구조를 이해하기 위해 모든 파일을 읽을 필요는 없다. 설정, 화면, 기능, 데이터 순서로 범위를 좁히면 AI가 만든 프로젝트도 비교적 빠르게 파악할 수 있다.

이 글에서는 Next.js와 TypeScript 기반 웹앱을 예시로 사용하지만, React나 다른 JavaScript 프로젝트에도 비슷한 방법을 적용할 수 있다.

프로젝트 폴더를 읽기 전에 하지 말아야 할 것

프로젝트를 처음 열었을 때 node_modules 폴더부터 확인할 필요는 없다. 이 폴더에는 프로젝트가 설치한 외부 패키지의 코드가 들어 있으며 파일 수가 매우 많다.

.next, dist, build처럼 빌드 과정에서 자동으로 생성되는 폴더도 처음에는 읽지 않아도 된다. 이 폴더들은 원본 코드를 이용해 만들어진 결과물이므로 프로젝트의 구조를 파악하는 출발점으로 적합하지 않다.

먼저 사람이 직접 관리하는 설정 파일과 소스 코드 폴더를 찾아야 한다.

가장 쉬운 순서: 설정에서 시작해 데이터까지 이동한다

초보자는 다음 네 단계로 프로젝트를 읽는 것이 좋다.

설정 파일에서 프로젝트의 기술 환경을 확인한다.
화면 파일에서 사용자가 보는 페이지를 찾는다.
화면이 불러오는 컴포넌트와 기능을 따라간다.
기능이 사용하는 API와 데이터 저장 위치를 찾는다.

이 순서는 사용자가 보는 결과에서 내부 동작으로 이동하는 방식이다. 폴더 이름을 전부 외우는 것보다 하나의 화면이 어떻게 작동하는지 따라가는 것이 이해하기 쉽다.

1단계: 최상위 설정 파일부터 확인한다

프로젝트 최상위 폴더에는 애플리케이션의 전체 환경을 설명하는 파일이 있다. 처음에는 다음 파일을 확인하면 된다.

package.json
README.md
tsconfig.json
next.config.js 또는 next.config.mjs
.gitignore
.env.example

이 중 가장 먼저 확인할 파일은 package.json이다. 프로젝트에서 사용하는 패키지와 실행 명령을 확인할 수 있기 때문이다.

npm 공식 문서에 따르면 package.json은 프로젝트가 의존하는 패키지와 사용 가능한 버전을 기록하고, 다른 환경에서도 프로젝트를 재현하는 데 사용된다. npm package.json 안내

package.json에서는 다음 항목을 살펴본다.

scripts: 개발 서버, 빌드, 테스트와 코드 검사 명령
dependencies: 실제 서비스 실행에 필요한 패키지
devDependencies: 개발과 테스트에 필요한 도구
프로젝트 이름과 버전
사용 중인 주요 프레임워크

예를 들어 scripts에 dev, build, start, lint가 있다면 프로젝트를 실행하고 검증할 때 어떤 명령을 사용해야 하는지 알 수 있다.

tsconfig.json에서 코드의 기준 위치를 확인한다

TypeScript 프로젝트라면 tsconfig.json도 확인해야 한다. 이 파일에는 타입 검사 방식과 파일 경로 규칙이 들어 있다.

특히 paths 또는 baseUrl 설정이 있다면 코드에서 사용하는 @/components와 같은 경로가 실제로 어느 폴더를 가리키는지 알 수 있다.

이 설정을 확인하지 않으면 import 문에 표시된 경로와 실제 파일 위치가 다르게 보여 파일을 찾기 어려울 수 있다.

처음부터 모든 옵션을 이해할 필요는 없다. 다음 항목을 중심으로 확인하면 된다.

엄격한 타입 검사를 사용하는지
소스 코드의 기준 폴더가 어디인지
별칭 경로가 설정돼 있는지
어떤 파일과 폴더를 타입 검사에 포함하는지

환경변수 파일은 내용보다 사용 위치를 확인한다

.env, .env.local, .env.production 같은 파일에는 데이터베이스 주소, API 키와 외부 서비스 설정이 들어갈 수 있다.

이 파일은 프로젝트 구조를 이해하는 데 중요하지만 내용을 블로그, 채팅이나 공개 저장소에 그대로 올려서는 안 된다. 실제 값 대신 어떤 이름의 환경변수가 사용되는지만 확인하는 것이 안전하다.

Next.js 공식 문서에서도 .env와 환경별 설정 파일은 버전 관리에 포함하지 않아야 하는 파일로 안내한다. Next.js 프로젝트 구조 공식 문서

AI에게 프로젝트 분석을 요청할 때도 실제 비밀번호와 API 키를 전달하지 말고 다음과 같이 가려야 한다.

DATABASE_URL=[비공개]
API_SECRET_KEY=[비공개]
PUBLIC_SITE_URL=https://example.com

2단계: 사용자가 보는 화면 파일을 찾는다

설정 파일을 확인했다면 다음에는 화면을 구성하는 폴더를 찾는다. Next.js 프로젝트에서는 주로 app, pages 또는 src 폴더 안에 화면 코드가 있다.

Next.js App Router에서는 폴더 구조가 URL 구조와 연결된다. app 아래의 중첩 폴더가 주소 경로를 만들고, page.tsx 또는 route.ts가 있어야 실제 공개 경로나 API가 된다.

예를 들어 다음과 같은 구조가 있다고 가정해 보자.

project/
├─ app/
│  ├─ page.tsx
│  ├─ layout.tsx
│  ├─ login/
│  │  └─ page.tsx
│  └─ dashboard/
│     ├─ page.tsx
│     └─ settings/
│        └─ page.tsx
├─ components/
├─ lib/
├─ public/
└─ package.json

이 구조에서 주요 주소는 다음과 연결된다.

app/page.tsx → /
app/login/page.tsx → /login
app/dashboard/page.tsx → /dashboard
app/dashboard/settings/page.tsx → /dashboard/settings

Next.js 공식 문서도 파일 시스템 기반 라우팅을 사용하며 폴더와 파일을 이용해 페이지 주소를 정의한다고 설명한다. Next.js 레이아웃과 페이지

특정 화면을 이해하고 싶다면 해당 주소와 연결된 page.tsx부터 열면 된다.

page.tsx와 layout.tsx의 차이

page.tsx는 특정 주소에서 표시되는 화면을 담당한다. layout.tsx는 여러 페이지가 함께 사용하는 공통 구조를 담당한다.

전체 사이트의 상단 메뉴와 하단 영역이 모든 페이지에 나타난다면 최상위 layout.tsx에서 관리할 가능성이 높다. 대시보드 안에서만 보이는 사이드바는 dashboard 폴더 내부의 layout.tsx에 있을 수 있다.

화면 일부가 어디에서 추가됐는지 모르겠다면 현재 페이지의 page.tsx뿐만 아니라 상위 폴더의 layout.tsx를 차례로 확인해야 한다.

Next.js App Router에서는 상위 레이아웃이 하위 페이지를 감싸는 계층 구조로 렌더링된다.

loading, error, not-found 파일도 확인한다

Next.js 프로젝트에서는 파일 이름 자체가 특별한 역할을 가질 수 있다.

loading.tsx: 데이터를 기다리는 동안 표시할 화면
error.tsx: 페이지 내부 오류가 발생했을 때 표시할 화면
not-found.tsx: 찾을 수 없는 페이지를 표시하는 화면
route.ts: 서버 API 요청을 처리하는 파일

정상 화면만 확인하면 오류 상황을 담당하는 코드를 놓칠 수 있다. 로그인이나 데이터 조회 기능을 분석할 때는 같은 폴더의 loading, error, route 파일도 함께 확인하는 것이 좋다.

3단계: 화면에서 불러오는 기능을 따라간다

화면 파일을 찾았다면 파일 상단의 import 문을 확인한다. import 문은 해당 화면이 어떤 컴포넌트와 기능을 사용하는지 알려주는 지도와 같다.

예를 들어 다음과 같은 코드가 있다고 가정해 보자.

import LoginForm from "@/components/auth/LoginForm"
import { login } from "@/lib/auth"

이 경우 다음 순서로 이동하면 된다.

현재 로그인 페이지를 확인한다.
components/auth/LoginForm에서 입력 화면을 확인한다.
lib/auth에서 실제 로그인 처리를 확인한다.
로그인 함수가 호출하는 API 또는 인증 서비스를 확인한다.

이처럼 하나의 페이지에서 시작해 import 경로를 따라가면 프로젝트 전체를 읽지 않아도 해당 기능의 흐름을 이해할 수 있다.

components 폴더에서는 재사용 화면을 찾는다

components 폴더에는 버튼, 입력창, 메뉴, 카드와 같은 재사용 가능한 화면 요소가 들어가는 경우가 많다.

하지만 components라는 이름이 반드시 정해진 규칙은 아니다. 프로젝트에 따라 ui, shared, widgets 또는 기능별 폴더를 사용할 수도 있다.

Next.js 공식 문서도 components, lib, utils, hooks, styles 같은 이름은 일반적인 예시일 뿐 특별한 프레임워크 규칙은 아니라고 설명한다.

따라서 폴더 이름만 보고 역할을 확정하지 말고 파일을 사용하는 import 위치를 함께 확인해야 한다.

lib, utils, services 폴더에서는 실제 기능을 찾는다

화면과 컴포넌트가 어떻게 보이는지 이해했다면 다음에는 실제 동작을 담당하는 코드를 찾는다.

프로젝트에 따라 다음과 같은 폴더 이름이 사용될 수 있다.

lib: 여러 기능에서 사용하는 공통 로직
utils: 문자열, 날짜와 숫자를 처리하는 작은 함수
services: 외부 API와 데이터 서비스를 호출하는 코드
hooks: 화면 상태와 반복되는 React 동작
actions: 서버에서 실행되는 작업
api: 서버 요청을 받는 엔드포인트

이름은 프로젝트마다 다르므로 특정 화면이 import하는 파일을 따라가는 것이 가장 정확하다.

4단계: 데이터가 어디에서 오고 저장되는지 확인한다

마지막 단계에서는 화면에 표시되는 데이터가 어디에서 오는지 확인한다.

다음 질문을 순서대로 적용하면 된다.

화면은 어떤 함수를 호출하는가?
그 함수는 브라우저에서 실행되는가, 서버에서 실행되는가?
외부 API 또는 내부 API를 호출하는가?
데이터베이스에 직접 접근하는가?
사용자의 로그인과 권한을 어디에서 확인하는가?
오류가 발생하면 어떤 결과를 반환하는가?

데이터 관련 코드는 db, database, api, services, server, actions 또는 lib 폴더에 있을 수 있다.

Supabase나 Firebase 같은 서비스를 사용한다면 클라이언트를 생성하는 파일도 찾아야 한다. 브라우저용 클라이언트와 서버용 클라이언트가 구분돼 있는지 확인하는 것이 중요하다.

public 폴더에서는 정적 파일을 확인한다

public 폴더에는 이미지, 아이콘, 글꼴과 다운로드 파일처럼 서버가 그대로 제공하는 정적 파일이 들어간다.

Next.js에서는 public/profile.png 파일을 코드에서 /profile.png처럼 사용할 수 있다. Next.js 설치 및 public 폴더 안내

공개되면 안 되는 문서, 백업 파일, 데이터 파일과 API 키를 public 폴더에 넣어서는 안 된다. 이 폴더의 파일은 주소를 아는 사용자가 직접 접근할 수 있다고 생각하는 것이 안전하다.

테스트 폴더는 실제 요구사항을 이해하는 단서다

tests, test, __tests__, e2e 폴더가 있다면 해당 프로젝트가 무엇을 정상 동작으로 판단하는지 확인할 수 있다.

테스트 이름과 내용을 보면 회원가입, 로그인, 결제와 권한 기능이 어떤 조건을 만족해야 하는지 파악하기 쉽다.

AI가 만든 프로젝트에서는 테스트 파일이 실제 기능과 일치하지 않을 수도 있다. 테스트가 존재한다는 이유만으로 신뢰하지 말고 실제 코드와 함께 확인해야 한다.

이해하지 못한 폴더를 AI에게 물어보는 방법

AI에게 프로젝트 전체를 설명해 달라고만 요청하면 파일 목록을 나열하거나 일반적인 설명을 제공할 수 있다. 변경 없이 구조만 분석하도록 범위를 명확하게 지정하는 것이 좋다.

다음 프롬프트를 사용할 수 있다.

이 프로젝트의 코드는 수정하지 말고 폴더 구조만 분석해 줘.

다음 순서로 설명해 줘.
1. package.json을 기준으로 사용 기술과 실행 명령
2. 사용자에게 공개되는 페이지와 URL
3. 각 페이지가 사용하는 주요 컴포넌트
4. 로그인과 데이터 저장 기능의 실행 흐름
5. 서버 코드와 브라우저 코드의 구분
6. 환경변수가 사용되는 파일
7. 처음 검토해야 할 보안 관련 파일

자동 생성 폴더와 외부 패키지 코드는 제외해 줘.
확실하지 않은 역할은 추측하지 말고 “확인 필요”로 표시해 줘.
파일을 변경하거나 새 파일을 만들지 마라.

분석 결과에는 실제 파일 경로를 포함하도록 요청하는 것이 좋다. 설명만 있고 파일 근거가 없다면 AI가 프로젝트 구조를 일반적으로 추측했을 가능성이 있다.

프로젝트 구조를 이해할 때 사용할 질문

각 파일을 열었을 때 다음 네 가지 질문을 적용하면 된다.

이 파일은 누가 불러오는가?
이 파일은 어떤 다른 파일을 불러오는가?
브라우저와 서버 중 어디에서 실행되는가?
사용자 데이터나 권한에 영향을 주는가?

이 질문에 답할 수 있다면 파일 이름과 코드 전체를 완벽하게 이해하지 못해도 프로젝트 안에서의 역할을 파악할 수 있다.

폴더 구조를 임의로 정리하기 전에 주의할 점

AI에게 “폴더 구조를 깔끔하게 정리해 줘”라고 요청하면 많은 파일이 이동할 수 있다. 파일 경로가 바뀌면서 import 오류, 페이지 주소 변경과 빌드 실패가 발생할 수 있다.

프로젝트 구조를 이해하는 작업과 구조를 변경하는 작업은 분리해야 한다. 먼저 현재 구조를 문서로 정리하고 중복이나 문제를 확인한 뒤 작은 범위로 이동해야 한다.

파일을 이동하기 전에는 Git에 현재 상태를 기록하고 이동 후 타입 검사, 테스트와 운영 빌드를 실행해야 한다.

마무리

바이브 코딩 프로젝트의 폴더 구조는 모든 파일을 위에서부터 읽는 방식으로 이해할 필요가 없다.

먼저 package.json과 설정 파일에서 프로젝트의 기술 환경을 확인한다. 다음으로 app, pages 또는 src에서 사용자가 보는 화면을 찾는다. 화면 파일의 import 경로를 따라 컴포넌트와 기능으로 이동하고 마지막으로 API와 데이터베이스 연결을 확인한다.

설정, 화면, 기능, 데이터 순서를 기억하면 복잡한 프로젝트에서도 어디에서 분석을 시작해야 할지 판단할 수 있다. AI가 생성한 코드를 이해하는 능력은 오류를 수정하고 안전하게 서비스를 운영하기 위한 첫 번째 단계다.