VS Code 폴더 구조 읽는 법 - 비개발자가 알아야 할 것만 골라서 정리했습니다

VS Code를 열었더니 파일이 수십 개

😵 비개발자가 VS Code를 처음 열었을 때

npm install도 했고, npm run dev도 실행했습니다. 앱이 브라우저에서 잘 됩니다.

그런데 VS Code 왼쪽 파일 목록을 보니 폴더가 10개, 파일이 수십 개입니다.

app/? components/? lib/? public/? 이게 다 뭔가?

AI가 "Button.tsx 파일을 수정하세요"라고 했습니다. Button.tsx가 어디에 있는지 찾는 데 5분이 걸렸습니다.

다음에는 AI가 "api/route.ts를 확인하세요"라고 했습니다. api 폴더가 app 안에 있는 건지, 밖에 있는 건지 모르겠습니다.

처음에는 프로젝트 안 파일의 90%를 몰라도 됩니다. 중요한 건 "어느 파일이 화면에 연결되는가" 정도만 아는 것입니다. 폴더 구조를 이해한다는 것은 개발자가 된다는 뜻이 아닙니다. "AI가 어디를 수정해야 하는지 알려줄 수 있게 된다"는 뜻입니다.

이 글은 처음으로 개발을 시작해서 저와 비슷한 시행 착오를 겪고 계시는 분들을 위해 작성한 바이브 코딩에 필요한 기본적인 개념 정리 글들과 함께 지금까지 만들어온 VS Code 환경(Node.js, 터미널, npm)의 마지막 퍼즐입니다. 환경이 갖춰졌으니 이제 그 안을 어떻게 읽는지 알아봅니다. 그리고 이 지식은 이전 AI 수정 요청법에서 배운 AI 수정 요청 구조화와 직접 연결됩니다.

전체 구조 한눈에 보기

AI가 만든 Next.js 프로젝트의 일반적인 폴더 구조입니다. 모든 프로젝트가 똑같지는 않지만, 바이브 코딩으로 만든 앱의 80% 이상이 이 구조와 비슷합니다.

VS Code — 프로젝트 폴더 구조

📁 my-app/

├── 📁 app/ ← URL 주소 = 화면. 가장 자주 보게 되는 곳

│ ├── page.tsx ← 홈(/) 화면

│ ├── layout.tsx ← 모든 페이지 공통 틀 (헤더·푸터 등)

│ └── 📁 api/ ← 서버 로직 (AI·DB 연결)

├── 📁 components/ ← 레고 블록 모음. 버튼·카드·헤더 등

├── 📁 public/ ← 이미지·아이콘 파일 넣는 곳

├── 📁 lib/ ← 공통 함수·유틸리티 모음

├── 📁 styles/ ← 전역 CSS (있는 프로젝트도, 없는 프로젝트도)

├── 📄 .env ← API 키 보관. 절대 GitHub에 올리지 않음

├── 📄 package.json ← 패키지 목록 (8편에서 다룸)

├── 📁 node_modules/ ← 패키지 창고 (8편에서 다룸, 건드리지 않음)

└── 📄 next.config.js ← Next.js 설정 (AI가 관리)

💡 처음엔 이 3개만 알면 됩니다

app/ — URL과 화면을 담당. components/ — 화면 조각 모음. public/ — 이미지 파일 넣는 곳. 이 3개만 알아도 AI와의 수정 요청 대화에서 막히지 않습니다.

⚠️ 알아두면 좋은 것 — AI도 파일 구조를 보고 판단합니다

AI는 파일 이름과 폴더 위치를 보고 역할을 추론합니다. 구조가 정리된 프로젝트일수록 AI 수정 정확도도 높아집니다. 반대로 파일 위치를 지정하지 않으면 AI는 새 파일을 임의 위치에 만들 수 있습니다. 이것이 프로젝트 구조가 꼬이는 가장 흔한 원인 중 하나입니다. 폴더 구조를 아는 것이 AI 폭주를 막는 첫 번째 방어선입니다.

VS Code 파일 탐색기 — 바이브 코딩 프로젝트 폴더 구조 설명

폴더별 역할 완전 정리

아래 카드를 모두 외울 필요는 없습니다. AI가 특정 파일을 언급할 때 "아, 저 폴더구나"가 떠오를 정도면 충분합니다.

📱 app/ 가장 자주 봄

URL 주소와 화면을 연결하는 핵심 폴더입니다. 폴더 이름 = URL 경로가 됩니다.

작동 원리 app/page.tsx → / (홈)
app/about/page.tsx → /about

layout.tsx 모든 페이지에 공통으로 들어가는 틀. 헤더·푸터·네비게이션이 여기 있습니다.

api/ 폴더 app/ 안에 있는 경우가 많습니다. AI API 연결, 데이터베이스 처리 같은 서버 로직이 여기에 생깁니다.

💡 AI가 "새 페이지를 추가했습니다"라고 하면 → app/ 안에 새 폴더가 생긴 것

🧩 components/ 가장 자주 수정

화면을 구성하는 레고 블록들이 모여 있는 폴더입니다. 버튼, 카드, 헤더, 모달 같은 재사용 가능한 화면 조각들이 여기에 있습니다. 2편에서 배운 "컴포넌트 = 화면 조각"이 실제로 있는 곳입니다.

파일 예시 Button.tsx, Card.tsx, Header.tsx, Modal.tsx

AI 요청 시 AI가 "Button 컴포넌트를 수정했습니다"라고 하면 → components/Button.tsx를 확인

💡 디자인 수정 요청의 90%는 components/ 안 파일과 관련됩니다

🖼️ public/ 직접 파일 넣기

이미지, 아이콘, 폰트 등 정적 파일을 넣는 폴더입니다. 비개발자가 직접 파일을 넣어야 하는 유일한 폴더입니다.

사용 방법 public/logo.png를 넣으면 코드에서 src="/logo.png"로 접근

AI 요청 "public 폴더에 logo.png를 넣었어. 헤더 왼쪽에 표시해줘"라고 하면 AI가 코드를 만들어줌

💡 이미지가 화면에 안 보인다면 → public/ 폴더에 파일이 제대로 있는지 먼저 확인

🔧 lib/ · utils/ 이름만 알면 됨

여러 파일에서 공통으로 쓰는 함수나 도구들을 모아두는 폴더입니다. AI가 Supabase 연결 코드나 날짜 처리 함수를 만들 때 주로 이 폴더에 파일을 만듭니다.

내용 예시 Supabase 클라이언트 설정, 날짜 형식 변환 함수, API 요청 공통 함수

직접 수정 입문 단계에서는 직접 수정하지 않습니다. AI가 알아서 관리합니다.

🔑 .env (파일) 보안 필수

API 키, 데이터베이스 주소 같은 민감한 정보를 코드에 직접 쓰지 않고 여기에 보관합니다. 4편(GitHub)에서 다룬 것처럼 절대 GitHub에 올리면 안 됩니다.

형식 NEXT_PUBLIC_SUPABASE_URL=https://...
OPENAI_API_KEY=sk-...

주의 .env 파일은 VS Code에서 보이지만 GitHub에 올리면 키가 공개됩니다. .gitignore를 반드시 확인하세요.

💡 AI가 "환경 변수를 설정하세요"라고 하면 → .env 파일에 AI가 알려주는 형식 그대로 추가

📄 pages/ (구버전) 이름만 알면 됨

Next.js 12 이하 버전이나 일부 프로젝트에서 app/ 대신 pages/ 폴더를 씁니다. 역할은 같습니다. URL 주소와 화면을 연결합니다.

app/ 과 차이 구조가 약간 다르지만 비개발자 입장에서는 거의 동일. AI가 어느 방식인지 판단하고 알맞게 작업합니다.

💡 프로젝트에 app/이 없고 pages/가 있다면 → 이전 방식의 프로젝트. 동작은 같습니다.

Next.js app 폴더 방식 vs pages 폴더 방식 비교 — URL 라우팅 구조 차이 설명

파일을 빠르게 찾는 법 — Ctrl+P 하나로

AI가 "Button.tsx를 수정하세요"라고 했을 때 폴더를 하나씩 열어 찾을 필요가 없습니다. VS Code에는 파일을 이름으로 즉시 찾는 기능이 있습니다.

🔍 파일 빠른 열기 — 가장 자주 쓰는 단축키

Ctrl + P (Windows) → 파일 이름 검색창이 열립니다

Cmd + P (Mac) → 동일

단축키를 누르고 파일 이름(예: Button)을 입력하면 프로젝트 전체에서 해당 이름의 파일을 즉시 찾아줍니다. 폴더를 탐색할 필요가 없습니다.

이 단축키 하나만 알아도 AI가 어떤 파일을 언급하든 5초 안에 열 수 있습니다. 폴더 구조를 외우는 것보다 훨씬 실용적입니다.

💡 Ctrl+Shift+F — 내용으로 파일 찾기

파일 이름을 모를 때도 있습니다. 예를 들어 AI가 "로그인 버튼 색상을 바꿨습니다"라고 했을 때 어느 파일인지 모르면, Ctrl+Shift+F(Mac: Cmd+Shift+F)로 "LoginButton"이나 "로그인"을 검색하면 해당 텍스트가 있는 모든 파일을 찾아줍니다.

AI 수정 요청할 때 폴더 구조 활용하기

5편(AI 수정 요청법)에서 "수정할 파일을 명시하라"고 배웠습니다. 이제 폴더 구조를 알았으니 그 원칙을 실제로 적용할 수 있습니다. 폴더 구조를 아는 것이 수정 요청의 품질을 얼마나 높이는지 비교해 보겠습니다.

🎯 바이브 코딩에서 폴더 구조를 아는 것의 실제 의미:
수정할 파일을 지정할 수 있다 → AI가 그 파일만 수정한다 → 의도치 않은 변경이 줄어든다 → 프로젝트 구조가 유지된다 → GitHub 복구 필요 상황이 줄어든다

📝 폴더 구조 알기 전 vs 후 — 수정 요청 품질 비교

❌ 폴더 구조 모를 때

헤더 색상 바꿔줘

→ AI가 어떤 파일을 수정할지 직접 판단 → 예상치 못한 파일까지 수정될 수 있음

✅ 폴더 구조 알 때

components/Header.tsx에서 배경색만 #1a1040으로 바꿔줘. 다른 파일은 건드리지 마.

→ AI가 정확히 해당 파일만 수정 → 의도치 않은 변경 없음

📝 새 페이지 추가 요청 예시

❌ 폴더 구조 모를 때

소개 페이지 만들어줘

→ AI가 파일 위치를 임의로 결정. 기존 구조와 맞지 않을 수 있음

✅ 폴더 구조 알 때

app/about/page.tsx 파일을 새로 만들어서 /about URL로 접근되는 소개 페이지 만들어줘. layout.tsx의 헤더 스타일은 그대로 유지해.

→ 원하는 위치에 정확하게 생성. 기존 레이아웃 보존

폴더 구조를 모를 때 vs 알 때 AI 수정 요청 품질 비교

건드려도 되는 것 vs 건드리지 말아야 할 것

비개발자 입문 단계에서 어떤 파일을 직접 수정해도 되고 어떤 파일은 AI에게 맡겨야 하는지 정리합니다.

✅ 직접 해도 괜찮은 것

• public/ — 이미지 파일 넣기, 교체
• .env — API 키 값 추가·수정
• components/ — AI와 함께 수정
• app/page.tsx — 텍스트 내용 수정
• GitHub 커밋·푸시

⚠️ AI에게 맡기는 것

• next.config.js — 설정 파일
• lib/ utils/ — 공통 함수
• app/api/ — 서버 로직
• tsconfig.json — TypeScript 설정
• node_modules/ — 절대 직접 수정 금지

@media (prefers-color-scheme: dark) { /* 다크모드에서도 잘 보이게 */ }

💡 모르는 파일이 나왔을 때

처음 보는 파일이나 폴더가 나왔을 때 가장 좋은 방법은 AI에게 물어보는 것입니다. "이 프로젝트에서 [파일명]이 어떤 역할인지, 지금 내가 수정해도 되는지 알려줘"라고 하면 됩니다. 구조를 외우는 것보다 물어보는 습관이 더 중요합니다.

📖 이 시리즈 함께 읽기
이전 글 → [[npm과 패키지 완전 정리 — AI가 npm install을 시킬 때 실제로 무슨 일이 일어나는가]] 다음 글 → [[비개발자를 위한 바이브 코딩 환경 30분 세팅 완전 가이드 — VS Code + Codex]]

📌 핵심 정리

• 비개발자가 바이브 코딩에서 가장 자주 보게 되는 폴더 3개는 app/(URL·화면), components/(화면 조각), public/(이미지 파일)입니다. 이 3개만 알아도 AI와의 수정 요청 대화에서 막히지 않습니다.
• app/ 폴더 안의 구조가 URL 주소가 됩니다. app/about/page.tsx 파일이 있으면 /about 주소로 접근됩니다. 새 페이지를 만들 때 AI에게 "app/경로/page.tsx 파일 만들어줘"라고 명시하면 정확하게 만들어줍니다.
• Ctrl+P(Mac: Cmd+P) 단축키로 파일 이름을 검색하면 폴더를 탐색하지 않아도 즉시 찾을 수 있습니다. 폴더 구조를 외우는 것보다 이 단축키를 익히는 것이 더 실용적입니다.
• 폴더 구조를 알면 AI 수정 요청의 품질이 크게 올라갑니다. "헤더 색상 바꿔줘" 대신 "components/Header.tsx에서 배경색만 바꿔줘"라고 하면 의도치 않은 수정을 방지할 수 있습니다.
• 직접 파일을 넣어야 하는 폴더는 public/뿐입니다. .env는 AI가 알려주는 형식 그대로 값만 추가합니다. node_modules/, next.config.js, tsconfig.json은 직접 수정하지 않습니다.

❓ 자주 묻는 질문

바이브 코딩에서 AI가 '이 컴포넌트를 수정하세요'라고 할 때 어느 폴더에서 찾으면 되나요?

components/ 폴더를 먼저 확인하세요. 버튼, 카드, 헤더처럼 화면을 구성하는 재사용 조각들이 여기에 있습니다. AI가 'Button.tsx를 수정하세요'라고 하면 components/Button.tsx를 찾으면 됩니다. 파일을 찾기 어려울 때는 VS Code 상단 검색(Ctrl+P 또는 Cmd+P)에 파일 이름을 입력하면 바로 찾을 수 있습니다.

Next.js 프로젝트에서 app 폴더와 pages 폴더의 차이가 뭔가요?

둘 다 URL 주소와 화면을 연결하는 폴더입니다. 최신 Next.js(13 버전 이상)는 app/ 폴더 방식을 기본으로 씁니다. 이전 버전이나 일부 프로젝트는 pages/ 폴더 방식을 씁니다. AI가 프로젝트를 만들 때 어느 방식을 쓸지 자동으로 선택합니다. 비개발자는 '이 폴더 안의 파일 이름이 URL 주소가 된다'는 것만 알면 충분합니다.

public 폴더에 이미지를 넣으면 코드에서 어떻게 사용하나요?

public/ 폴더에 넣은 파일은 /파일명 형태로 바로 접근할 수 있습니다. 예를 들어 public/logo.png를 넣었다면 코드에서 src='/logo.png'로 쓰면 됩니다. AI에게 '이 이미지를 헤더에 넣어줘'라고 하면서 파일명을 알려주면 AI가 코드를 만들어줍니다.

lib 폴더와 utils 폴더는 무엇이고 건드려도 되나요?

lib/와 utils/는 여러 파일에서 공통으로 쓰는 함수나 도구들을 모아두는 폴더입니다. 날짜 형식 변환, 데이터 정리, API 연결 함수 등이 여기에 있습니다. 바이브 코딩 입문 단계에서는 직접 수정할 일이 거의 없습니다. AI가 새 기능을 추가할 때 여기에 파일을 만드는 경우가 있는데, 그때는 AI가 알아서 처리합니다.

지금 VS Code에서
Ctrl+P를 눌러보세요

파일 검색창이 열립니다. "Button"이라고 입력해보세요.
components/ 안의 파일들이 나타납니다.
폴더를 탐색하지 않아도 됩니다. 이것만으로 충분합니다.

🖥️ VS Code 열기