[Next.js 15 + 웹기능 기본 기능 구현] 프로젝트 자동 생성 스킬: nextjs-project-wizard

새로운 Next.js 프로젝트를 시작할 때마다 같은 설정을 반복하고 계신가요? 이 글에서는 Claude Code 스킬을 활용해 프로덕션 레벨의 프로젝트 구조를 자동으로 생성하는 방법을 소개합니다.

Table of Contents

TL;DR

💡 핵심 요약

nextjs-project-wizard: 5단계 인터랙티브 위저드로 Next.js 15 프로젝트 생성
32개 템플릿: 환경 설정, 스크립트, 미들웨어 시스템 포함
Clean Architecture: 비즈니스 로직과 공용 코드 분리
즉시 실행: 생성 후 바로 서버 구동 가능
GitHub: greeun/nextjs-project-wizard

왜 이 스킬이 필요한가?

실무에서 새 프로젝트를 시작할 때마다 마주치는 문제들이 있습니다.

1. 반복되는 초기 설정 작업

매번 프로젝트를 시작할 때마다 같은 작업을 반복합니다.

TypeScript 설정 (tsconfig.json)
ESLint + Prettier 설정
환경 변수 파일 생성
디렉토리 구조 설계
미들웨어 시스템 구축

이 작업들은 프로젝트마다 2-3시간씩 소요되며, 매번 “이전 프로젝트에서 복사해올까?”라는 유혹에 빠지게 됩니다. 하지만 복사-붙여넣기는 프로젝트별 특성을 반영하지 못하고, 불필요한 코드를 포함하게 됩니다.

2. 환경별 설정의 복잡성

실무 프로젝트는 최소 4가지 환경을 관리해야 합니다.

환경	용도	특징
`.env.local`	로컬 개발	InMemory 캐시, Rate Limit 비활성화
`.env.dev`	공유 개발	Redis + InMemory Hybrid
`.env.production`	프로덕션	Redis, Rate Limit 활성화, 최소 로깅
`.env.test`	테스트	포트 3555, 로깅 비활성화

이 환경들을 처음부터 올바르게 설정하지 않으면, 나중에 “로컬에서는 되는데 배포하면 안 돼요” 같은 문제에 직면하게 됩니다.

3. 일관된 아키텍처의 부재

팀에서 여러 프로젝트를 운영하다 보면,

프로젝트마다 다른 디렉토리 구조
미들웨어 처리 방식의 불일치
에러 핸들링 패턴의 차이
공용 코드 재사용의 어려움

이런 상황은 개발자가 프로젝트를 이동할 때 온보딩 시간을 증가시키고, 코드 품질의 편차를 만듭니다.

해결책: nextjs-project-wizard

이 스킬은 실제 프로덕션 프로젝트(url-shortener-mvp)에서 검증된 구조를 자동으로 생성합니다.

📋 위저드 워크플로우:

Claude Code 호출 → Phase 1: 프로젝트 정보 → Phase 2: 기술 스택 → Phase 3: 모듈 선택 → Phase 4: 생성 → Phase 5: 검증 → ✅ 서버 구동

생성되는 프로젝트 구조

my-project/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── api/               # API Routes
│   │   └── [locale]/          # i18n 라우트
│   ├── components/            # React 컴포넌트
│   ├── lib/                   # 비즈니스 로직 (프로젝트 특화)
│   │   ├── services/
│   │   ├── validators/
│   │   └── hooks/
│   └── shared/@withwiz/       # 재사용 가능 코드
│       ├── middleware/        # API 미들웨어 체인
│       ├── error/
│       └── auth/
├── scripts/                   # 환경별 실행 스크립트
│   ├── local-startup.sh
│   ├── dev-startup.sh
│   └── build.sh
├── .env.local                 # 환경별 설정
├── .env.dev
├── .env.production
└── .env.test

핵심 기능: 미들웨어 시스템

이 스킬의 가장 강력한 기능은 Express 스타일의 미들웨어 체인입니다. Next.js App Router에서는 기본적으로 미들웨어 체인이 없어서, API마다 인증/에러처리/로깅 코드를 반복 작성해야 합니다.

기존 방식의 문제

// ❌ 매 API마다 반복되는 코드
export async function GET(request: NextRequest) {
  try {
    // 인증 체크
    const token = request.headers.get('authorization');
    if (!token) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });

    // 토큰 검증
    const user = await verifyToken(token);

    // Rate limit 체크
    const ip = getClientIp(request);
    const isAllowed = await checkRateLimit(ip);
    if (!isAllowed) return NextResponse.json({ error: 'Too many requests' }, { status: 429 });

    // 실제 비즈니스 로직
    const data = await fetchData();
    return NextResponse.json(data);

  } catch (error) {
    console.error(error);
    return NextResponse.json({ error: 'Server error' }, { status: 500 });
  }
}

미들웨어 체인 사용

// ✅ 깔끔한 API 코드
import { withAuthApi } from '@withwiz/middleware';

export const GET = withAuthApi(async (ctx) => {
  // 비즈니스 로직에만 집중
  const data = await fetchData(ctx.user.id);
  return NextResponse.json(data);
});

withAuthApi 래퍼가 다음을 자동으로 처리합니다.

미들웨어 체인 순서:Request → errorHandler → security → cors → initRequest → auth → rateLimit → responseLogger → Handler → Response

제공되는 API 래퍼

래퍼	용도	포함된 미들웨어
`withPublicApi`	공개 API	에러, 보안, CORS, Rate Limit, 로깅
`withAuthApi`	인증 필요	위 + JWT 인증
`withAdminApi`	관리자 전용	위 + 관리자 권한 검증
`withCustomApi`	커스텀 체인	직접 구성

Clean Architecture: 의존성 규칙

이 스킬은 단방향 의존성 규칙을 강제합니다.

✅ 허용 (단방향):
src/app/ → src/shared/@withwiz/
src/lib/ → src/shared/@withwiz/
src/components/ → src/shared/@withwiz/

❌ 금지 (역방향):
src/shared/@withwiz/ → src/lib/
src/shared/@withwiz/ → src/app/

src/shared/@withwiz/는 프로젝트에 독립적이어야 합니다. 이를 통해,

공용 코드를 다른 프로젝트에서 그대로 재사용 가능
비즈니스 로직 변경이 공용 코드에 영향을 주지 않음
테스트와 유지보수가 용이

사용 방법

Claude Code에서 다음과 같이 호출합니다:

# 방법 1: 자연어로 요청
새 프로젝트 생성해줘

# 방법 2: 슬래시 커맨드
/nextjs-project-wizard

위저드가 다음 질문들을 순차적으로 물어봅니다.

📌 Phase 1: 프로젝트 기본 정보

프로젝트 이름
생성 경로
주제/도메인 (예: 전자상거래, SaaS)
핵심 기능 3가지
한 줄 설명

📌 Phase 2: 기술 스택 선택

데이터베이스: PostgreSQL / MongoDB / SQLite / None
캐시: Hybrid / Redis / InMemory / None
인증: JWT+OAuth / JWT Only / None

📌 Phase 3: 기능 모듈 선택

i18n (다국어)
Testing (Jest + Playwright)
Middleware (API 미들웨어)
Docker
Rate Limiting

프로젝트 타입별 추천 설정

프로젝트	DB	캐시	인증	추천 모듈
SaaS	PostgreSQL	Hybrid	JWT+OAuth	Rate Limit, Analytics
블로그	PostgreSQL	InMemory	JWT Only	i18n
이커머스	PostgreSQL	Hybrid	JWT+OAuth	Email, Analytics
API 서버	PostgreSQL	Redis	JWT	Rate Limit, API Docs
포트폴리오	SQLite	None	None	–

GitHub Repository

전체 소스코드와 32개의 템플릿 파일은 GitHub에서 확인할 수 있습니다:

🔗 https://github.com/greeun/nextjs-project-wizard

포함된 템플릿

카테고리	파일 수	주요 파일
설정 파일	6개	package.json, tsconfig.json, next.config.js
환경 변수	5개	.env.local, .env.dev, .env.production, .env.test
스크립트	5개	local-startup.sh, build.sh, test-server-startup.sh
미들웨어	11개	auth.ts, cors.ts, rate-limit.ts, wrappers.ts
소스 코드	3개	layout.tsx, page.tsx, globals.css
기타	2개	CLAUDE.md, .gitignore

마치며

nextjs-project-wizard는 단순한 보일러플레이트 생성기이지만, 실제 프로덕션 환경에서 검증된 아키텍처와 패턴을 담고 있어, 프로젝트 시작 시 발생하는 의사결정 피로를 줄이고 일관된 코드 품질을 유지할 수 있게 해줍니다.

특히 팀에서 여러 Next.js 프로젝트를 운영한다면, 이 스킬을 팀 표준으로 사용함으로써

신규 프로젝트 셋업 시간 2-3시간 → 5분으로 단축
프로젝트 간 일관된 구조로 온보딩 시간 감소
검증된 미들웨어 패턴으로 보안 이슈 예방
환경별 설정 분리로 배포 문제 최소화

Claude Code를 사용 중이라면, 다음 프로젝트에서 한번 사용해보세요! 🚀