Next.js 프로젝트 계획 스킬 (nextjs-plan)
Next.js App Router 애플리케이션을 위한 구조화된 오케스트레이션 스킬입니다. 호출되면 기존 워크스페이스 파일에서 기술 명세를 추출하고, 사용자 요구사항에 대한 집중 인터뷰를 수행한 후, 정식 프로젝트 명세(docs/project.json), lib/ 디렉토리의 타입-세이프 코드 레지스트리, docs/design/ 디렉토리의 디자인 문서, 그리고 docs/plan/ 디렉토리의 7단계 모듈형 구현 로드맵을 출력합니다.
워크플로 개요
flowchart TD
Invoke["/nextjs-plan 호출"] --> Step1["1. 자동 워크스페이스 검사<br/>(의존성, 디렉토리 구조, 스타일, 설정, 라우트 추출)"]
Step1 --> Step2["2. 페이지 및 니즈에 대한 그릴링 인터뷰<br/>(페이지 ➔ 섹션 ➔ 컴포넌트)"]
Step2 --> Step3["3. 정식 명세 생성<br/>(docs/project.json 및 lib/ 레지스트리)"]
Step3 --> Step4["4. 전략 및 디자인 시스템 문서화<br/>(docs/design/ 01-strategy, 02-sitemap, 03-tokens)"]
Step4 --> Step5["5. 7단계 모듈형 구현 계획 생성<br/>(docs/plan/ README.md 및 01-07 단계 파일)"]
Step5 --> Step6["6. 완료 및 마무리<br/>(요약 대시보드 표시, 다운스트림 스킬 호출 금지)"]
표준화된 프로젝트 디렉토리 구조
├── lib/ # 타입-세이프 Next.js 코드 진실 공급원
│ ├── routes.ts # 중앙화된 라우트 레지스트리 및 경로 빌더
│ ├── site-config.ts # 중앙화된 사이트 메타데이터, 작성자 약력, 소셜 링크
│ └── utils.ts # Tailwind cn 헬퍼
├── docs/ # 아키텍처, 계획 및 디자인 근거
│ ├── project.json # 기계 판독 가능한 정식 명세
│ ├── plan/ # 7단계 모듈형 구현 로드맵
│ │ ├── README.md # 마스터 대시보드: 진행 상황 추적 및 단계 인덱스
│ │ ├── 01-discovery-and-architecture.md
│ │ ├── 02-environment-and-cicd.md
│ │ ├── 03-system-health-probe.md
│ │ ├── 04-core-foundations.md
│ │ ├── 05-pages-and-components.md
│ │ ├── 06-server-functions-and-metadata.md
│ │ └── 07-integrations-and-release.md
│ ├── design/ # UX, UI 및 화면 명세
│ │ ├── 01-strategy-brief.md # 목적, 페르소나, 목표, KPI, 벤치마크
│ │ ├── 02-sitemap-and-routes.md # 페이지 인벤토리, 섹션 계층, 렌더링 매트릭스
│ │ ├── 03-ui-design-tokens.md # 의미론적 CSS 토큰, 타이포그래피, 컴포넌트 프리미티브
│ │ └── components/ # 컴포넌트 디자인 명세 및 스티치 스크린샷
│ └── adr/ # 아키텍처 결정 레코드
단계별 실행 런북
1. 자동 워크스페이스 검사 (중단 없음)
[!IMPORTANT] 먼저 검사하고, 나중에 질문하세요. 워크스페이스 파일에서 직접 추론할 수 있는 사실을 사용자에게 묻지 마십시오.
- 워크스페이스 컨텍스트 스캔:
package.json, 잠금 파일 (pnpm-lock.yaml,bun.lockb), 라우팅 구조 (app/vssrc/app/), 컴포넌트 디렉토리,app/globals.css, UI 라이브러리 (shadcn/ui,lucide-react, 애니메이션),next-intl설정 (루트messages/폴더), 기존 라우트 (page.tsx,route.ts), 테스트 및 Docker 설정을 검사합니다. - 전체 검사 체크리스트는 workspace-inspection.md를 참조하세요.
2. 사용자 그릴링 인터뷰 (페이지 ➔ 섹션 ➔ 컴포넌트)
- 적응형 그릴링 인터뷰 진행: 그릴링 프론티어 방법론을 사용하여 구조화된 라운드로 사용자와 상호 작용합니다. 각 질문에 번호를 매기고 권장 답변을 제공합니다.
- 필수 그릴링 순서:
- 페이지 그릴링: 필요한 모든 웹 페이지와 대상 URL 라우트를 열거합니다.
- 섹션 그릴링: 각 페이지에 대해 상단에서 하단까지 모든 콘텐츠 섹션을 식별합니다.
- 컴포넌트 그릴링: 각 섹션에 대해 필요한 모든 UI 컴포넌트를 정의합니다.
- 핵심 질문 영역: 문제 설명, 대상 페르소나, 인증, 데이터 레이어/ORM, i18n 로케일 및 RTL, 시각적 미적 톤, 배포 대상을 다룹니다.
- 인터뷰 템플릿 및 결정 트리 규칙은 grilling-interview.md를 참조하세요.
3. 정식 명세 및 타입-세이프 코드 생성
-
docs/project.json생성: 기술 메타데이터 (패키지 매니저, 컴포넌트 디렉토리, 스타일, UI/애니메이션/테스팅 라이브러리, 지원 언어, 딕셔너리 경로)를 채웁니다. project-schema.md를 참조하고 project.json.template을 배포합니다. -
lib/routes.ts생성: routes.ts.template에서 타입-세이프 라우트 레지스트리를 생성합니다. -
lib/site-config.ts생성: site-config.ts.template에서 중앙화된 사이트 프로필 및 메타데이터를 생성합니다.
4. docs/design/에 디자인 전략 문서화
-
docs/design/01-strategy-brief.md생성: 01-strategy-brief.md.template을 배포합니다. -
docs/design/02-sitemap-and-routes.md생성: 02-sitemap-and-routes.md.template을 배포합니다. -
docs/design/03-ui-design-tokens.md생성: 03-ui-design-tokens.md.template을 배포합니다.
5. 7단계 모듈형 구현 로드맵 생성 (docs/plan/)
-
docs/plan/디렉토리 스캐폴딩: resources/templates/plan/의 템플릿을 사용하여 모듈형 계획 파일을 배포합니다:docs/plan/README.md(마스터 진행 대시보드)docs/plan/01-discovery-and-architecture.md(1단계)docs/plan/02-environment-and-cicd.md(2단계)docs/plan/03-system-health-probe.md(3단계:/api/health활성 프로브)docs/plan/04-core-foundations.md(4단계: 환경 변수, i18n, 테마 토큰, 레이아웃, OTel)docs/plan/05-pages-and-components.md(5단계: 표준 페이지 및 컴포넌트 체크리스트 with SEO 및 지원 파일)docs/plan/06-server-functions-and-metadata.md(6단계: 서버 액션, API 라우트, 글로벌 SEO)docs/plan/07-integrations-and-release.md(7단계: 통합 및 프로덕션 릴리스)
- 필수 페이지 수준 파일이 있는 단일 진실 공급원: 5단계 (
05-pages-and-components.md)는 페이지 및 컴포넌트에 대한 독점적인 표준 체크리스트입니다. 모든 페이지에 대해page.tsx,loading.tsx,error.tsx,generateMetadata,JSON-LD Schema,generateStaticParams()(동적 라우트의 경우)에 대한 하위 체크리스트 작업을 강제합니다. - 페이지 완료 규칙: 5단계에서 페이지 항목을
- [x]로 표시하는 것은 모든 하위 컴포넌트 체크리스트 항목과 페이지 수준 SEO/지원 작업이 완료된 경우에만 가능합니다. - 전체 단계 지침은 plan-checklist-structure.md를 참조하세요.
6. 마무리 및 완료 게이트
- 사용자에게 워크스페이스 결과,
docs/project.json의 명세,docs/plan/README.md의 로드맵을 자세히 설명하는 간결한 요약 보고서를 제공합니다. - 다운스트림 Next.js 스킬을 자동으로 호출하지 마십시오. 실행을 종료하고 사용자가 계획을 검토할 수 있도록 합니다.
엣지 케이스 및 알려진 AI 함정
[!WARNING]
- 명령어 체이닝:
&&,||,;를 사용하여 한 줄에 복합 명령어를 실행하지 마십시오. 항상 터미널 명령어를 개별적으로 실행하십시오.- 검사 전 질문:
package.json또는 디렉토리 목록에서 직접 읽을 수 있는 기본 사실을 사용자에게 묻지 마십시오.- 역전된 마일스톤 순서: 상태 프로브 (
/api/health)는 3단계에 속하며, 페이지/컴포넌트 구현 전에 핵심 기반 (i18n, Theme, Layouts, OTel)이 4단계에서 수행됩니다.- 페이지 수준 파일 누락: 5단계 체크리스트를 작성할 때 어떤 페이지에 대해서도
loading.tsx,error.tsx,generateMetadata또는 JSON-LD 스키마 작업을 누락하지 마십시오.- 페이지 목록 중복: 모든 페이지 및 컴포넌트 추적은 엄격히
docs/plan/05-pages-and-components.md에 유지하십시오.- 조기 페이지 체크오프: 5단계의 페이지는 모든 하위 컴포넌트 및 페이지 수준 지원 파일이 완료될 때까지
- [ ]로 유지되어야 합니다.- 잘못된 딕셔너리 위치: Next.js i18n 설정에서 딕셔너리는 루트
messages/(예:messages/en.json)에 위치하며,app/dictionaries에 절대 위치하지 않습니다.- 다운스트림 스킬 생성: 계획 완료 시 구현 또는 스타일링 스킬을 자동으로 트리거하지 말고 중단하고 사용자의 지시를 기다리십시오.
출력 요약 스키마
계획 단계를 마치면 다음 형식으로 요약을 제공하십시오:
### Next.js 프로젝트 계획 완료
- **정식 명세**: `[docs/project.json](file:///...)`
- **타입-세이프 레지스트리**: `[lib/routes.ts](file:///...)` | `[lib/site-config.ts](file:///...)`
- **디자인 및 전략 명세**: `[docs/design/01-strategy-brief.md](file:///...)`, `[docs/design/02-sitemap-and-routes.md](file:///...)`, `[docs/design/03-ui-design-tokens.md](file:///...)`
- **모듈형 로드맵 대시보드**: `[docs/plan/README.md](file:///...)`
- **식별된 페이지**: 총 X개의 라우트 매핑됨
- **식별된 컴포넌트**: 총 Y개의 컴포넌트가 Z개의 섹션에 걸쳐 카탈로그됨
- **완료된 단계**: N / 7 단계 확인됨
_계획 완료. 컴포넌트 디자인 또는 구현을 진행하려면 `docs/plan/README.md`를 검토하십시오._
참조 가이드 및 템플릿
- 워크스페이스 검사 가이드 — 인터뷰 전 코드베이스 발견 체크리스트.
- 그릴링 인터뷰 가이드 — 다중 라운드 질문 프로토콜 및 문의 영역.
- 프로젝트 스키마 참조 —
docs/project.json의 명세 필드 및 유효성 검사 기준. - 계획 아키텍처 참조 — 7단계 모듈형 로드맵 구조 및 페이지-컴포넌트 규칙.
- 프로젝트 JSON 템플릿 —
docs/project.json용 시작 스키마. - 모듈형 계획 템플릿 —
docs/plan/용 시작 템플릿. - 라우트 TypeScript 템플릿 —
lib/routes.ts용 타입-세이프 라우트 정의. - 사이트 설정 템플릿 —
lib/site-config.ts용 중앙화된 사이트 프로필. - 전략 문서 템플릿 —
docs/design/01-strategy-brief.md용 템플릿. - 사이트맵 및 라우트 템플릿 —
docs/design/02-sitemap-and-routes.md용 템플릿. - UI 디자인 토큰 템플릿 —
docs/design/03-ui-design-tokens.md용 템플릿. - 환경 변수 예제 템플릿 —
.env.example용 단일 진실 공급원 템플릿 (프로덕션 배포를 위해.env로 이름 변경). - 개발 환경 템플릿 —
.env.development용 기본 개발 변수 (로컬 개발, gitignored).