Next.js 개발 환경 설정 (nextjs-dev-setup)은(는) 무엇을 하나요?
Next.js App Router 개발 환경, 리버스 프록시 라우팅(Traefik/Nginx), 그리고 docs/project.json을 단일 진실 공급원으로 사용하는 구조화된 종단 간 오케스트레이션 런북입니다.
사전 조건 및 검색
- 무중단 스캔: 질문하기 전에 기존 저장소 파일(
package.json, 락파일, 스타일시트,docs/adr/*.md,docs/plan.md,CONTEXT.md)을 먼저 스캔하세요. - 메타데이터 구조와 자동 추론 규칙을 보려면 project-json-schema.md를 참조하세요.
0단계: 다중 라운드 설정 인터뷰(심층 조사) 및 계획 수립
인터랙티브 인터뷰를 점진적이고 적응적인 라운드(각 라운드 후 사용자 응답 대기)로 진행하여 설정을 맞춤화합니다:
- 1라운드(범위 및 도구): 대상 테스트 스위트(Jest, Playwright, Storybook), MCP 서버,
@shadcn/lint적용 여부를 조사합니다. - 2라운드(리버스 프록시 및 프로덕션 호스팅): 도메인 이름, 포트, 리버스 프록시 전략을 조사합니다:
- Docker Compose를 통한 Traefik: 환경 변수(
${DOMAIN_NAME},${TRAEFIK_ENTRYPOINT},${TRAEFIK_CERTRESOLVER})를 읽는 Compose 레이블을 사용한 자동 컨테이너 검색 및 안티 버퍼링. - 호스트 시스템을 통한 Nginx: Certbot SSL 인증서를 사용하는
/etc/nginx/sites-available/<domain>의 독립 실행형 구성입니다.
- Docker Compose를 통한 Traefik: 환경 변수(
- 3라운드(CI/CD, Git 훅 및 레지스트리): Husky pre-push 테스트 스위트, Commitlint, GitHub Actions Release Please / GHCR 워크플로를 조사합니다.
- 전체 질문 세트와 분기 로직은 setup-interview-rounds.md를 참조하세요.
- 계획 및 실행: 변경 사항을 적용하기 전에 계획된 모든 파일 생성, 구성 및 패키지를 자세히 설명하는
implementation_plan.md아티팩트를 생성하여 제시하고, 수동 확인을 기다리지 않고 바로 실행을 진행합니다.
단계별 실행 흐름
1단계: 프로젝트 메타데이터 및 개발자 도구 (docs/project.json)
- 사용자 인터뷰 선택 사항을 기반으로 project.template.json을 사용하여
docs/project.json을 초기화합니다. - vscode-launch.json.template을 사용하여
.vscode/launch.json을 구성합니다. - providers.tsx.template을 사용하여
<ProgressBarProvider>로app/providers.tsx를 스캐폴딩하고, Link.tsx.template을 사용하여 합성<Link>를 구성합니다. - 프로덕션용으로 env.example.template을 사용하여
.env.example을, 로컬 개발용으로 env.local.template을 사용하여.env.local을 스캐폴딩합니다. - 앱 아이콘, Apple 아이콘 및 PWA 매니페스트: manifest.ts.template을
app/manifest.ts에 배포합니다. 사용자가 제공한 파비콘을 루트app/favicon.ico,app/icon.png,app/apple-icon.png(또는 동적ImageResponse아이콘)에 걸쳐 구성합니다. app-icons-and-pwa-guide.md를 참조하세요.
2단계: 테스트 스위트 (Jest, Playwright 및 인스턴트 내비게이션)
[!IMPORTANT] 더미 테스트 파일 없음(규칙 3): 작업 공간에 플레이스홀더/샘플 테스트 파일을 생성하지 마십시오. 프레임워크 파일과 스크립트만 구성하십시오. 샘플 패턴은 sample-component.test.tsx, sample-navigation.spec.ts, sample-component.stories.tsx에서 확인할 수 있습니다.
- Jest 단위 테스트: jest.config.ts.template 및 jest.setup.ts.template을 구성합니다.
- Playwright E2E 및 인스턴트 내비게이션:
@playwright/test및@next/playwright를 설치하고(pnpm add -D @playwright/test @next/playwright), playwright.config.ts.template을 구성하고, 브라우저를 설치합니다. - Next.js 인스턴트 구성:
next.config.ts에서cacheComponents: true,partialPrefetching: true및 인스턴트 인사이트를 구성합니다. - Storybook 워크숍: .storybook/main.ts 및 .storybook/preview.tsx를 구성합니다.
- testing-guide.md 및 storybook-guide.md에서 아키텍처를 검토합니다.
3단계: 이중 MCP 서버 구성
[!IMPORTANT] 안티그래비티 글로벌 MCP 로딩 규칙: AG는 호스트 시스템(
~/.gemini/antigravity/mcp_config.json및~/.gemini/config/mcp_config.json)에 전역적으로 구성된 MCP 서버만 로드합니다. 작업 공간mcp.json은 이식성을 위해 유지됩니다. 둘 다 구성되어야 합니다.
next-devtools,playwright,storybook및codebase-memory-mcp를 구성합니다.- 말더듬 방지:
codebase-memory-mcp config set auto_watch false를 통해auto_watch = false를 설정하고 루트 .cbmignore를 배포합니다. - mcp-configuration-guide.md에서 전체 사양을 검토합니다.
4단계: Agent-First 디자인 시스템 린팅 (@shadcn/lint)
@shadcn/lint를 설치하고 eslint.config.mjs.template을 사용하여 ESLint 플랫 구성을 구성합니다.- styling-and-linting-guide.md에서 메커니즘을 검토합니다.
5단계: 독립 실행형 프로덕션 Docker 및 리버스 프록시 (Traefik / Nginx)
next.config.ts에서: Git 커밋 해시(getGitCommitHash()with CI fallbacks) 및 패키지 버전을 확인하고,NEXT_PUBLIC_APP_VERSION및NEXT_PUBLIC_GIT_COMMIT_HASH를env아래에 주입하고,output: "standalone"을 활성화하고, 버전 스큐 보호를 위해deploymentId를 설정하고(${pkg.version}-${gitHash}),X-Accel-Buffering: no로headers를 구성하고,experimental.serverActions.allowedOrigins를 설정합니다..env.example에NEXT_SERVER_ACTIONS_ENCRYPTION_KEY를 문서화하고 런타임 환경에 전달합니다.- (
STOPSIGNAL SIGTERM이 있는) Dockerfile.template과 (stop_grace_period: 30s가 있는) docker-compose.yml.template을 배포합니다. - 리버스 프록시 구성:
- Traefik: 동적 환경 변수 레이블(
${DOMAIN_NAME},${TRAEFIK_ENTRYPOINT},${TRAEFIK_CERTRESOLVER})과 안티 버퍼링 미들웨어가 포함된 docker-compose.prod.yml.template을 배포합니다. - Nginx: Certbot SSL 인증서와 함께
/etc/nginx/sites-available/<domain>에 대한 nginx-site.conf.template을 배포하거나 출력합니다.
- Traefik: 동적 환경 변수 레이블(
- docker-containerization-guide.md에서 아키텍처 및 다중 컨테이너 캐시 드리프트 주의 사항을 검토합니다.
6단계: Git 훅 및 크레딧 최적화 CI/CD
husky,@commitlint/cli,@commitlint/config-conventional을 설치합니다.- commitlint.config.mjs.template,
.husky/commit-msg,.husky/pre-push(pnpm run test:all)를 구성합니다. .next/cache빌드 캐싱 및 다중 아키텍처 매트릭스 게시와 함께 .github/workflows/release-please.yml을 배포합니다.- cicd-and-release-automation-guide.md에서 캐싱을 검토합니다.
7단계: 최종 실행 보고서 및 검증
- 구성 검증 스크립트를 실행하고 모든 검사가 통과하는지 확인합니다.
- 규칙 36에 따라 생성/수정된 모든 파일을 git에 스테이징합니다(
git add .). - 필수 최종 출력: 구현된 모든 파일, 검증 검사 결과 및 다음 개발 단계를 요약하는 완전하고 구조화된 Next.js 개발 환경 설정 실행 보고서 마크다운 테이블을 렌더링합니다.
검증 및 상태 확인
- 구성 검증 스크립트를 실행합니다:
- Windows (PowerShell):
powershell -ExecutionPolicy Bypass -File .agents/skills/nextjs-dev-setup/scripts/verify-project-config.ps1 - Linux / macOS (Bash):
bash .agents/skills/nextjs-dev-setup/scripts/verify-project-config.sh
- Windows (PowerShell):
- 보고된 오류를 수정하고 모든 검사가 통과할 때까지 다시 검증합니다.
엣지 케이스 및 알려진 AI 함정
- 연결된 명령어: 터미널 실행에서 한 줄에
&&또는;로 명령어를 연결하지 마십시오. - MCP 비활성화: AG 글로벌 구성에서
agy.exe는mcpServers내부의"disabled": true를 무시합니다. 비활성화된 서버를mcpServers외부로 이동하십시오. - Docker 이미지 이름: Docker OCI 명명 규칙은 저장소 이름을 엄격하게 소문자로 요구합니다(
IMAGE_NAME=$(echo ... | tr '[:upper:]' '[:lower:]')). - Storybook Intl 컨텍스트:
Link또는useTranslations를 렌더링하는 Storybook 스토리를 항상NextIntlClientProvider로 감싸십시오.
필수 최종 출력: 실행 보고서 템플릿
스킬 워크플로를 완료하면 항상 이 보고서를 출력합니다:
## 🛠️ Next.js Dev Setup Execution Report
| 단계 / 구성 요소 | 대상 파일 / 리소스 | 상태 | 참고 / 세부 사항 |
| :----------------------------------- | :----------------------------------------------------------------------------------------------------- | :------------------------------ | :------------------------------------------------------------------------------- |
| **1. 프로젝트 메타데이터** | `docs/project.json` | `[IMPLEMENTED]` / `[UNTOUCHED]` | 패키지 관리자, 디렉토리, 애니메이션 및 i18n 메타데이터가 구성됨. |
| **2. 앱 아이콘 및 PWA 매니페스트** | `app/manifest.ts`, `app/favicon.ico`, `app/apple-icon.png`, `app/icon.png` | `[IMPLEMENTED]` / `[UNTOUCHED]` | 사용자 파비콘을 사용하여 루트 파비콘, Apple 터치 아이콘 및 웹 앱 매니페스트가 구성됨. |
| **3. 핵심 종속성** | `package.json`, Lockfile | `[IMPLEMENTED]` / `[UNTOUCHED]` | React, Next.js, 스타일링 및 모션 라이브러리가 확인됨. |
| **4. Next.js Dev Server MCP** | `~/.gemini/antigravity/mcp_config.json`, `mcp.json`, `.agents/plugins/workspace-tools/mcp_config.json` | `[IMPLEMENTED]` / `[UNTOUCHED]` | Next.js Dev Server(`next-devtools`)가 AG용으로 전역 및 작업 공간에 구성됨. |
| **5. Playwright 및 인스턴트 테스트** | `playwright.config.ts`, `@next/playwright`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json` | `[IMPLEMENTED]` / `[UNTOUCHED]` | 러너, 브라우저, Playwright MCP 및 `@next/playwright` 인스턴트 내비게이션 헬퍼가 확인됨. |
| **6. 코드베이스 메모리 및 말더듬 수정** | `.cbmignore`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json`, `auto_watch=false` | `[IMPLEMENTED]` / `[UNTOUCHED]` | MCP 등록, .cbmignore 제외 항목 구성, 세션 와처 비활성화됨. |
| **7. Jest 단위 테스트** | `jest.config.ts`, `jest.setup.ts` | `[IMPLEMENTED]` / `[UNTOUCHED]` | Next.js Jest 변환기, jsdom 환경 및 test-dom이 구성됨. |
| **8. Storybook 및 Storybook MCP** | `.storybook/main.ts`, `.storybook/preview.tsx`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json` | `[IMPLEMENTED]` / `[UNTOUCHED]` | Storybook Vite, a11y, 테마 및 Storybook AI MCP가 전역 및 작업 공간에 구성됨. |
| **9. Agent-First Tailwind 린터** | `eslint.config.mjs`, `package.json` | `[IMPLEMENTED]` / `[UNTOUCHED]` | 디자인 토큰 및 계약의 에이전트 검증을 위해 `@shadcn/lint`가 구성됨. |
| **10. Docker 및 리버스 프록시** | `Dockerfile`, `docker-compose.prod.yml`, `nginx-site.conf`, `.dockerignore` | `[IMPLEMENTED]` / `[UNTOUCHED]` | 독립 실행형 컨테이너, Traefik 레이블 / Certbot SSL을 사용하는 Nginx HTTPS. |
| **11. Husky Git 훅** | `.husky/commit-msg`, `.husky/pre-push` | `[IMPLEMENTED]` / `[UNTOUCHED]` | 이중 사전 푸시 테스트 스위트(Jest + Playwright) 및 commitlint를 시행함. |
| **12. Commitlint 구성** | `commitlint.config.mjs` | `[IMPLEMENTED]` / `[UNTOUCHED]` | `@commitlint/config-conventional`이 구성됨. |
| **13. 릴리스 및 CI 빌드 캐싱** | `.github/workflows/release-please.yml` | `[IMPLEMENTED]` / `[UNTOUCHED]` | Next.js 빌드 캐시(.next/cache), SemVer 릴리스 PR 및 GHCR 다중 아키텍처 패키지. |
| **14. 환경 검증** | `scripts/verify-project-config.ps1` / `.sh` | `[PASSED]` | 오류 없이 상태 확인 통과. |
#### 상태 정의:
- **`[IMPLEMENTED]`**: 이 설정 실행 중에 새로 생성, 설치 또는 수정됨.
- **`[UNTOUCHED]`**: 스킬 실행 전에 이미 올바르게 구성되어 있음; 변경되지 않고 유지됨.
- **`[SKIPPED]`**: 사용자 선호도에 따라 의도적으로 생략됨.