매번 프로젝트를 시작할 때마다 같은 초기 설정을 반복하는 게 번거롭다면, 한 번 잘 만들어둔 스타터킷이 답이다. 이번 글에서는 Claude Code를 활용해 claude-nextjs-starterkit 을 세팅하는 과정을 정리한다
기술 스택
| 역할 | 선택 | 이유 |
|---|---|---|
| 프레임워크 | Next.js 15 (App Router) | 업계 표준, 커뮤니티 풍부 |
| 언어 | TypeScript | 타입 안전성, AI 코드 품질 향상 |
| 스타일링 | Tailwind CSS v4 | config 파일 불필요, AI 친화적 |
| UI 컴포넌트 | shadcn/ui | Tailwind 기반, 커스터마이징 용이 |
| 아이콘 | lucide-react | shadcn 기본 아이콘 세트 |
프로젝트 폴더 생성
mkdir claude-nextjs-starterkit cd claude-nextjs-starterkit
이후 Claude Code를 실행한다
claude
핵심 – 바로 구현하지 않는다
Claude Code로 프로젝트를 시작할 때 가장 많이 하는 실수가 있다. 바로 “Next.js 프로젝트 만들어줘”를 곧장 요청하는 것이다
Anthropic 공식 문서에서 권장하는 개발 워크플로우는 이렇다
탐색 (정보 수집) → 계획 → 구현 → 커밋
특히 복잡한 초기 설정일수록 계획 단계가 중요하다. 계획 없이 바로 구현에 들어가면 오류 수정을 반복하면서 토큰만 낭비하게 된다
Plan 모드로 계획 먼저
Shift + Tab 으로 Plan 모드로 전환하고 아래와 같이 요청한다
웹 개발을 빠르게 시작할 수 있는 starter kit을 개발해주세요. 기술 스택: - Next.js 15 (App Router) - TypeScript - Tailwind CSS v4 (no tailwind.config file) - shadcn/ui - lucide-react 각 기술 스택이 공식 문서의 최신 버전을 준수하고 있는지 단계별로 검토해주세요. 고려사항: 1. 공식 문서 설치 가이드 확인 2. 가이드 내용 준수 여부 확인 참고 링크: https://nextjs.org/docs/app/getting-started/installation https://tailwindcss.com/docs/installation/framework-guides/nextjs https://ui.shadcn.com/docs/installation/next
공식 문서 링크를 함께 제공하는 게 중요하다. Claude는 학습 데이터 기준의 버전을 사용하려는 경향이 있는데, 특히 Tailwind CSS가 v4로 업그레이드되면서 config 파일 구조가 바뀌었기 때문에 이를 명시하지 않으면 v3 방식으로 세팅할 가능성이 높다
“단계별로 검토해주세요”라는 표현은 Chain-of-Thought 프롬프팅이다. Claude가 문제를 순서대로 논리적으로 분석하도록 유도해서 오류를 줄이는 효과가 있다
create-next-app 충돌 문제 해결
create-next-app 은 빈 디렉터리에서만 실행된다. 그런데 Claude Code를 실행하면 .claude 디렉터리가 자동으로 생성되기 때문에 그냥 진행하면 충돌 오류가 발생한다
해결 방법은 간단하다. temp 디렉터리를 임시로 사용하도록 계획을 수정한다
Next.js 프로젝트 초기 설정을 루트 디렉터리에 temp 디렉터리를 만들어서 진행해주세요. 모든 작업이 완료된 후에 temp 디렉터리 안의 모든 파일과 디렉터리를 루트로 옮기고 temp 디렉터리를 삭제해주세요.
/init으로 CLAUDE.md 생성
초기 설정이 완료되면 /clear로 컨텍스트를 정리하고 /init을 실행한다
프로젝트를 처음 만들자마자 /init을 하지 않는 이유가 있다. /init은 현재 프로젝트를 스캔해서 CLAUDE.md를 자동 생성한다. 기술 스택이 갖춰진 상태에서 실행해야 프로젝트 구조와 코딩 컨벤션이 제대로 반영된다
/init
생성된 CLAUDE.md가 영어로 작성됐다면 한국어로 변환 요청을 한다. 그 전에 사용자 메모리(~/.claude/CLAUDE.md)에 IMPORTANT: 문서화는 한국어로 작성 규칙을 추가해두면 앞으로는 자동으로 한국어로 작성된다
컨텍스트 관리
초기 설정처럼 작업량이 많은 세션 이후에는 반드시 컨텍스트를 확인하자
/context
사용량이 39%라면 다음 작업이 관련된 작업이라면 그냥 이어가도 된다. 70%를 넘었다면 /compact로 요약하거나 새 작업이면 /clear로 초기화한다
새 기능 시작 → /clear 작업 중 70% 초과 → /compact 또는 /clear
커밋까지 Claude Code에게
구현이 완료되면 커밋도 Plan 모드로 요청한다
코드 변경 사항을 커밋해주세요.
Claude가 변경 파일을 확인하고 스테이징한 뒤 적절한 커밋 메시지를 작성한다. 커밋 메시지 작성 규칙을 CLAUDE.md에 미리 정의해두면 일관성 있는 메시지가 나온다
결과
두 번의 명령으로 완성된 스타터킷 구조다
claude-nextjs-starterkit/ ├── app/ │ ├── layout.tsx # 다크모드 Provider, Navbar, Footer 포함 │ └── page.tsx ├── components/ │ ├── ui/ # shadcn 컴포넌트 │ ├── navbar.tsx │ └── footer.tsx ├── CLAUDE.md # 프로젝트 메모리 (한국어) └── package.json # Next.js 15, React 19, Tailwind v4
한 번에 원하는 결과가 나온 이유는 단 하나다. 공식 문서를 컨텍스트로 제공하고, Chain-of-Thought로 단계별 검토를 요청했으며, Plan 모드로 계획을 먼저 확인했기 때문이다. 프롬프트 품질이 결과 품질을 결정한다