14장. 프로젝트 생성과 폴더 구조 이해하기

지난 장에서 우리는 개발을 시작할 작업실을 준비했습니다. 브라우저, VS Code, 터미널, Node.js, Git, GitHub까지 갖췄으니 이제 책상 위에 진짜 작업물을 올릴 차례입니다. 바로 프로젝트입니다.

초보자에게 프로젝트 생성은 종종 마법처럼 느껴집니다. 명령어 한 줄을 입력했더니 갑자기 폴더가 우르르 생기고, 처음 보는 파일들이 쏟아집니다. 이때 많은 사람이 이렇게 생각합니다.

"이 많은 것 중에 건드리면 안 되는 게 뭘까?"

하지만 조금만 감을 잡으면 생각보다 단순합니다. 프로젝트는 복잡한 미로가 아니라, 웹 서비스를 만들기 위한 정리된 작업 상자입니다. 그리고 그 상자 안에서 무엇이 어디에 있는지만 알아도, AI가 코드를 바꿔도 훨씬 덜 무섭게 볼 수 있습니다.

이번 장의 목표는 두 가지입니다. Next.js 프로젝트를 직접 만들고, 자주 보게 될 폴더와 파일의 역할을 감각적으로 익히는 것입니다. 모든 파일을 완벽히 외울 필요는 없습니다. 대신 "아, 이건 화면 쪽이구나", "이건 설정 파일이구나", "이건 이미지 넣는 곳이구나" 정도만 읽혀도 아주 큰 진전입니다.

프로젝트를 만든다는 것은 뼈대를 세우는 일이다

웹 서비스를 만들 때 처음부터 모든 파일을 손으로 하나씩 만들 필요는 없습니다. Next.js는 create-next-app이라는 공식 도구를 통해 기본 구조를 한 번에 만들어 줍니다. 쉽게 말해, 빈 공터에서 집을 짓기 전에 골조를 먼저 세워주는 장비라고 생각하면 됩니다.¹

이 장에서는 Next.js의 최신 권장 방식인 App Router 기준으로 진행합니다. App Router는 폴더 구조가 곧 URL 구조가 되는 라우팅 방식입니다. 이름은 조금 딱딱하지만, 초보자에게는 오히려 더 직관적입니다. 폴더 이름만 봐도 어떤 주소가 생길지 짐작할 수 있기 때문입니다.²

create-next-app으로 첫 프로젝트 만들기

가장 간단한 방법은 아래 명령어로 프로젝트를 만드는 것입니다.

npx create-next-app@latest first-fullstack-service --typescript --eslint --tailwind --app --src-dir --use-npm

명령어가 길어 보여도 겁먹지 않아도 됩니다. 사실은 "타입스크립트 쓰고, 코드 검사 도구 넣고, 스타일 도구 넣고, App Router 쓰고, 코드는 src 안에 넣고, npm으로 설치해줘"라고 한 줄로 부탁한 것입니다.¹

프로젝트가 만들어졌다면 아래처럼 폴더로 들어가 개발 서버를 실행합니다.

cd first-fullstack-service
npm run dev

이제 브라우저에서 http://localhost:3000을 열면 기본 화면이 보입니다. 이 순간이 꽤 중요합니다. 아직 대단한 서비스를 만든 것은 아니지만, 내 컴퓨터에서 돌아가는 웹 프로젝트가 하나 생긴 것이기 때문입니다.²

만약 대화형 질문이 뜬다면 너무 긴장하지 마세요. 보통 이런 선택지를 만나게 됩니다.

• TypeScript 사용 여부

• ESLint 사용 여부

• Tailwind CSS 사용 여부

• src/ 디렉터리 사용 여부

• App Router 사용 여부

• import alias 설정 여부

이 책에서는 TypeScript, ESLint, Tailwind CSS, App Router를 사용하는 쪽으로 설명하겠습니다. 그리고 src/ 디렉터리도 켜는 쪽을 추천합니다. 이유는 단순합니다. 프로젝트 루트가 덜 어수선해지고, 설정 파일과 실제 코드를 눈으로 구분하기 쉬워지기 때문입니다.¹³

처음 보이는 폴더 구조는 이렇게 읽으면 된다

프로젝트를 만들고 나면 대략 아래와 비슷한 모습이 보일 것입니다. 버전과 선택 옵션에 따라 조금씩 다를 수 있지만, 큰 흐름은 비슷합니다.

first-fullstack-service/
├── public/
├── src/
│   └── app/
│       ├── favicon.ico
│       ├── globals.css
│       ├── layout.tsx
│       └── page.tsx
├── .gitignore
├── AGENTS.md
├── CLAUDE.md
├── eslint.config.mjs
├── next-env.d.ts
├── package.json
├── tsconfig.json
└── next.config.ts

처음 보면 파일이 많아 보여도, 사실 크게 네 덩어리로 나누면 됩니다.

첫째, 실제 화면과 기능 코드가 들어가는 곳이 있습니다. 보통 src/app 아래입니다.

둘째, 정적 파일을 넣는 곳이 있습니다. public 폴더입니다.

셋째, 프로젝트 설정 파일들이 있습니다. package.json, tsconfig.json, eslint.config.mjs, next.config.ts 같은 것들입니다.

넷째, 도구와 협업을 위한 파일이 있습니다. .gitignore, 그리고 최근 템플릿에서는 AI 코딩 도구를 위한 AGENTS.md와 CLAUDE.md 같은 파일이 포함되기도 합니다.²

이렇게만 나눠도 갑자기 훨씬 덜 복잡해집니다. 폴더 구조를 다 외우는 것이 아니라, "어느 구역이 어떤 역할인지" 먼저 보는 것이 핵심입니다.

루트 폴더에서는 무엇을 먼저 보면 좋을까

프로젝트 맨 위, 즉 루트 폴더에는 주로 설정과 규칙이 모여 있습니다. 여기서 가장 자주 마주칠 파일 몇 개만 먼저 익혀봅시다.

package.json

package.json은 프로젝트 소개서이자 제어판입니다. 이 파일에는 프로젝트 이름, 설치한 라이브러리, 실행 명령어가 들어 있습니다. 예를 들어 npm run dev, npm run build 같은 명령은 대부분 이 파일에 적혀 있습니다.²

초보자 입장에서 package.json은 이렇게 이해하면 충분합니다. "이 프로젝트가 어떤 재료를 쓰고, 어떤 버튼으로 실행되는지 적어둔 파일."

AI가 package.json을 바꿨다면 대개 둘 중 하나입니다. 새 라이브러리를 추가했거나, 실행 스크립트를 바꿨거나입니다. 그러면 덜 무섭습니다. 최소한 어디서 무슨 변화가 일어났는지 감이 오기 때문입니다.

tsconfig.json

이 파일은 TypeScript 설정 파일입니다. 처음에는 세부 옵션을 읽을 필요가 없습니다. 다만 이 파일이 있으면 "아, 이 프로젝트는 타입스크립트 규칙을 따르는구나" 정도만 알면 됩니다.²

eslint.config.mjs

이 파일은 코드 품질 검사 규칙을 담고 있습니다. 쉽게 말해, 코드가 너무 지저분하거나 위험한 방식으로 작성되지 않도록 잔소리해주는 파일입니다. 약간 엄격한 선생님 같지만, 초보자에게는 꽤 든든한 존재입니다.²

next.config.ts

이 파일은 Next.js 프로젝트의 동작 방식을 조정하는 설정 파일입니다. 이미지 설정, 빌드 방식, 특정 실험 기능 같은 것을 만질 때 등장합니다. 자주 수정하진 않지만, 나중에 배포나 외부 서비스 연동을 할 때 한 번씩 만나게 됩니다.³

.gitignore

이 파일은 Git에게 "이건 기록하지 마"라고 알려주는 목록입니다. 예를 들어 설치된 패키지 폴더나 로컬 환경 파일은 보통 여기에서 제외합니다. 아직 Git을 깊게 배우지 않았더라도, 이 파일이 있다는 것은 쓸데없이 무거운 파일을 저장소에 올리지 않게 막아주는 안전장치라고 이해하면 됩니다.

AGENTS.md와 CLAUDE.md

최근 create-next-app 템플릿에는 AI 코딩 에이전트가 프로젝트 규칙을 읽을 수 있도록 돕는 파일이 포함될 수 있습니다. 이것은 이 책의 주제와도 잘 맞습니다. 사람이 팀 규칙 문서를 읽듯이, Claude Code 같은 도구도 이런 파일을 참고해 프로젝트 맥락을 더 잘 이해하게 됩니다.²

즉, 이 파일들은 "AI에게도 온보딩 문서가 필요하다"는 시대의 흔적이라고 볼 수 있습니다. 꽤 재밌지요.

src 폴더와 app 폴더의 차이부터 잡자

초보자가 가장 자주 헷갈리는 질문 중 하나가 이것입니다.

"src와 app는 뭐가 다른가요?"

답은 간단합니다.

src는 소스 코드를 모아두는 큰 상자입니다. 선택 사항이지만, 프로젝트 루트와 코드를 분리해 정리하기 좋아서 많이 사용합니다.²³

그 안의 app은 라우팅과 페이지 구조를 담당하는 핵심 폴더입니다. 여기서는 폴더 구조가 URL 구조와 연결됩니다. 즉, app/about/page.tsx가 있으면 /about 주소가 생기는 식입니다.³

그래서 감각적으로는 이렇게 이해하면 됩니다.

• src는 코드가 사는 동네

• app은 웹사이트 지도를 그리는 구역

이 구분이 잡히면 폴더를 볼 때 훨씬 덜 헷갈립니다.

app 폴더는 웹사이트의 지도다

Next.js의 App Router에서는 app 폴더가 아주 중요합니다. 이 안에서는 몇몇 파일 이름이 특별한 의미를 가집니다. 초보자에게는 이것이 외워야 할 주문처럼 느껴질 수 있지만, 사실 역할만 알면 됩니다.³

자주 보게 될 것들만 먼저 정리해보면 이렇습니다.

• page.tsx: 해당 주소에서 보여줄 실제 화면

• layout.tsx: 여러 페이지를 감싸는 공통 틀

• loading.tsx: 불러오는 동안 보여줄 화면

• error.tsx: 해당 구간에서 에러가 났을 때 보여줄 화면

• not-found.tsx: 없는 페이지일 때 보여줄 화면

• route.ts: API처럼 서버 동작을 만드는 파일

• [id] 같은 폴더: 동적인 주소를 나타내는 폴더

• (group) 같은 폴더: URL에는 드러나지 않는 정리용 그룹

• _components 같은 폴더: 라우팅 대상이 아닌 내부 구현용 폴더

여기서 중요한 포인트는 딱 하나입니다. 폴더 이름과 파일 이름이 Next.js에게 의미를 전달한다는 점입니다. 그냥 마음대로 main.tsx, screen.tsx라고 짓는 방식이 아닙니다. 그래서 처음에는 자유도가 낮아 보일 수 있지만, 대신 구조를 읽기가 훨씬 쉬워집니다.³

예를 들어 아래 구조를 봅시다.

src/app/
├── page.tsx
├── login/
│   └── page.tsx
├── posts/
│   ├── page.tsx
│   └── [id]/
│       └── page.tsx
└── api/
    └── posts/
        └── route.ts

이 구조만 봐도 꽤 많은 것을 읽어낼 수 있습니다.

• / 주소의 홈 화면이 있다.

• /login 로그인 화면이 있다.

• /posts 글 목록 화면이 있다.

• /posts/123 같은 상세 화면이 있다.

• /api/posts라는 서버 엔드포인트가 있다.

아직 코드를 한 줄도 읽지 않았는데도 여기까지 보입니다. 바로 이 감각이 중요합니다.

page.tsx와 layout.tsx는 특히 자주 본다

입문 단계에서 가장 자주 만나는 파일은 사실상 page.tsx와 layout.tsx입니다.

page.tsx는 말 그대로 그 주소의 본문입니다. 사용자가 실제로 보게 될 화면이 여기에서 시작됩니다. 홈 화면이라면 src/app/page.tsx, 글 목록이라면 src/app/posts/page.tsx처럼 들어갑니다.³

반면 layout.tsx는 공통 프레임입니다. 예를 들어 모든 페이지에 같은 헤더와 푸터를 보여주고 싶다면 layout.tsx에서 감싸줍니다. 루트의 layout.tsx는 특히 중요합니다. Next.js App Router에서는 루트 레이아웃이 필요하며, 여기에는 <html>과 <body>가 포함됩니다.²

쉽게 비유하면 이렇습니다.

layout.tsx는 건물의 공용 복도이고, page.tsx는 각 방의 내부입니다.

공용 복도는 비슷하게 유지되고, 방마다 내용이 달라지는 것이죠.

public 폴더는 코드보다 자산에 가깝다

public 폴더는 이미지, 아이콘, 폰트처럼 정적 파일을 넣는 곳입니다. 여기에 넣은 파일은 웹사이트 루트 경로에서 바로 접근할 수 있습니다. 예를 들어 public/logo.png 파일은 코드에서 /logo.png처럼 사용할 수 있습니다.²³

이 폴더를 보면 보통 다음 같은 파일이 들어갑니다.

• 로고 이미지

• 기본 아이콘 파일

• 배경 이미지

• 폰트 파일

초보자는 종종 이미지를 아무 폴더나 넣고 왜 안 보이는지 당황합니다. 그럴 때 가장 먼저 떠올리면 좋은 곳이 바로 public입니다.

감각적으로 말하면, public은 "코드가 아니라 재료를 보관하는 창고"입니다.

앞으로 우리가 자주 추가하게 될 폴더들

기본 템플릿만으로도 프로젝트는 실행됩니다. 하지만 실제 서비스를 만들기 시작하면 파일이 금방 늘어납니다. 그때 아무 생각 없이 app 안에 모든 것을 몰아넣으면, 처음에는 편해 보여도 나중에 꽤 복잡해집니다.

Next.js 공식 문서는 app을 라우팅 중심으로 두고, 나머지 공유 코드는 바깥 폴더에 둘 수도 있다고 설명합니다.³ 이 책도 그 감각을 따라가겠습니다.

예를 들어 프로젝트가 조금 자라면 이런 구조를 자주 보게 됩니다.

src/
├── app/
├── components/
├── lib/
├── styles/
└── types/

각 폴더는 대체로 이렇게 생각하면 됩니다.

components

버튼, 입력창, 카드, 헤더처럼 화면 조각을 모아두는 곳입니다. 여러 페이지에서 재사용할 수 있는 UI를 넣습니다.

lib

유틸 함수, 외부 서비스 연결, 데이터 처리처럼 화면 바깥의 공통 로직을 두는 곳입니다. 예를 들어 날짜를 예쁘게 바꾸는 함수나 Supabase 클라이언트 설정 같은 것이 들어갈 수 있습니다.

styles

전역 스타일이나 공통 스타일 파일을 모아두는 곳입니다. 기본 템플릿에서는 globals.css가 app 안에 있을 수 있지만, 프로젝트가 커지면 스타일을 따로 정리하고 싶어질 때가 있습니다.

types

타입스크립트 타입을 모아두는 곳입니다. 예를 들어 게시글 데이터 구조, 사용자 정보 구조 같은 것을 파일로 정리하게 됩니다.

물론 폴더 구조에는 절대 정답이 없습니다. 중요한 것은 멋진 구조보다 찾기 쉬운 구조입니다. 그리고 팀과 AI가 함께 일할 때는, 그 찾기 쉬움이 생산성을 크게 바꿉니다.

AI가 바꾼 파일을 덜 무섭게 읽는 법

이 장의 핵심은 사실 여기입니다. 폴더 구조를 안다는 것은 단순히 정리 습관의 문제가 아닙니다. AI가 바꾼 내용을 읽을 수 있게 되는 문제입니다.

예를 들어 Claude Code나 Codex가 아래 파일들을 수정했다고 가정해봅시다.

• src/app/posts/page.tsx

• src/components/PostCard.tsx

• src/lib/posts.ts

• package.json

이제 폴더 구조를 모르면 그냥 공포 영화입니다. "어디를 어떻게 건드린 거지?"라는 생각만 듭니다.

하지만 구조를 알면 이렇게 읽힙니다.

src/app/posts/page.tsx는 글 목록 화면일 가능성이 큽니다.

src/components/PostCard.tsx는 글 하나를 보여주는 UI 조각일 가능성이 큽니다.

src/lib/posts.ts는 글 데이터를 다루는 공통 로직일 가능성이 큽니다.

package.json은 새 라이브러리를 추가했거나 실행 명령을 바꿨을 가능성이 큽니다.

즉, 코드를 다 해독하지 못해도 변경의 성격을 읽을 수 있게 됩니다. 이것만으로도 AI 협업의 체감 난이도가 크게 내려갑니다. 초보자에게 가장 필요한 것은 완벽한 이해가 아니라, "지금 어디에서 무슨 일이 일어났는지"를 아는 능력입니다.

폴더 구조를 읽는 가장 쉬운 순서

프로젝트를 열었을 때 저는 초보자에게 늘 같은 순서를 권합니다.

첫째, package.json을 봅니다. 이 프로젝트가 무엇으로 실행되는지 감이 잡힙니다.

둘째, src/app을 봅니다. 어떤 화면과 주소가 있는지 보입니다.

셋째, public을 봅니다. 이미지와 정적 파일이 어디 있는지 알 수 있습니다.

넷째, components나 lib가 있다면 그 구조를 봅니다. 화면 조각과 공통 로직이 어디에 모이는지 보입니다.

이 순서가 좋은 이유는, 큰 지도에서 작은 부품으로 내려가는 방식이기 때문입니다. 처음부터 개별 함수에 파고들면 금방 길을 잃습니다. 하지만 루트 → 라우팅 → 자산 → 공통 코드 순으로 보면 프로젝트가 훨씬 질서 있게 보입니다.

꼭 기억해야 할 몇 가지 오해

이쯤에서 초보자가 자주 하는 오해도 정리해두겠습니다.

첫째, 폴더가 많다고 어려운 프로젝트는 아닙니다. 오히려 잘 나뉜 폴더는 프로젝트가 친절하게 정리되어 있다는 뜻일 때가 많습니다.

둘째, app 안의 모든 폴더가 자동으로 공개 주소가 되는 것은 아닙니다. 실제로 라우트가 되려면 보통 page.tsx나 route.ts 같은 특수 파일이 있어야 합니다.³

셋째, 구조에는 정답이 하나만 있는 것이 아닙니다. 다만 초보자에게 좋은 구조는 있습니다. 한눈에 역할이 보이는 구조입니다.

넷째, AI가 바꿨다고 해서 모든 파일을 다 뜯어볼 필요는 없습니다. 어느 폴더의 어떤 종류 파일이 바뀌었는지 먼저 보고, 중요한 변화부터 확인하면 됩니다.

오늘 여기까지 읽히면 충분하다

이번 장을 마친 뒤 아래가 자연스럽게 느껴진다면 아주 잘 따라온 것입니다.

• Next.js 프로젝트는 create-next-app으로 시작할 수 있다.

• package.json은 프로젝트의 재료와 실행 버튼을 담고 있다.

• src/app은 화면과 주소 구조를 만드는 핵심 구역이다.

• page.tsx는 화면, layout.tsx는 공통 틀에 가깝다.

• public은 이미지 같은 정적 파일 창고다.

• components, lib, types 같은 폴더는 프로젝트가 자라면서 자연스럽게 등장한다.

• 폴더 구조를 읽을 수 있으면 AI가 바꾼 파일도 훨씬 덜 두렵다.

지금은 모든 파일을 완벽히 이해하지 못해도 괜찮습니다. 중요한 것은 프로젝트를 봤을 때 "완전히 외계어는 아니다"라는 감각을 갖는 것입니다. 그 감각이 생기면, 이제부터는 파일을 열고 수정하고 저장하는 일이 훨씬 현실적으로 느껴집니다.

다음 장에서는 이 프로젝트를 안전하게 기록하고 관리하기 위한 핵심 도구, Git과 GitHub를 본격적으로 만나보겠습니다. 이제 작업 상자는 준비됐고, 곧 그 안의 변화들을 차곡차곡 남기는 법을 배우게 됩니다.

참고

¹CLI: create-next-app

²Getting Started: Installation

³Getting Started: Project Structure