이전 시리즈에서 만든 프로젝트 폴더를 다시 열고 가만히 보면 내가 만들었는데 어디서 부터 봐야 할지 모른다. app/, components/, lib/ — 폴더 이름이 영어라서 더 그렇다. 파일이 10개 정도 넘는 순간부터 그 느낌이 온다.
솔직히 이 시점에서 파일 개수가 무섭다. 잘못 건드리면 뭔가 망가질 것 같은 느낌. 그래서 건드리질 못한다. 특히 비개발자의 입장에서는 더욱 그렇다.
이번 편은 그 두려움을 없애는 게 목표다. Next.js 폴더 구조가 처음으로 "어디가 어디인지" 보이기 시작하는 경험.
먼저 AI에게 폴더 지도를 받아라
직접 파일을 하나하나 열어보기 전에, AI에게 지도를 먼저 받는 게 훨씬 빠르다.
VSCode에서 프로젝트를 열고, 좌측 파일 트리에서 폴더 구조를 확인하거나, 터미널에 아래 명령어를 입력하면 전체 구조를 텍스트로 뽑을 수 있다.
tree /f /a | more
참고: 터미널이 PowerShell이 아닌 경우 VSCode 하단 터미널에서
+버튼 옆 드롭다운을 클릭해 PowerShell을 선택하면 된다. 결과가 너무 길면node_modules폴더는 파일 트리에서 직접 접어두고 나머지만 캡처해도 충분하다.
명령어가 낯설어도 괜찮다. 결과만 전체 복사해서 AI에게 이렇게 넘긴다.
내 프로젝트 폴더 구조를 아래에 붙여넣을게.
각 파일과 폴더가 어떤 역할을 하는지,
중학생도 이해할 수 있는 수준으로 한 줄씩 설명해줘.
이렇게 하면 AI가 파일 하나하나를 설명해준다. 처음엔 설명이 길어 보여도 괜찮다. 지금은 전체 지형을 보는 단계다.
실제 폴더 구조는 이렇게 생겼다
시즌 1 메모 앱 기준으로 Next.js 폴더 구조는 대략 이런 모습이다.
my-memo-app/
├── app/
│ ├── page.tsx ← 메인 화면
│ ├── layout.tsx ← 전체 레이아웃
│ └── api/
│ └── memos/
│ └── route.ts ← 메모 저장/불러오기 API
├── components/
│ └── MemoCard.tsx ← 메모 카드 컴포넌트
├── lib/
│ └── supabase.ts ← Supabase 연결 설정
├── public/ ← 이미지 등 정적 파일
├── .env.local ← API 키 보관
├── next.config.js ← Next.js 설정
└── package.json ← 설치된 패키지 목록
처음엔 page.tsx, layout.tsx, route.ts가 전부 비슷해 보인다. 솔직히 파일 이름만 보면 누가 메인인지 감이 안 온다. 다들 .tsx 아니면 .ts로 끝나니까.
딱 세 구역으로 나눠서 보면 달라진다.
세 구역으로 나눠서 보는 법
구역 1 — 화면을 그리는 곳 (app/, components/)
사용자 눈에 보이는 것들이 여기 있다. page.tsx를 열면 화면에 뭐가 표시되는지 나온다. MemoCard.tsx는 메모 하나하나를 어떻게 보여줄지가 담겨 있다.
이 구역 파일을 수정하면 화면이 바뀐다.
구역 2 — 데이터를 주고받는 곳 (app/api/, lib/)
화면에서 "저장" 버튼을 누르면 어딘가에 데이터가 가야 한다. 그 경로가 여기다. route.ts는 "저장 요청이 오면 이렇게 처리해라"는 규칙이 담겨 있다. lib/supabase.ts는 Supabase 서비스에 연결하는 설정이다.
여기 잘못 건드리면 저장 버튼이 갑자기 죽는다. 눌러도 아무 반응이 없어지는 것. 처음엔 왜 그런지 감도 안 잡힌다.
구역 3 — 설정 파일들 (.env.local, next.config.js, package.json)
앱이 돌아가기 위한 환경 설정이 여기 모여 있다. .env.local은 Supabase API 키처럼 외부에 노출되면 안 되는 값들이 들어간다.
.env.local에서 많이 겪는 실수가 있다. 값을 수정하고 저장했는데 반영이 안 된다. 이 파일은 수정 후 개발 서버를 재시작해야 적용된다. npm run dev를 다시 실행해야 한다는 뜻이다. 이걸 몰라서 한참 헤매는 경우가 꽤 있다.
파일 이름만 봐도 감이 오기 시작하는 패턴
개발 세계에는 파일 이름을 짓는 암묵적인 규칙이 있다. 처음부터 전부 외울 필요 없고, 자주 보이는 패턴만 알아두면 된다.
| 파일/폴더 이름 | 대체로 이런 역할 |
|---|---|
page.tsx |
해당 경로의 화면 |
layout.tsx |
여러 페이지에 공통으로 적용되는 틀 |
route.ts |
API 요청을 받아서 처리하는 곳 |
lib/ |
공통으로 쓰는 함수·설정 모음 |
components/ |
재사용 가능한 화면 조각들 |
utils/ |
자잘한 도우미 함수들 |
.env |
비밀 키·설정값 보관 |
types.ts |
데이터 형태 정의 |
lib/는 처음 보면 거의 마법 폴더다. 뭘 하는 곳인지 이름만으로는 감이 안 온다. 근데 열어보면 대부분 "여기저기서 공통으로 쓰는 설정이나 함수"가 모여 있다. supabase.ts가 lib/ 안에 있는 이유가 그거다.
이 목록을 외우는 게 목적이 아니다. 낯선 파일 이름을 봤을 때 "이 이름 어디서 봤지" 하는 감이 생기기 시작하는 것.
공식 문서와 실제 프로젝트가 달라 보이는 이유
Next.js 공식 문서를 처음 보면 폴더 구조가 굉장히 깔끔하다. 파일이 5~6개밖에 없다.
실제로 AI가 만들어준 프로젝트를 열면 파일이 20개가 넘는다.
이 차이 때문에 "내가 뭔가 잘못 만든 건가" 싶어지는 경우가 많다. 잘못 만든 게 아니다. 공식 문서는 최소한의 구조만 보여주고, 실제 프로젝트는 기능이 붙을수록 파일이 자연스럽게 늘어난다. AI가 처음부터 "나중에 쓸 것 같은" 파일을 미리 만들어주기도 한다.
모르는 파일이 있어도 괜찮다. "이 파일 뭐야?" 하고 AI에게 바로 물어보면 된다.
이전 시즌에 만들어 놓고 "이게 뭐였지" 싶었던 파일들이 이제 조금 다르게 보이기 시작했다면 충분하다.
전부 알 필요 없다. 어디가 화면이고 어디가 데이터인지 구역이 보이기 시작하는 것. 그게 이번 편의 전부다.
→ [2편: 함수가 보이기 시작한다 — 코드 덩어리에서 기능 단위를 구분하는 첫 경험](준비 중)
← 이전 글: 시즌 2를 시작하기 전에 — AI 코딩 입문 다음 단계는 "코드 읽기"였다
바이브 코딩 시리즈는 비개발자가 AI와 협업해 실제 서비스를 만들어가는 과정을 기록합니다.
댓글 쓰기