Claude Code에게 “Next.js 프로젝트 만들어줘”라고 바로 요청하는 것과, 공식 문서를 기반으로 직접 설치한 뒤 Claude Code를 붙이는 것은 결과가 다르다. 이 글은 claude-nextjs-starters 프로젝트를 세팅하면서 두 방식의 차이를 직접 보여준다
Next.js 15 (App Router) + TypeScript Tailwind CSS v4 shadcn/ui + lucide-react react-hook-form + zod @tanstack/react-query usehooks-ts date-fns
공식 CLI로 Next.js 직접 설치
Claude Code에게 처음부터 전부 맡기면 오래된 버전으로 설치되거나 비표준 구조로 세팅될 수 있다. 주요 기술 스택만큼은 공식 문서 기반으로 직접 설치하는 것이 가장 정확하다
mkdir claude-nextjs-starters cd claude-nextjs-starters npx create-next-app@latest .
대화형 설정에서 선택 항목은 다음과 같다
| 항목 | 선택 |
|---|---|
| TypeScript | Yes |
| Lint | ESLint |
| Tailwind CSS | Yes |
src/ 디렉터리 | Yes |
| App Router | Yes |
| Turbopack | Yes |
| Import alias 커스터마이징 | No (기본값) |
설치가 완료되면 개발 서버를 확인한다.
npm run dev # http://localhost:3000
create-next-app은 Git 초기화와 초기 커밋까지 자동으로 처리한다
shadcn/ui 설치
shadcn/ui 공식 문서의 Next.js 가이드를 따른다
npx shadcn@latest init
색상 테마를 선택하면 다음 파일들이 자동으로 설정된다
components/ui/생성globals.css업데이트tailwind.config에 테마 변수 주입 (v4에서는 CSS 변수 방식)
컴포넌트는 필요할 때마다 개별 설치한다
npx shadcn@latest add button input label textarea
여기까지가 Claude Code 없이 할 수 있는 범위다. 이후부터 Claude Code를 붙인다
Claude Code에게 역할 부여 + 계획 수립
Claude Code는 역할을 명시할수록 더 전문적인 결과를 낸다. 프롬프트 시작에 역할을 부여하는 것이 Anthropic 공식 문서에서 권장하는 방식이다
Plan 모드(Shift + Tab)로 전환하고 다음과 같이 요청한다
당신은 모던 웹 스타터킷 제작 전문가입니다. 빠르게 웹 개발을 시작할 수 있도록 스타터킷을 개발해주세요. 기술 스택: - Next.js 15 (App Router) - TypeScript - Tailwind CSS v4 - shadcn/ui - lucide-react 현재 프로젝트에 위 기술 스택 설치는 완료되었습니다. 스타터킷에 필요한 컴포넌트와 레이아웃을 단계별로 생각하고 계획해주세요. 사고 순서: 1. 어떤 웹에서도 필요한 컴포넌트와 레이아웃을 정리해주세요 2. 컴포넌트 계층으로 분류해주세요 3. 우선순위에 따라 shadcn/ui 컴포넌트를 설치하고 레이아웃까지 개발해주세요 참고: 유틸리티 기능 추가 시 직접 구현하지 말고 검증된 라이브러리를 활용해주세요.
“사고 순서”를 명시하는 것이 Chain-of-Thought 프롬프팅이다. Claude가 문제를 단계별로 분해해서 논리적으로 처리하기 때문에 복잡한 계획일수록 오류가 줄어든다
바퀴를 재발명하지 않는다
계획안을 검토하다 보면 useMediaQuery, useLocalStorage 같은 훅을 직접 구현하는 경우가 있다. 이미 검증된 라이브러리가 있다면 직접 구현보다 낫다. 버그가 검증되어 있고 타입 지원과 성능 최적화까지 따라온다
계획을 수정하려면 Plan 모드에서 3번(Tell Claude what to change)을 선택한다
useMediaQuery, useLocalStorage를 직접 구현하는 것보다 검증된 라이브러리를 사용해주세요. 참고: - https://www.npmjs.com/package/react-responsive - https://www.npmjs.com/package/use-local-storage-state 참고한 라이브러리보다 더 괜찮은 라이브러리가 있다면 제안해주셔도 됩니다.
Claude는 두 라이브러리를 분석하고 대안으로 usehooks-ts를 제안했다. TypeScript 지원이 뛰어나고 useMediaQuery, useLocalStorage를 포함한 웹 개발 필수 훅이 하나로 통합되어 있다. 이 방향으로 최종 확정했다
Playwright MCP로 브라우저 오류 자동 수정
구현 완료 후 브라우저에서 404 오류나 컴포넌트 누락 오류가 발생했다. 이를 Claude Code가 직접 브라우저를 열어 확인하고 수정하게 할 수 있다
Playwright MCP 설치
claude mcp add playwright npx @playwright/mcp@latest --scope project
설치하면 .mcp.json 파일이 생성된다
권한 설정
.claude/settings.json에서 Playwright MCP 사용을 허용한다.
{
"enableAllProjectMcpServers": true,
"enabledMcpJsonServers": ["playwright"]
}
오류 수정 요청
당신은 Playwright MCP 전문가입니다. Playwright MCP를 활용해서 현재 웹 애플리케이션에서 발생하는 오류를 수집하고 분석해서 해결해주세요. 단계별로 진행해주세요: 1. 오류 정보 수집 (브라우저로 직접 접속) 2. 오류 원인 분석 3. 오류 해결 4. 테스트 오류가 해결되지 않는다면 1번부터 반복해주세요. 에러 정보: 헤더 메뉴에서 예제 메뉴 클릭 시 서브 페이지 진입 시 에러가 발생합니다. 푸터에서 발생하는 404 오류는 무시해주세요.
Claude Code가 브라우저를 자동으로 열고 각 페이지를 순회하며 오류를 수집한다. shadcn/ui의 Select 컴포넌트가 설치되지 않은 것을 스스로 파악하고 설치 후 재테스트까지 완료했다
/init으로 CLAUDE.md 생성
오류 수정까지 완료되면 /clear로 컨텍스트를 정리하고 /init을 실행한다
/init
현재 프로젝트 전체를 스캔해서 기술 스택, 디렉터리 구조, 컴포넌트 패턴, 코딩 컨벤션을 담은 CLAUDE.md를 자동 생성한다. 이 파일이 있으면 이후 모든 작업에서 Claude Code가 프로젝트 맥락을 정확히 파악하고 일관성 있는 코드를 작성한다
영어로 생성된 경우 한국어로 변환 요청하면 된다. 사용자 메모리(~/.claude/CLAUDE.md)에 IMPORTANT: 문서화는 한국어로 작성 규칙을 추가해두면 다음부터 자동 적용된다
전체 흐름 요약
공식 CLI로 직접 설치 (create-next-app, shadcn init)
↓
Claude Code Plan 모드로 스타터킷 계획 수립
↓
계획 검토 → 라이브러리 선택 보완 (usehooks-ts 등)
↓
구현 요청 (accept edits 모드)
↓
Playwright MCP로 브라우저 오류 자동 수정
↓
/init으로 CLAUDE.md 생성
↓
커밋
주요 기술 스택 설치는 공식 문서 기반으로 직접 처리하고, 그 이후 개발과 오류 수정은 Claude Code에 위임하는 방식이 가장 안정적이다. Claude Code가 강력한 만큼 처음부터 전부 맡기기보다, 사람이 방향을 잡고 AI가 실행하는 역할 분담이 중요하다