Claude로 Next.js 프로젝트 부트스트랩하기: 실전 가이드

Claude Code로 Next.js 프로젝트를 처음부터 설정하는 최적 방법은 CLAUDE.md 먼저 작성하고, 스택 선택을 한 번의 프롬프트로 넘기고, Claude가 설정 파일을 일괄 생성하게 두는 것이다. 이 방식으로 1시간 걸리던 초기 설정을 10-15분으로 줄일 수 있다. 이 가이드는 단계별 명령어와 실전 CLAUDE.md 템플릿을 제공한다.

0단계: Next.js 프로젝트 생성

# 기본 생성 (Claude와 작업 전 준비)
npx create-next-app@latest my-app \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir \
  --import-alias "@/*"

cd my-app

1단계: CLAUDE.md 먼저 작성

프로젝트 루트에 CLAUDE.md를 먼저 만든다. Claude Code의 모든 세션이 이 파일을 읽고 일관된 코드를 생성한다.

# my-app CLAUDE.md

## 프로젝트 개요
[서비스 설명 1-2줄]

## 기술 스택
- Framework: Next.js 15 App Router
- Language: TypeScript (strict)
- Styling: Tailwind CSS + shadcn/ui
- Database: Supabase (PostgreSQL)
- Auth: Clerk
- Package manager: bun

## 디렉토리 구조
src/
├── app/                 # App Router 페이지
│   ├── (auth)/         # 인증 필요 페이지 그룹
│   ├── (public)/       # 인증 불필요 페이지 그룹
│   └── api/            # API Routes
├── components/
│   ├── ui/             # shadcn 기본 컴포넌트 (수정 금지)
│   └── [기능명]/       # 기능별 컴포넌트
├── lib/
│   ├── supabase/       # Supabase 클라이언트
│   └── utils.ts        # 유틸리티 함수
└── types/              # 전역 TypeScript 타입

## 코딩 규칙
- 서버 컴포넌트 기본 (클라이언트 컴포넌트는 'use client' 명시)
- 에러 처리: try-catch + 구체적인 에러 메시지
- 환경변수: NEXT_PUBLIC_ 프리픽스는 클라이언트 노출 용도만
- import: @/ 절대 경로 사용

## 금지 사항
- console.log (개발용만, 프로덕션 빌드에 포함되면 안 됨)
- any 타입
- useEffect를 data fetching에 사용 (서버 컴포넌트 또는 useSWR 사용)
- pages/ 디렉토리 (App Router만 사용)

## 명령어
- dev: bun run dev
- build: bun run build
- typecheck: bun run typecheck
- lint: bun run lint

2단계: 초기 설정 프롬프트 (한 번에)

claude "
다음 설정을 모두 진행해줘:

1. shadcn/ui 초기화 및 기본 컴포넌트 설치
   (button, input, form, card, dialog, toast, dropdown-menu)

2. Supabase 클라이언트 설정
   - src/lib/supabase/client.ts (브라우저용)
   - src/lib/supabase/server.ts (서버 컴포넌트용)
   - 환경변수: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY

3. Clerk 미들웨어 설정
   - middleware.ts (루트)
   - src/app/layout.tsx에 ClerkProvider 추가
   - 환경변수: NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY

4. TypeScript 경로 alias 확인 (@/ = src/)

5. .env.local.example 파일 생성 (실제 값 없이 키 이름만)

모든 설정 후 bun run build로 빌드 성공 확인해줘.
"

3단계: 기본 레이아웃 설정

claude "
기본 앱 구조를 만들어줘:

1. src/app/layout.tsx
   - Clerk ClerkProvider 래핑
   - 한국어 locale 설정 (lang='ko')
   - 기본 메타태그

2. src/app/(public)/page.tsx
   - 랜딩 페이지 (간단한 히어로 섹션)
   - Tailwind + shadcn Button 사용

3. src/app/(auth)/dashboard/page.tsx
   - 로그인 후 대시보드
   - Clerk useUser() 훅으로 사용자 정보 표시

4. src/components/navigation.tsx
   - 상단 네비게이션
   - 로그인/로그아웃 버튼 (Clerk SignInButton, UserButton)
   - 모바일 반응형

CLAUDE.md의 컨벤션 따르고, TypeScript strict 에러 없이 빌드 되어야 함.
"

4단계: DB 스키마 및 타입 생성

claude "
Supabase 데이터베이스 설정:

1. src/lib/supabase/schema.sql 생성
   테이블:
   - profiles: id(uuid, FK users), full_name(text), avatar_url(text), created_at
   - [프로젝트 핵심 테이블 1-2개]
   
   RLS 정책:
   - profiles: 자신의 데이터만 읽기/쓰기 가능
   
2. src/types/database.ts 생성
   - Supabase 스키마 기반 TypeScript 타입
   - Database, Tables, Row, Insert, Update 타입

3. src/lib/supabase/queries.ts 생성
   - 자주 쓸 쿼리 함수 (getProfile, updateProfile 등)
   - 모든 함수: 서버/클라이언트 양쪽에서 사용 가능

TypeScript 타입 에러 없이 완성해줘.
"

5단계: 기능 구현 패턴

프로젝트별 기능을 추가할 때:

# 새 기능 추가 패턴
claude "
[기능명] 기능을 구현해줘:

요구사항:
- [요구사항 1]
- [요구사항 2]

파일 구조:
- src/components/[기능명]/[컴포넌트].tsx
- src/app/api/[기능명]/route.ts
- src/lib/supabase/[기능명].ts (DB 쿼리)

CLAUDE.md 컨벤션 따르고, 구현 후 typecheck 실행해줘.
"

자주 하는 추가 설정

Tailwind 커스텀 색상 (브랜드 컬러)

claude "
tailwind.config.ts에 브랜드 컬러 추가해줘:
primary: '#1a73e8' (구글 블루)
secondary: '#34a853'

shadcn/ui 컴포넌트에서 이 컬러를 기본으로 사용하도록 globals.css의 CSS 변수도 업데이트해줘.
"

SEO 메타태그 설정

claude "
Next.js 15 Metadata API로 SEO 설정해줘:

1. src/app/layout.tsx - 기본 메타태그
   - title: '[사이트명] | [슬로건]'
   - description: '[사이트 설명]'
   - openGraph 태그
   - twitter card

2. 동적 페이지용 generateMetadata 예시 함수
   (제품 상세 페이지 예시)

3. sitemap.ts 생성 (Next.js 빌트인)
"

에러 처리 레이어

claude "
공통 에러 처리 설정:

1. src/lib/errors.ts
   - AppError 클래스 (message, code, status)
   - 일반 에러 타입 정의

2. src/app/error.tsx
   - Next.js Error Boundary (클라이언트 에러)

3. src/app/not-found.tsx
   - 404 페이지

4. API route 에러 처리 패턴
   - try-catch + NextResponse.json({ error }) 표준화
"

완성 확인 체크리스트

claude "
설정 완료 후 체크리스트 검증해줘:

□ bun run build 성공 (에러 0)
□ TypeScript strict 에러 없음 (bun run typecheck)
□ ESLint 경고 없음 (bun run lint)
□ .env.local.example 파일 존재
□ .env.local이 .gitignore에 포함
□ shadcn/ui 컴포넌트 import 정상
□ Supabase 클라이언트 (서버/클라이언트 분리)
□ Clerk 미들웨어 설정
□ 모바일 반응형 확인 (md 브레이크포인트)

각 항목 확인하고 문제 있으면 수정해줘.
"

자주 겪는 문제

서버 컴포넌트에서 클라이언트 훅 사용 오류

Error: You're importing a component that needs useState. It only works in a Client Component but none of its parents are marked with "use client".

claude "이 에러 수정해줘 — use client 지시어 위치를 정확히 잡아줘"

TypeScript 경로 alias 작동 안 함

claude "tsconfig.json과 next.config.js의 @/* 경로 설정 확인하고 수정해줘"

Supabase RLS 정책 오류

claude "
이 Supabase 쿼리가 'new row violates row-level security policy' 에러를 냄.
RLS 정책 확인하고 수정해줘:
[에러 발생 쿼리]
"

자주 묻는 질문

create-next-app 없이 Claude가 처음부터 만들어줄 수 있나요? 가능하지만 권장하지 않는다. create-next-app이 Webpack, Turbopack, 기본 설정을 가장 안정적으로 구성한다. Claude는 그 위에 추가 설정하는 역할이 효율적이다.

Pages Router 프로젝트에도 동일한 방법이 통하나요? CLAUDE.md에 "App Router 대신 Pages Router 사용" 명시하면 된다. Claude Code는 양쪽을 모두 알고 있다.

한국어 페이지도 잘 만들어주나요? Claude에게 "한국어 UI로 만들어줘"라고 하면 된다. 단, Tailwind 폰트 설정은 따로 필요할 수 있다 (font-family: 'Noto Sans KR', sans-serif).

Supabase 대신 Prisma + Neon을 써도 같은 방법이 통하나요? 통한다. CLAUDE.md의 DB 부분을 변경하면 된다. Claude Code는 Prisma 스키마 생성, 마이그레이션, 쿼리 작성을 잘 처리한다.

관련 가이드

• Claude Code 완벽 가이드: 설치부터 고급 활용까지 — 기본 가이드
• 솔로 개발자의 AI 스택 2026 — 전체 스택 선택
• Context Engineering for Claude — CLAUDE.md 심화

더 깊이 알고 싶다면

Power Prompts 300 — $29 — Next.js 부트스트랩 프롬프트 20개 + 기능별 구현 프롬프트 (인증, 결제, 파일 업로드, 알림 등) + CLAUDE.md 템플릿 3종 포함.

→ Power Prompts 300 구매 — $29

30일 환불 보장. 즉시 다운로드.