Next.js App Router 特有のバグを最短で潰すプロンプト

いつ使うか

App Router 移行後に「Server Component から useState を呼んでる」「fetch のキャッシュが効きすぎ/効かない」「params が Promise になって await 漏れ」みたいな、Pages Router 時代には無かった種類のバグを片付けたい時。一般的な React デバッグだと拾えない App Router 固有の罠を構造的にチェックさせる。

プロンプト本文 (コピペして使う)

あなたは Next.js 14/15 App Router のシニアエンジニアです。以下のバグを App Router 固有の観点で原因特定してください。

## 環境
- Next.js バージョン: <例: 15.0.3>
- ランタイム: <node / edge>
- デプロイ先: <Vercel / Cloudflare / 自前 Node>

## バグ事象
- 期待挙動: <例: /products/[id] でサーバー側 fetch した商品を表示>
- 実際の挙動: <例: ビルドは通るがリクエストで Error: Dynamic server usage>
- エラーログ: <貼る>

## 関連コード
```tsx
<該当の page.tsx / layout.tsx / route.ts / Server Action>
```

## App Router 固有チェック観点 (該当に○+理由)
1. **Server / Client の境界違反** ('use client' 無しで useState/useEffect 使用、Server Component から Client にイベントハンドラ直渡し)
2. **params / searchParams の async 化** (Next 15 で Promise になった、await 忘れ)
3. **fetch のキャッシュ挙動** (no-store / revalidate / force-cache の指定漏れ、cookies()/headers() 使用で動的化)
4. **Server Action の使い方** ('use server' ディレクティブ、FormData/直接呼び出しの違い)
5. **Route Handler vs Server Action** の使い分けミス
6. **Streaming / Suspense 境界** (loading.tsx の有無、Suspense fallback 漏れ)
7. **revalidatePath / revalidateTag** の呼び忘れ・粒度ミス
8. **middleware の matcher** (除外パスを書き忘れて static asset まで通っている)
9. **環境変数の Server/Client 露出** (NEXT_PUBLIC_ プレフィックス漏れ、逆にサーバー秘密を Client に持ち込み)

## 出力
1. 該当する観点と一次原因 (上記番号付きで)
2. 修正パッチ (before/after の diff)
3. 再発防止のための追加対策 (eslint-config-next のルール / 型補強 / テスト)
4. 同じ罠を踏みやすい近傍ファイルの指摘 ("このプロジェクトで他にも怪しい箇所")

## 制約
- 「とりあえず 'use client' を付けて回避」のような対症療法は禁止 (構造的に正しい配置を提案)
- Pages Router 時代の API (getServerSideProps 等) を引きずる提案はNG
- Next.js のバージョン依存挙動は明示 (Next 14 / 15 のどちらの話か)

効くポイント

  1. App Router 固有9観点を渡すと、汎用 React デバッグでは拾えない罠が拾える
  2. 「'use client' で全部回避」を禁止すると、構造を壊さない解決策が出る
  3. 近傍ファイルの怪しい箇所まで聞くと、芋づる式に同種バグを潰せる

関連プロンプト

よくある質問

Next.js 13 や Pages Router でも使えますか?
9 観点のうち、Server/Client 境界・fetch キャッシュ・middleware は Next.js 13 App Router でも適用できます。params の async 化は Next 15 固有なので 13/14 では関係ありません。Pages Router 専用プロジェクトには別プロンプト (getServerSideProps / API Routes 観点) を用意した方が拾いやすいです。
エラーログがビルド時ではなくランタイム時にしか出ません
App Router のバグは「ビルド通る・ランタイムで爆発」のパターンが多いです。本プロンプトでは『期待挙動』と『実際の挙動』の比較が一次情報源になるので、エラーログが取れない場合でも「画面が真っ白」「フォーム送信後リダイレクトしない」など挙動の差を具体的に書けば原因観点の絞り込みは機能します。
AI が「'use client' を付けて回避」しか提案してきません
プロンプトの制約セクションに『対症療法は禁止』と明記しているのに返ってくる場合は、「'use client' で回避する以外の構造的解決を 3 案出してください」と再指示すると、Server Component 内へのデータ取得移動・Client 境界の最小化・Server Action 化などの代替案が出ます。
近傍ファイルの怪しい箇所まで指摘させると精度が落ちませんか?
コード全体を貼らない場合、AI は「ありがちな罠の一般論」を返してくるだけになる傾向があります。app/ 配下のディレクトリツリーと、該当ページに関連する layout.tsx / loading.tsx / route.ts のファイル名一覧を併せて貼ると、近傍指摘の精度が大幅に上がります。

このプロンプトを実戦で使った所感や改善案があればぜひフィードバックを。姉妹サイト ai-pick.tech では AI x SNS集客の運用ノウハウを公開しています。