specsfy-specialist-nextjs

Next.js

使用する場合

• プロジェクトが next／next.config に依存し、タスクにルート、レイアウト、Server/Client Component、Server Action、route handler、キャッシュ、middleware、metadata、デプロイのいずれかが関わる場合に使用します。
• データのウォーターフォール、hydration mismatch、または古いデータやユーザー間で共有されたデータをキャッシュが返す問題の診断にも使用します。
• フレームワークに依存しないフック、状態、コンポーネントの構成には使用しません。その場合は $specsfy-specialist-react を使い、server/client の境界に関する作業でのみこちらに戻ります。
• ルートが mutation、アップロード、機密データを公開する場合は $specsfy-specialist-application-security と組み合わせます。症状が SLO を超える Web Vitals または TTFB の場合は、$specsfy-specialist-performance-engineering と組み合わせます。

フロー

1. Next.js のバージョン、ルーター（App または Pages）、ランタイム（Node または Edge）、デプロイ先、アクティブな実験的フラグを確認します。キャッシュと Server Components のセマンティクスはバージョンによって異なります。
2. 変更するルートをマッピングします。レイアウト、loading、error、not-found、データ（server）とインタラクション（client）の境界を確認します。
3. コンポーネントはデフォルトで Server にします。フック、イベント、ブラウザー API が本当に必要な最下層のコンポーネントにのみ "use client" を指定します。手軽だからという理由でレイアウトやページ全体に指定してはいけません。
4. 各データソースのキャッシュ、再検証、タグを明示的に定義します。デフォルトの挙動は、想定ではなく、インストール済みバージョンの仕様として扱います。
5. 各 Server Action と route handler で、公開 HTTP エンドポイントと同様に入力を検証し、認可を確認します。実際に公開 HTTP エンドポイントだからです。
6. metadata、ストリーミング（loading.js／Suspense）、画像／フォント、エラーからの復旧経路（error.js、not-found.js）を設計します。
7. lint、typecheck、テスト、本番ビルドを実行し、next dev だけでなく、対象の adapter／ホストの実際のランタイムで結果を確認します。

パターン

• フックのエラーを「解決」するためにツリー全体を "use client" にしないでください。インタラクティブ性は適切な最下層のコンポーネントに分離します。
• Client Component 内にシークレット、データベースクライアント、server-only モジュールをインポートしてはいけません。バンドラーがブラウザーに送信される JS に含める可能性があります。
• データを使う側のできるだけ近くでデータを取得します。実際には必要ない依存関係によって連続するリクエストが発生する、回避可能なウォーターフォールを測定し、解消します。
• キャッシュはルートごとに明示的な契約として扱います。各データソースが静的、時間による再検証、タグによる再検証、動的のいずれかを宣言します。インストール済みバージョンを確認せず、デフォルトを継承してはいけません。
• キャッシュ済みデータに影響する mutation の直後に、再検証（revalidatePath／revalidateTag）を行います。行わないと UI に古い状態が表示されます。
• すべての Server Action を公開エンドポイントと同じ規律で保護します。認証し、オブジェクト単位で認可し、ペイロードを検証します。クライアントは想定される UI フローを経ずに、Server Action を直接呼び出せます。
• middleware は、ルートのランタイムと互換性のある短いロジックにのみ使います（Edge では API に制限があります）。重いロジックは route handler またはアプリケーション層に置きます。
• ヘッダー、ストリーミング、時間制限など、ホスト／adapter 固有の挙動との結合は暗黙にせず、文書化します。

アンチパターン

• 子コンポーネントにインタラクティブ性が必要だからという理由だけで、layout.tsx または page.tsx の先頭に "use client" を置くと、サブツリー全体がクライアントに移り、Server Components のメリットが失われます。
• キャッシュや重複排除をせずに、ネストされた複数のコンポーネントで同じデータを取得すると、ネットワークウォーターフォールに見える逐次リクエストの連鎖が発生します。
• Server Action でデータを変更しても、対応するパスやタグを再検証しないと、完全なリフレッシュを行うまで古いキャッシュが表示され、UI が「壊れている」ように見えます。
• Client Component 内で、公開用プレフィックス（NEXT_PUBLIC_）のない環境変数を信頼しても、ブラウザーのバンドルには含まれません。
• Server Action は「UI からしかアクセスできない」と考えて認可を省略してはいけません。Server Action は他のルートと同じ HTTP ルートであり、直接呼び出せます。

検証

• next build を完全に実行し（プロジェクトの lint/typecheck も実施）、出力されるルートレポート（静的 ○、動的 λ、ISR）を読み、フローのステップ 4 で宣言した意図と一致していることを確認します。
• 変更した各ルートで loading、error、not-found、リダイレクト、認可をテストします。クライアントサイド遷移なしで URL に直接アクセスするケースも含めます。
• キャッシュのヒット／ミスと無効化を実証します。データを変更し、ルートが再検証されることを確認し、キャッシュキーのスコープ設定が不適切なために、異なるユーザー／セッション間でデータが漏えいしないことを確かめます。
• パフォーマンスが重要なルートでは、変更の前後でクライアントバンドル、画像、フォント、Web Vitals（LCP、INP、CLS）を測定します。
• その証拠がないまま、ルートを「サーバーファースト」や「キャッシュが適切」と断言してはいけません。根拠のない断定的な表現は禁止です。

関連するスキル

• $specsfy-specialist-astro は Astro プロジェクトとそのアイランドを扱います。キャッシュやサーバー／クライアントの境界を、異なるフレームワーク間で流用しないでください。
• $specsfy-specialist-web-accessibility は、ルートや Client Components における WCAG、フォーカス、支援技術を詳しく扱います。
• $specsfy-specialist-react は、フレームワークに依存しないフック、状態、エフェクト、コンポジションを扱います。重要な Client Component には、必ず併用してください。
• $specsfy-specialist-react-ui-components と $specsfy-specialist-ui-design は、ここでサーバー／クライアントの境界を決める前に、ビジュアルライブラリとページのコンポジションを扱います。
• $specsfy-specialist-application-security は、Server Actions や route handlers における認可、アップロード、機密データを扱います。
• $specsfy-specialist-performance-engineering は、Web Vitals、TTFB、パフォーマンスのリグレッションを、独自の方法論で調査します。
• $specsfy-specialist-typescript は、ルートの params、Server Action の payload、データ取得の戻り値を安全に型付けする際に役立ちます。
• $specsfy-specialist-tailwind-css と $specsfy-specialist-shadcn-ui は、各 Server/Client Component 内でレンダリングされるスタイル層とビジュアルコンポーネントを扱います。

公式の情報源とともに、サーバー／クライアントの境界、キャッシュ、Server Actions、ストリーミング、セキュリティ、本番環境向けチェックリストを確認するには、references/standards.md をお読みください。