BIGboss248/nextjs-wordpress

Next.js コンポーネント & スケルトン開発 (nextjs-component-dev)

本番環境対応のReact Server Components (RSC) およびクライアントコンポーネントを作成するための専門ワークフローです。Suspenseスケルトン、二層構造のTDDテスト（Jest + RTLユニットテストとPlaywright統合/ハイドレーション/ビジュアルチェック）、next-intl辞書バックアップ翻訳、セマンティックテーマトークン、そして next-devtools MCPによるライブランタイム診断を備えています。

[!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)

• Codebase Memory 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 またはプロップとしてクライアントラッパーに渡します。"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 を使用します。
• 画像: 常に next/image を明示的な寸法または fill、レスポンシブ sizes、およびファーストビューのLCPアセットには priority と共に使用します。

6. インスタントナビゲーション、詳細なSuspense、キャッシュアーキテクチャ

• インスタントコンポーネントのための3つのレバー:
  1. プッシュダウン: リクエスト固有の非同期操作（await params、await searchParams、cookies()、headers()、キャッシュされていないDB/API呼び出し）を、<Suspense> でラップされたリーフサブコンポーネントに抽出します。静的な親と兄弟は、直接静的/App Shellに引き上げられます。
  2. キャッシュ: 関数/コンポーネントレベルで 'use cache' と cacheLife、cacheTag を組み合わせます。セッションブリッジングパターンを使用します:
     • パターンA（抽出して渡す）: cookies() からセッション属性（例: team_id、role、tier）を抽出し、'use cache' 関数に引数として渡すことで、キャッシュされたデータが一致する属性を持つすべてのユーザー間で共有されるようにします（コストはユーザーセッション数ではなく、チーム/属性数に応じてスケーリングされます）。
     • パターンB（"use cache: private"）: 厳密にユーザー固有のセッションルックアップには、App Shellと共に移動する stale >= 5m のブラウザのみのセッションキャッシュを使用します。
  3. プリフェッチ戦略と密度の高いグリッド:
     • デフォルトのApp Shellプリフェッチ（<Link> / prefetch={null}）: ルートごとに1つの共有静的/App Shellをプリフェッチします。コストは制限されています（$O( ext{routes})$）、リンクあたりのサーバー呼び出しはゼロです。密度の高いフィード、カードグリッド（50枚以上のカード）、一括ナビゲーションに使用します。
     • リンクごとのプリフェッチ（<Link prefetch={true}>）: ナビゲーション前に動的URLデータ（params、searchParams）を解決し、表示されているリンクごとに1回のサーバー呼び出しを行います。意図性の高い主要な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 を定義します。
• サーバープリフェッチ: 内部のDB関数を直接呼び出して、未完了のプリフェッチ（void queryClient.prefetchQuery(...)）をトリガーします（サーバー上の相対フェッチはゼロ）。<HydrationBoundary> でデハイドレートします。
• ストリームドコンポーネント: <Suspense fallback={<[ComponentName]Skeleton />}> 内で useSuspenseQuery を使用します。
• 楽観的ミューテーション: onMutate キャッシュスナップショットと onError ロールバックを備えた useMutation を使用します。updateTag(cache.tag) でサーバーアクションを呼び出します。

8. 二層テストの役割分担 (Jest vs. Playwright)

• Jest + RTL ([ComponentName].test.tsx):
  • jsdom での高速フィードバックループ。
  • プロップのバリエーション、条件付き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, ...) ヘルパーを使用して、動的サーバーストリーミングが解決される前に、静的シェルとプリフェッチされたApp Shellが即座にレンダリングされることをアサートします。
  • ゼロハイドレーションミスマッチ: ブラウザコンソールイベント（page.on('console')）をリッスンして、React SSRハイドレーションの警告を検出し、テストを失敗させます。
  • ビジュアルとBiDiのリグレッション: テーマ（ライト/ダークOKLCH変数）とテキスト方向（dir="ltr" 対 dir="rtl"）にわたって expect(page).toHaveScreenshot() を使用します。
  • ネットワーク回復力: page.route() を使用して、低速なネットワーク応答（Suspenseスケルトンがジオメトリと一致してCLSを防ぐことを確認）および500エラーバウンダリをテストします。
• 詳細なテスト標準: references/testing-architecture-guide.md を参照してください。

---

フェーズ0: 実装計画と承認ゲート

[!IMPORTANT] 実行前の計画: 書き込み操作、辞書の変更、またはリポジトリへのコンポーネント作成を実行する前に、常に implementation_plan.md アーティファクトを生成して提示し、計画されたすべてのファイル作成、変更、TypeScriptコントラクト、翻訳辞書の追加、およびTDDテストケースを文書化してください。実行を続行する前に、ユーザーの確認/承認を待ってください。

実装計画は以下をカバーする必要があります:

1. ターゲットアーキテクチャとパス: 完全なターゲットディレクトリ（<new_component_dir>/<page_or_global>/<ComponentName>/）と分類（RSC 対 クライアントリーフコンポーネント）。
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アノテーションを持つプロップインターフェースと型。
4. 辞書戦略: docs/project.json のすべての supported_languages にわたって messages/[locale].json に追加する明示的な翻訳名前空間とキー（ハードコードされた文字列やファイル内モック辞書はゼロ）。
5. テーマトークンとスタイリング: 特定されたセマンティックOKLCH CSS変数と論理レイアウトクラス。
6. テストと診断戦略:
   • Jestユニットテスト（[ComponentName].test.tsx）: モック設定（next/navigation）、プロップバリエーション、コールバックアサーション、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）を持つプロップインターフェースを定義します。
  • サポートされている言語が複数ある場合、コンポーネントは最初に翻訳をフェッチし、失敗した場合はフォールバックを使用する必要があります。

• ステップ 3: TDDベースラインユニットテスト（Jest + RTLを使用した [ComponentName].test.tsx）

  • コンポーネントを実装する前に [ComponentName].test.tsx を記述します。
  • next/navigation フック（useRouter、usePathname、useSearchParams）をモックします。
  • レンダリングされたコンポーネントを、辞書 messages とアクティブな locale を提供する NextIntlClientProvider でラップします。
  • 方向属性（dir="rtl" 対 dir="ltr"）、デフォルトのプロップ、インタラクティブなコールバック（@testing-library/user-event）、Suspenseスケルトンフォールバック、セマンティックARIAロールをテストします。

• ステップ 4

…

[翻訳のため省略]