BIGboss248/nextjs-wordpress

Next.js 컴포넌트 및 스켈레톤 개발 (nextjs-component-dev)

Suspense 스켈레톤, 이중 계층 TDD 테스트(Jest + RTL 단위 테스트 및 Playwright 통합/수화일치/시각 테스트), next-intl 사전 기반 번역, 시맨틱 테마 토큰 및 next-devtools MCP를 통한 실시간 런타임 진단과 함께 프로덕션에 바로 사용 가능한 React 서버 컴포넌트(RSC) 및 클라이언트 컴포넌트를 생성하기 위한 특화된 워크플로우입니다.

[!TIP] 모듈식 에셋 및 템플릿:

• Next.js 문서 검색 및 컨텍스트: references/nextjs-docs-lookup.md
• 테스트 아키텍처 및 검증: references/testing-architecture-guide.md
• Storybook 표준 및 분리: references/storybook-reference.md
• 즉시 탐색 및 프리페칭: references/instant-navigation-and-prefetching.md
• Next DevTools 디버깅 가이드: references/next-devtools-debugging.md
• 캐싱 및 재검증: references/caching-and-revalidation.md
• 코드 템플릿: resources/templates/ (컴포넌트, 스켈레톤, Jest 단위 테스트, Playwright 스펙)
• 참조 구현: examples/
• 검증 스크립트: scripts/verify-dev.ps1 (Windows) / scripts/verify-dev.sh (Linux)

---

아키텍처 규칙 및 표준

1. 계획 컨텍스트 및 경로

• docs/project.json을 읽어 package_manager, new_component_dir, style_file_dir, component_library, dictionaries_dir (기본값: "messages") 및 supported_languages를 확인합니다.
• 모든 내부 경로는 @/lib/routes의 ROUTES를 사용해야 합니다.
• 모든 작성자/사이트 메타데이터는 @/lib/site-config의 SITE_CONFIG를 사용해야 합니다.
• 대상 경로 계층 구조: <new_component_dir>/<page_or_global>/<ComponentName>/
  • 카테고리: global/은 공유 레이아웃 크롬용; <page-name>/ (예: home/, about/, lab/)은 페이지 범위 섹션용.

2. Next.js 내부 문서 조회 (node_modules/next/dist/docs)

• 코드베이스 메모리 MCP를 통한 로컬 문서 검색: 컴포넌트를 생성할 때마다 codebase-memory MCP 도구(search_code, search_graph, get_code_snippet)를 사용하여 node_modules/next/dist/docs/에 있는 로컬 Next.js 배포 문서를 적극적으로 쿼리하고 검사하여 관련 API 시그니처, 지시문('use cache', 'use client', 'use server'), 내장 컴포넌트(next/image, next/link, next/font, <Form>), 탐색 훅(useRouter, usePathname) 및 캐싱 정책(cacheLife, cacheTag)을 확인합니다.
• 비권장 사항 및 할루시네이션 제거: 가정이나 오래된 Next.js 패턴에 절대 의존하지 마십시오. 설치된 패키지 버전과 일치하는 로컬 node_modules/next/dist/docs가 기본 정보 소스입니다. references/nextjs-docs-lookup.md를 참조하십시오.

3. 개발 서버 및 Next DevTools 프로토콜

• 개발 서버 확인 및 연결: 컴포넌트 개발 전/중에 next-devtools MCP 서버(nextjs_index)를 통해 Next.js 개발 서버가 실행 중인지 확인합니다.
• 서버 실행 중: 즉시 실행 중인 서버와 포트에 연결하고, 재시작하지 마십시오.
• 서버 미실행: 백그라운드에서 개발 서버를 시작하고(pnpm dev, IsDaemon: true), nextjs_index를 통해 연결을 확인합니다.
• 런타임 디버깅: 컴포넌트 구현 후 next-devtools(nextjs_call)를 쿼리하여 오류를 검사하고, 빌드 상태를 확인하며, 런타임 문제를 즉시 진단합니다. references/next-devtools-debugging.md를 참조하십시오.

4. RSC 경계 및 리프 클라이언트 푸시다운

1. 기본 서버 컴포넌트: 컴포넌트를 서버 렌더링(async function) 상태로 유지합니다.
2. "use client" 푸시다운: 대화형 핸들러(버튼, 토글, 폼 입력)를 작은 리프 클라이언트 컴포넌트로 격리합니다.
3. RSC 구성: 서버 컴포넌트를 children 또는 props로 클라이언트 래퍼에 전달합니다. "use client" 파일 내에서 서버 컴포넌트를 가져오지 마십시오.

5. 스타일링, 논리적 속성 및 테마 토큰

• 시맨틱 토큰: app/globals.css에 정의된 시맨틱 CSS 변수(bg-background, text-foreground, border-border, text-muted-foreground)만 독점적으로 사용합니다. 하드코딩된 16진수 색상(#FAFAFA) 또는 원시 색상 스케일(bg-blue-500)은 금지됩니다.
• 클래스 병합: 항상 cn(...) (clsx + tailwind-merge)을 사용하여 클래스를 병합합니다.
• 논리적 속성 (BiDi): Tailwind 논리적 속성(ms-, pe-, ps-, me-, start, end)만 독점적으로 사용합니다. 물리적 방향 클래스(ml-, mr-, pl-, pr-, left-, right-)는 금지됩니다.
• 진행 링크: 기본 탐색, 히어로 CTA 및 대화형 카드에는 @vercel/react-transition-progress의 <Link>를 사용하고, 정적 유틸리티 링크에는 표준 next/link를 사용합니다.
• 이미지: 항상 명시적인 크기 또는 fill, 반응형 sizes, 그리고 LCP 에셋의 경우 priority와 함께 next/image를 사용합니다.

6. 즉시 탐색, 세분화된 Suspense 및 캐싱 아키텍처

• 즉시 컴포넌트를 위한 세 가지 레버:
  1. 푸시다운: 요청별 비동기 작업(await params, await searchParams, cookies(), headers(), 캐시되지 않은 DB/API 호출)을 <Suspense>로 감싸진 리프 하위 컴포넌트로 추출합니다. 정적 부모 및 형제는 정적/앱 셸로 직접 승격됩니다.
  2. 캐싱: 함수/컴포넌트 수준에서 'use cache'를 cacheLife 및 cacheTag와 쌍으로 사용합니다. 세션 브리징 패턴 사용:
     • 패턴 A (추출 및 전달): 세션 속성(예: team_id, role, tier)을 cookies() 외부에서 추출하고 'use cache' 함수에 인수로 전달하여 캐시된 데이터가 일치하는 속성을 가진 모든 사용자 간에 공유되도록 합니다(비용은 사용자 세션 수가 아닌 팀/속성 수에 따라 확장됨).
     • 패턴 B ("use cache: private"): 엄격히 사용자별 세션 조회의 경우, 앱 셸과 함께 이동하는 stale >= 5m인 브라우저 전용 세션 캐싱을 사용합니다.
  3. 프리페칭 전략 및 밀집 그리드:
     • 기본 앱 셸 프리페칭 (<Link> / prefetch={null}): 경로당 하나의 공유 정적/앱 셸을 프리페칭합니다. 비용 제한($O(\text{routes})$), 링크당 서버 호출 제로. 밀집 피드, 카드 그리드(50개 이상의 카드) 및 대량 탐색에 사용합니다.
     • 링크별 프리페칭 (<Link prefetch={true}>): 표시되는 링크당 1회의 서버 호출로 탐색 전에 동적 URL 데이터(params, searchParams)를 확인합니다. 스켈레톤 깜박임을 제거해야 하는 높은 의도의 기본 CTA, 히어로 작업 또는 마스터-디테일 목록 항목에 드물게 사용합니다.
     • 밀집 카드 그리드: 피드의 수십 개 카드에 걸쳐 절대 prefetch={true}를 일괄 적용하지 마십시오. 기본 <Link>를 유지하거나 호버/포커스 의도 프리페칭(router.prefetch())을 사용합니다.
• 세분화된 로딩 상태 (전체 페이지 플래시 방지): 전체 페이지 스켈레톤을 깜빡이는 단일 최상위 <Suspense> 경계로 전체 컴포넌트나 페이지를 감싸지 마십시오. 제목, 레이아웃 프레임 및 캐시된 콘텐츠를 즉시 표시하고, <Suspense>를 동적 스트리밍 슬롯 주위에만 엄격히 배치합니다.
• 네이티브 Next.js 16 캐싱 지시문: references/instant-navigation-and-prefetching.md 및 references/caching-and-revalidation.md를 참조하십시오.

7. TanStack Query 및 서버 프리페칭

• 통합 캐시 계약: 명시적인 staleTime(예: 30_000 ms)으로 key, tag 및 queryOptions를 정의합니다.
• 서버 프리페칭: 대기되지 않은 프리페치(void queryClient.prefetchQuery(...))를 트리거하여 내부 DB 함수를 직접 호출합니다(서버에서 상대 fetch 제로). <HydrationBoundary>로 수화를 해제합니다.
• 스트리밍된 컴포넌트: <Suspense fallback={<[ComponentName]Skeleton />}> 내에서 useSuspenseQuery를 사용합니다.
• 낙관적 변이: onMutate 캐시 스냅샷 및 onError 롤백과 함께 useMutation을 사용하고, updateTag(cache.tag)로 서버 액션을 호출합니다.

8. 이중 계층 테스트 업무 분담 (Jest vs. Playwright)

• Jest + RTL ([ComponentName].test.tsx):
  • jsdom에서 빠른 피드백 루프.
  • Prop 조합, 조건부 UI 요소 및 빈/null 상태.
  • @testing-library/user-event를 통한 사용자 상호 작용(fireEvent 절대 사용 금지).
  • Next.js 라우팅 목업(next/navigation의 useRouter, usePathname, useSearchParams).
  • NextIntlClientProvider 내부의 next-intl 사전 보간 및 복수형 검사.
  • 접근 가능한 역할 쿼리(screen.getByRole) 및 자동화된 a11y 검사(jest-axe).
• Playwright ([ComponentName].spec.ts 또는 페이지 수준 스펙):
  • 실제 브라우저 실행 (Chromium/WebKit/Firefox).
  • 즉시 셸 어설션 (@next/playwright): instant(page, ...) 헬퍼를 사용하여 정적 셸 및 프리페치된 앱 셸이 동적 서버 스트리밍이 해결되기 전에 즉시 렌더링되는지 확인합니다.
  • 제로-수화일치 불일치: 브라우저 콘솔 이벤트(page.on('console'))를 수신 대기하여 React SSR 수화일치 경고를 감지하고 테스트를 실패 처리합니다.
  • 시각적 및 BiDi 회귀: 테마(밝은 모드 vs. 어두운 모드 OKLCH 변수) 및 텍스트 방향(dir="ltr" vs. dir="rtl")에 걸쳐 expect(page).toHaveScreenshot()을 사용합니다.
  • 네트워크 탄력성: page.route()를 사용하여 느린 네트워크 응답(CLS를 방지하기 위해 Suspense 스켈레톤이 지오메트리와 일치하는지 확인) 및 500 오류 경계를 테스트합니다.
• 상세 테스트 표준: references/testing-architecture-guide.md를 참조하십시오.

---

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

[!IMPORTANT] 실행 전 계획: 쓰기 작업을 실행하거나, 사전을 수정하거나, 저장소에 컴포넌트를 생성하기 전에 항상 계획된 모든 파일 생성, 수정, TypeScript 계약, 번역 사전 추가 및 TDD 테스트 케이스를 설명하는 implementation_plan.md 아티팩트를 생성하고 제시하십시오. 실행을 진행하기 전에 사용자 확인/승인을 기다리십시오.

구현 계획은 다음을 포함해야 합니다:

1. 대상 아키텍처 및 경로: 전체 대상 디렉토리(<new_component_dir>/<page_or_global>/<ComponentName>/) 및 분류(RSC vs. 클라이언트 리프 컴포넌트).
2. 참조한 Next.js 로컬 문서: node_modules/next/dist/docs/에서 확인한 특정 문서 경로(예: 04-api-reference/04-components/image.md, 03-directives/use-cache.md, 04-api-reference/02-functions/use-router.md).
3. TypeScript 계약: 엄격한 영어 TSDoc 주석이 있는 Prop 인터페이스 및 타입.
4. 사전 전략: docs/project.json의 모든 supported_languages에 걸쳐 messages/[locale].json에 추가할 명시적인 번역 네임스페이스 및 키 (하드코딩된 문자열이나 파일 내 모의 사전 없음).
5. 테마 토큰 및 스타일링: 식별된 시맨틱 OKLCH CSS 변수 및 논리적 레이아웃 클래스.
6. 테스트 및 진단 전략:
   • Jest 단위 테스트 ([ComponentName].test.tsx): 목업 구성(next/navigation), prop 변형, 콜백 어설션, NextIntlClientProvider 통합 및 a11y 역할 쿼리.
   • Playwright 통합 시나리오 ([ComponentName].spec.ts): 시각적 스냅샷 대상(라이트/다크 테마 토큰, LTR vs. RTL 논리적 레이아웃), 네트워크 스로틀링/스켈레톤 지오메트리 확인 및 수화일치 검증 리스너.
   • Next DevTools 진단: next-devtools를 통한 런타임 오류 및 컴파일 검사.
7. 검증 게이트: 실행할 정확한 검증 명령어 (verify-dev.ps1, 대상 단위 테스트 및 Playwright e2e 스펙).

---

워크플로우 단계

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

  • codebase-memory MCP(search_code, search_graph)를 통해 node_modules/next/dist/docs를 검색하고 검사하여 계획된 컴포넌트에서 사용되는 Next.js API, 지시문, 훅 또는 컴포넌트가 있는지 확인하여 최신 컨텍스트를 보장합니다.
  • 컴포넌트 요구 사항을 종합하고, docs/project.json을 스캔하고, 참조한 문서 및 계약을 문서화한 implementation_plan.md를 생성합니다.
  • 아티팩트에서 request_feedback = true 및 user_facing = true를 설정합니다.
  • 코드를 작성하기 전에 사용자 검토 및 명시적 승인을 기다립니다.

• 1단계: 개발 서버 확인 및 Next DevTools 연결

  • next-devtools MCP를 nextjs_index를 통해 쿼리하여 실행 중인 Next.js 개발 서버 인스턴스를 감지합니다.
  • 개발 서버 실행 중: 활성 포트 및 서버 인스턴스에 연결하고, 재시작하지 않고 개발을 계속합니다.
  • 개발 서버 미실행: 백그라운드에서 개발 서버를 시작하고(pnpm dev, IsDaemon: true), nextjs_index로 발견을 확인합니다.

• 2단계: 사전 채우기 및 TypeScript 계약 정의

  • docs/project.json을 읽어 dictionaries_dir(기본값은 messages) 및 supported_languages를 확인합니다.
  • 컴포넌트의 번역 네임스페이스 및 키를 정의합니다.
  • JSX를 작성하기 전에 지원되는 모든 언어에 대해 모든 사전 파일(messages/en.json, messages/fa.json 등)을 정확한 번역으로 채웁니다.
  • 엄격한 영어 TSDoc 주석(@param, @defaultValue, @returns)으로 Prop 인터페이스를 정의합니다.
  • 지원되는 언어가 두 개 이상인 경우, 컴포넌트는 먼저 번역을 가져와야 하며 실패할 경우 대체 텍스트를 사용해야 합니다.

• 3단계: TDD 기준 단위 테스트 ([ComponentName].test.tsx via Jest + RTL)

  • 컴포넌트를 구현하기 전에 [ComponentName].test.tsx를 작성합니다.
  • next/navigation 훅(useRouter, usePathname, useSearchParams)을 목업합니다.
  • 렌더링된 컴포넌트를 사전 messages 및 활성 locale을 제공하는 NextIntlClientProvider로 래핑합니다.
  • 방향 속성(dir="rtl" vs. dir="ltr"), 기본 props, 대화형 콜백(@testing-library/user-event), Suspense 스켈레톤 폴백 및 시맨틱 ARIA 역할을 테스트합니다.

• 4단계: ...

[truncated for translation]