BIGboss248/nextjs-wordpress

Next.js 페이지 및 경로 개발 (nextjs-page-dev)

비동기 경로 파라미터, 지역화된 번역 딕셔너리, 동적 메타데이터, 타입 안전 JSON-LD 구조화 데이터 (schema-dts) 및 정적 사전 렌더링을 사용하여 프로덕션에 바로 투입 가능한 Next.js App Router 페이지를 생성하기 위한 특화 워크플로우입니다.

[!TIP] 모듈식 에셋 및 심층 가이드:

• 스트리밍 및 UI 경계: references/streaming-and-boundaries.md
• 페이지 컨벤션 및 생명주기: references/page-conventions-and-lifecycle.md
• SEO 및 구조화 데이터 가이드: references/seo-structured-data-guide.md
• 재사용 가능 템플릿: resources/templates/
• 검증 스크립트: scripts/verify-page.ps1 (Windows) / scripts/verify-page.sh (Linux)

---

아키텍처 규칙 및 표준

1. 계획 컨텍스트 및 경로 레지스트리

• docs/project.json을 읽어 supported_languages, dictionaries_dir(기본값: "messages"), new_component_dir을 확인합니다.
• 모든 탐색 URL은 @/lib/routes 또는 @/i18n/navigation의 ROUTES를 참조해야 합니다.
• 대상 페이지 경로 계층 구조: app/[locale]/<route-path>/page.tsx (또는 비지역화된 경로의 경우 app/<route-path>/page.tsx).

2. 제로 하드코딩 및 딕셔너리 채우기

• 하드코딩된 사본 없음: 페이지 제목, 헤딩, 설명 및 정적 레이블은 JSX를 작성하기 전에 모든 supported_languages에 걸쳐 messages/[locale].json에 추가되어야 합니다.
• RSC 번역: await getTranslations('<namespace>')를 사용하여 서버 컴포넌트에서 번역을 읽습니다.

3. SEO, 메타데이터 및 JSON-LD

• 동적 메타데이터: 동적 title, description 및 표준 URL(alternates: { canonical: ... })을 제공하는 generateMetadata({ params, searchParams }: Props)를 내보냅니다.
• 구조화 데이터: <script type="application/ld+json">로 감싸고 < 문자를 \u003c로 이스케이프 처리한 schema-dts (WithContext<T>)를 사용하여 타입이 지정된 JSON-LD를 삽입합니다.
• 스키마에 대해서는 references/seo-structured-data-guide.md를 참조하십시오.

4. 정적 사전 렌더링 (generateStaticParams)

• 페이지가 [locale] 동적 세그먼트(또는 다른 동적 세그먼트) 아래에 중첩되어 있고 supported_languages에 1개 이상의 로케일이 포함된 경우, 지원되는 모든 로케일에 대해 { locale }을 반환하는 generateStaticParams()를 내보냅니다.

5. 즉시 탐색 및 세분화된 서스펜스 푸시 다운

• 세분화된 로딩 상태: <Suspense>를 특정 동적 하위 컴포넌트로 푸시 다운하여 정적/캐시된 섹션(헤더, 히어로, 캐시된 제품 정보)이 즉시 정적 쉘 및 앱 쉘로 올라가도록 합니다.
• 옵트아웃: 세그먼트가 본질적으로 동적이고 즉각적인 피드백이 필요하지 않은 경우 export const instant = false를 구성합니다.
• 스트리밍 패턴에 대해서는 references/streaming-and-boundaries.md를 참조하십시오.

---

워크플로우 단계

• 단계 0: 구현 계획 생성 및 승인 게이트

  • docs/project.json 및 lib/routes.ts의 대상 경로 정의를 읽습니다.
  • 페이지 메타데이터, JSON-LD 스키마 유형, 번역 네임스페이스 및 컴포넌트 레이아웃을 공식화합니다.
  • 주요 새 페이지를 생성하는 경우 간결한 구현 계획을 사용자에게 제시합니다.

• 단계 1: 번역 딕셔너리 채우기

  • 모든 로케일 파일(messages/en.json, messages/fa.json 등)에 전용 페이지 네임스페이스 아래에 페이지 제목, 메타 설명 및 페이지 본문 사본을 추가합니다.

• 단계 2: 동반 스켈레톤 생성 (loading.tsx)

  • 페이지가 콘텐츠를 스트리밍하거나 데이터를 가져오는 경우 loading.tsx.template에서 loading.tsx를 배포합니다.

• 단계 3: 페이지 컴포넌트 구현 (page.tsx)

  • page.tsx.template을 배포 및 사용자 지정합니다:
    1. 비동기 props 인터페이스 정의 (params: Promise<{ locale: string, ... }>, searchParams).
    2. 동적 제목 및 표준 대체 URL을 해결하는 generateMetadata() 내보내기.
    3. 지역화/동적 경로에 대한 generateStaticParams() 내보내기.
    4. <new_component_dir>/<page-name>/의 섹션 컴포넌트를 구성하는 페이지 RSC 구현.
    5. <JsonLd> 구조화 데이터 컴포넌트 렌더링.

• 단계 4: 검증 및 상태 확인

  • 페이지 검증 스크립트를 실행합니다:
    • Windows (PowerShell):

      pwsh .agents/skills/nextjs-page-dev/scripts/verify-page.ps1 -RoutePath <route_dir>
      

    • Linux / macOS (Bash):

      bash .agents/skills/nextjs-page-dev/scripts/verify-page.sh <route_dir>
      

  • 타입스크립트 오류 또는 누락된 딕셔너리가 없는지 확인합니다.

• 단계 5: 구현 계획 체크리스트 동기화

  • docs/plan/05-pages-and-components.md에서 완료된 페이지 인프라 항목(page.tsx, loading.tsx, error.tsx, generateMetadata, JSON-LD Schema, generateStaticParams())을 체크합니다.
  • 이 페이지에 대한 모든 컴포넌트 하위 체크리스트와 페이지 인프라 작업이 완료되면 상위 페이지 항목을 체크합니다 (- [x]).