next-partial-prefetching-adoption

next-partial-prefetching-adoption

Partial Prefetching を有効にして、アプリ内のすべてのリンクが共有 App Shell を再利用するまでアプリを操作します。このスキルは作業の順序を定めます。各インサイトに対応する手順は、開発オーバーレイの修正カードとドキュメントページに記載されています。このスキルで扱う概念の正式な参照先は、Adopting Partial Prefetching guide です。

開発時のインサイトと保持テストは、別々の経路です。インサイトは next dev の開発オーバーレイにある Insights タブにのみ表示されます。テストに基づく保持確認は、instant() を使って本番環境に近いビルドに対して実行するため、開発サーバーは必要ありません。フラグを有効にした後に行う URL データのインサイト確認は、引き続き next dev を使用します。

保持確認のゲート

テストに基づく保持確認を行う場合、最初の実装マイルストーンは、フラグを無効にした状態で instant() のテストスイートに合格することです。本番テスト環境を構築し、選択したアサーションを記述して、partialPrefetching を無効にした状態で実行し、コマンドと終了ステータスを記録します。テスト環境に必要な設定（experimental.exposeTestingApiInProductionBuild など）は許可されますが、このベースラインに合格するまでは、partialPrefetching を有効にしたり、遷移先、キャッシュ境界、Link の props を編集したりしないでください。不足しているテスト依存関係のインストールは、ベースラインに到達するための作業であり、先に導入する理由にはなりません。手動の経路を使うのは、リポジトリでは解決できない具体的な阻害要因が rig-template.md に記載されている場合に限り、その阻害要因と延期するテストカバレッジを記録してください。

ユーザーには、インサイトのスラッグや手順ラベルではなく、PR、機能、適用後のアプリの動作など、実際に目にする内容を説明してください。開始前に、Partial Prefetching によって何が変わるのかを簡潔に伝えます。ルートへのリンクは、共有 App Shell を 1 つプリフェッチします。また、prefetch={true} を指定すると、キャッシュされた URL 固有のコンテンツも解決できます。監査では、従来の完全なプリフェッチで使われていた UI のうち、どれを保持するかを判断します。

必要条件

• Cache Components が導入済み（cacheComponents: true）で、ビルドに合格していること。 partialPrefetching とルートレベルの prefetch エクスポートは、どちらも Cache Components が必要です。無効になっている場合は、まず next-cache-components-adoption を使用し、ビルドを妨げるプリレンダリングエラーを解決してから戻ってきてください。これらのエラーは next build を失敗させる場合があります。このスキルで扱う Partial Prefetching のインサイトのみ、開発時の非ブロッキングシグナルです。

• Next.js 16.3 以降であること。 partialPrefetching、prefetch のルートセグメント設定、プリフェッチのインサイトは、いずれもこのバージョンで導入されます。

• 操作できるブラウザーがあること。 テストに基づく保持確認では、既存または最小限の本番モードの Playwright テストスイートを使用します。手動での保持確認と最終デモでは、実行中の本番アプリを使用します。開発時のインサイト経路と、フラグ有効化後の URL データ確認では next-dev-loop を使用します。すでに利用可能な場合を除き、いずれかの開発パスを実行する前にインストールしてください（npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-dev-loop）。アプリが webpack に固定されている場合は、ブラウザーを直接操作してください（agent-browser、Playwright）。失われるのはフレームワークによるクロスチェックであり、インサイトではありません。インサイトは引き続きオーバーレイと開発ログに表示されます。

• 実行可能なアプリがあること。 自動プリフェッチは本番環境でのみ実行されるため、保持確認と最終デモには本番環境に近いビルドが必要です。開発サーバーが必要なのは、インサイト経路を使う場合、またはフラグ有効化後の URL データ確認を行う場合のみです。テストに基づく保持確認を確かめるだけのために、開発サーバーを起動しないでください。アプリがインポート時にデータベースや必須の環境変数を読み込む場合は、ステップ 1 の前に、選択した経路で使う環境から起動できることを確認してください。

メモ

• オフラインのドキュメント。 ガイドへのリンクは node_modules/next/dist/docs/ にオフライン版があります（Next.js 16.2 以降に同梱）。ディレクトリ構成には順序を示す番号が付いています（例：node_modules/next/dist/docs/01-app/02-guides/adopting-partial-prefetching.md）。番号付きのプレフィックスを予測できない場合は、find node_modules/next/dist/docs -name '<slug>.md' で見つけられます。/docs/messages/* のエラーページは同梱されていません。

• ドキュメントが同梱されていない古いバージョン。 作業を始める前に、ユーザーに npx @next/codemod@latest agents-md を提案してください。このコマンドはバージョンに対応したコピーを .next-docs/ にダウンロードし、AGENTS.md にインデックスを書き込みます。リポジトリ内のファイルを変更するため、最初に確認し、ユーザーが希望した場合にのみ実行してください。

背景

Partial Prefetching の導入により、すべてのルートで重要なプリフェッチ済み UI が維持されるようになります。これは、共有 App Shell と、リンクが明示的に要求する追加のリンクごとのデータに分けられます。ガイドは、プリフェッチに何が含まれるか、各ケースをどのように判断するかを示す正式なリファレンスです。このスキルでは、実行中のアプリに対してその作業を順序立てて進めます。

大半の確認作業で重要になる点は、デフォルトのリンクがプリフェッチするのは共有 App Shell だけだということです。params または searchParams をキーとするルートで、さらにプリフェッチできるのは、Partial Prefetching を導入したうえで、特定のリンクが <Link prefetch={true}> を使用している場合だけです。この場合、Next.js はクリックされる前に URL データと、その背後にあるキャッシュ済みコンテンツを解決します（ガイドのURL データのセクションを参照してください）。

作業面

• 本番モードのinstant()テストスイート — テストに裏付けられた保持を確認するための主要な記録です。 アプリの本番ビルド、テストコンテキスト、Playwright のセットアップを再利用します。まず既存のinstant-nav.rig.mdを読みます。プロジェクトに rig がない場合は、**rig-template.md**から作成します。同じテストで、導入前のレガシーな基準を定義し、遷移先が部分プリフェッチを有効にするたびに作業キューとして使います。開発環境は失敗の調査に役立ちますが、プリフェッチされた UI が保持されたかどうかを判断するのは、このテストスイートだけです。
• 開発サーバーのターミナル — インサイトの経路を確認するための主要な記録です。 検証済みの各ルートのインサイトは、https://nextjs.org/docs/messages/<slug>へのリンクを含むError: Route "...": Next.js encountered ...の行としてログに記録されます。確認中は開発ログを追跡してください。どこで何が発生したかを検索できる記録であり、Turbopack と webpack のどちらでも同じように機能します。
• 開発オーバーレイのインサイトタブ。 インサイトは、アンバー色のブロックしないタブに表示されます。インサイトが発生した場合にのみ表示されるため、何も表示されないルートではタブも表示されません。これは機能が欠けているのではなく、問題のない状態です。何も起きていないルートでタブを探さないでください。信頼できるシグナルである上記の開発ログで、問題がないことを確認します。前提条件は、ブロックするプリレンダリングエラーがないことです。ブロックするエラーがあると、そのルートではインサイトが置き換えられます（「必要条件」を参照）。無関係な Issue（ハイドレーションエラーやコンソールエラーなど）は確認を妨げないため、そこで作業を止めないでください。タブが表示されている場合、オーバーレイのピルには件数が表示され、各インサイトにはドキュメントページへのリンクを含む修正カードがあります。オーバーレイはシャドウルート（nextjs-portal）内にレンダリングされるため、アクセシビリティツリーのスナップショットには表示されません。プログラムから読み取ったりクリックしたりするには、shadowRootを評価してください。
• next-dev-loopを使ってナビゲーションを実行し、オーバーレイを読み取ります。 Cache Components スキルと同じ理由から、手書きのブラウザー自動化よりこちらを優先してください（webpack アプリについては「必要条件」を参照）。/_next/mcpツールを調べる際、プリフェッチのインサイトはget_errorsとオーバーレイに表示され、名前が似たget_request_insightsには表示されません。後者はスパンとパフォーマンスを記録する機能（experimental.requestInsightsで有効化）であり、プリフェッチについては何も報告しません。

すべてのインサイトにはドキュメントページがあります。開いてください。遭遇したインサイトごとに、リンク先のページを取得してください。インラインメッセージは要約であり、ページには具体的な手順が記載されています。

ステップ 1：<Link prefetch={true}> のナビゲーションを監査する（有効化前）

この監査とステップ 2 のレガシーなベースライン測定が終わるまで、グローバルフラグはオフのままにしてください。先に有効化すると、移行で測定する必要があるレガシーな動作が失われます。未リリースの作業ですでにフラグがオンになっている場合は、フラグを有効にする前のコミットを使って監査とベースライン測定を行います。ユーザーに確認できる場合は、PR の進め方としてどちらにするか尋ねてください。

• 1 つのブランチ — 監査全体を 1 回の変更として行い、最後にフラグを有効化して codemod を実行します（ステップ 4）。
• ルートごと — 採用するリンク先ごとに、独立した PR としてリリースします。まだ対応していないリンク先では引き続きインサイトが発生し、リアルタイムの作業リストとして機能します。最後のリンク先を移行した後にステップ 4 を実施します。

どちらの場合も作業内容と順序は同じで、異なるのはコミットの区切りだけです。ユーザーに確認できない場合は、アプリの規模に応じて決めてください。リンクが少数なら 1 つのブランチ、監査の規模が大きくレビュー担当者が小さな差分を必要とする場合はルートごとに進めます。選択した進め方を報告に記載してください。

明示的なプリフェッチと手動プリフェッチの箇所は、app/ だけでなく、ソースツリー全体から列挙してください。これらは src/components や共有 UI パッケージにあることもよくあります。next/link のインポートと再エクスポートから調べ始め、カスタムラッパーを利用箇所までたどってください。rg -n '\bprefetch\b|router\.prefetch' -g '*.tsx' -g '*.jsx' . は候補の一覧として使い、完全な監査として扱わないでください。実際に有効となる本番環境での値を判定するには、条件付きの props と転送される LinkProps を調べてください。実際に有効となる本番環境での Link の値が prefetch={true} となるナビゲーションは、監査対象にすべて含めてください。これには、明示的な true、値を指定しない prefetch プロパティ、そして評価結果が true となる式が含まれます。デフォルト値、prefetch="auto"、prefetch={false} はレガシーなフルプリフェッチを要求しないため、保持対象のテストスイートから除外します。既存の router.prefetch() の呼び出しは、Link のインサイトがないため、別途監査してください。新たに手動プリフェッチを行う場合は、プリフェッチガイドに従ってください。prefetch={true} に解決される Link がない場合は、その旨を伝え、ステップ 4 に進んでください。

保持する内容と検証方法を選ぶ

テストの作成や遷移先の編集に着手する前に、ガイドの移行ガイダンスに従い、保持する価値のあるUIを提案してください。結果は簡潔な表1つにまとめます。

ナビゲーション	提案する結果

同等のナビゲーションをまとめてください。すぐに表示できる内容と、ストリーミングされる内容を要約してください。提案が曖昧な場合は、実行中のアプリでナビゲーションを確認し、ユーザーに確認を求めてください。ユーザーが対応できない場合は、ガイドに従って前提を記録してください。

対象のUIが確定したら、既存のテスト環境を確認してください。instant() ヘルパーは next/experimental/testmode/playwright ではなく、別パッケージの @next/playwright に含まれています。

• 適用可能な本番モードのテストスイートがある場合： デフォルトでは、テストに基づいて保持を進めてください。プロジェクトの @next/playwright テスト、本番用スクリプト、認証、および既存の instant-nav.rig.md を再利用してください。ガイドのプリフェッチ済みUIのテストワークフローに従い、採用前にフラグをオフにした状態でテストスイート全体を成功させてください。変更していないアサーションを移行の指針とし、回帰テストとして維持してください。
• 適用可能な本番モードのテストスイートがない場合： プロジェクトのパッケージマネージャーとテスト規約を使って、rig-template.md に本番モードのテスト環境を設定してください。これはテストに基づく採用プロセスの一部であり、ユーザーがその場にいる必要はありません。
• テスト環境を安定して実行できない場合： rig-template.md に沿って、セットアップと稼働確認を進めてください。認証情報を利用できない、または本番環境にアクセスできないなど、リポジトリでは解決できない具体的な阻害要因がある場合に限り、手動での保持確認に切り替えてください。阻害要因と先送りしたテスト範囲を記録し、テストに基づく検証を実施したと主張しないでください。

既存のテストスイートを再利用する場合も、新しいテスト環境を作成する場合も、ユーザーへの入力依頼は不要です。質問が必要なのは、環境に関する疑問をリポジトリから解決できない場合、または対象のUI自体がプロダクト上の決定事項である場合に限ります。ユーザーが対応できない場合は、ガイドの安全なプロダクト上のデフォルトに従い、具体的なテスト環境の阻害要因がある場合に限って手動で検証してください。新しいプリフェッチ済みUIはステップ7の作業として扱い、意図的に削除するものは、採用後に別途検証してください。

このワークフローの対象は、クリックされた <Link> です。router.prefetch('/dashboard') のような直接呼び出しは手動プリフェッチであり、Linkによるプリフェッチではありません。ソース監査の対象に含め、ステップ6で別途検証してください。

step 2: 従来のベースラインを取得する

このステップでは、partialPrefetching を有効にしたり、ルートの動作、Linkのプロパティ、キャッシュ境界を編集したりしないでください。instant() の実行に必要なテスト専用の設定は許可されます。

テストに基づいて保持する場合は、保持ゲートを完了してください。instant() のテストスイート全体を作成し、Partial Prefetchingを無効にした本番相当のテスト環境で実行してください。テストファイル、ビルド、完了したナビゲーション、またはユーザーに表示したコマンドは、ベースラインにはなりません。テストスイートが実際に成功するまで、ステップ3に進まないでください。

手動で保持を確認する場合は、遷移先を編集する前に、変更前と対象の一覧を完成させてください。この方法に切り替えるのは、rig-template.md を通じて特定した具体的なテスト環境の阻害要因がある場合に限り、阻害要因と先送りしたテストを記録してください。

step 3: 移行先を採用し、対象を復元する

一時的なルート設定を使って、監査済みの移行先をすべて採用します。ルートのエクスポートだけで十分です。グローバルフラグをオフのままにしても、変更していないテストでその移行先の Partial Prefetching を実行できます。

// See: https://nextjs.org/docs/app/guides/adopting-partial-prefetching
export const prefetch = 'partial'

ほかにもプリフェッチする価値のある URL 固有の UI があり、従来の仕様には含まれていなかった場合は、そのリンクに prefetch={true} を残し、step 7 の対象としてルートに印を付けます。

// TODO(per-link-prefetch): assess with the user whether URL data should resolve before click.
// See: https://nextjs.org/docs/app/guides/optimizing-prefetching
export const prefetch = 'partial'

step 7 で再検索できるよう、必ずこの正確なプレフィックスを使ってください。ここでは新しい対象 UI を選ばず、従来の動作から選んだ対象だけを復元します。

テストに基づいて動作を維持する場合は、移行先を変更するたびに、影響を受ける変更していないテストを再実行し、失敗を作業キューとして扱います。グローバルフラグを有効にする前に、完全なテストスイートを実行し、成功した終了ステータスを記録してください。手動で動作を維持する場合は、採用した本番環境のナビゲーションを選択した対象と比較し、まだ復元されていない点を記録します。キャッシュと Link プロパティの変更には、ガイドにある該当する動作維持パターンを適用し、鮮度やキャッシュに関する判断が不明確な場合はユーザーに確認してください。上記で印を付けた新しい URL データ候補は、step 7 まで保留します。

対象を復元したことでキャッシュや無効化の動作が変わる場合は、プロジェクトで既に採用されている検証方法と再検証ガイドに従ってください。影響を受けるライフサイクルに適用できるテストスイートを再利用または拡張します。プロジェクトでこの種の動作をテストしていない場合は、移行中に新しいテストインフラストラクチャを導入せず、本番環境で手動検証し、予想結果と実際の結果を記録してください。instant() テストの成功が証明するのは準備ができていることだけで、キャッシュが正しいことではありません。意図された動作が不明確な場合に限り、ユーザーに確認してください。

use cache を追加する場合は、ビルドだけでなく next start の実行下でも検証してください。 キャッシュ対象の呼び出しツリー内のどこかで cookies()／headers()／セッションを読み取ると、next build が問題なく通っても、リクエスト時に例外が発生します。use cacheを参照してください。

step 4: フラグを有効にする

監査済みのすべての移行先で prefetch = 'partial' になったら、次の 2 つの作業を完了します。

1. フラグをグローバルに有効にします。 next.config.ts で（cacheComponents: true と並べて）partialPrefetching: true を設定します。すべてのルートが移行済みなので、すべてのリンクを利用できます。

2. 冗長な prefetch = 'partial' エクスポートを削除します。 テキストの検索・置換ではなく、ファーストパーティの remove-partial-prefetch codemod を実行してください。この codemod は、TODO(per-link-prefetch) マーカーの下にあるものも含め、すべての export const prefetch = 'partial' と、生成された Partial Prefetching ガイドのコメントを削除します。TODO マーカーと Optimizing prefetching ガイドへのリンクは step 7 のために残します。prefetch = 'force-disabled' など、ほかの値はそのまま残します。

   npx @next/codemod@canary remove-partial-prefetch ./app
   

   src/ を使うプロジェクトでは ./src/app を指定し、報告されたファイル数を確認してください。codemod は作業ツリーに未コミットの変更があると実行を拒否します。先に無関係な作業をコミットまたは stash するか、--force を渡して WIP と並行して編集を適用してください。codemod を利用できない場合（古い @next/codemod、サンドボックス環境、オフラインでの実行）は、app/**/{page,layout}.{js,jsx,ts,tsx} のすべてのファイルから export const prefetch = 'partial' と、生成された Partial Prefetching ガイドのコメントを手作業で削除し、同じ処理を行います。ほかの prefetch の値はそのまま残し、TODO(per-link-prefetch) マーカーと Optimizing prefetching ガイドへのリンクもそのまま残してください。codemod を実行できる場合は、手作業で編集しないでください。

フラグと codemod を同時に反映したら、テストに基づく方法を採用している場合は、固定した動作維持テストスイートを再実行します。それ以外の場合は、最終的なグローバル設定のもとで、記録した本番環境の比較をもう一度行います。

ステップ 5：URL データのインサイトを確認する（有効化後）

これは開発時のみ行う第 2 段階です。シェルのチェックはフラグがオンのときだけ実行され、ナビゲーション時に発生し、ビルドをブロックしないため、ステップ 4 の後ならいつでも実施できます。具体的な情報源（直近の next build のルートテーブル、または app/ ツリー）をもとにルートのキューを作成し、ToDo リストとして管理します。

機能ごとに確認します。機能とは、app/settings/** や app/posts/[slug]/** のような単一のプロダクト領域であり、トップレベルの領域全体ではありません。次の機能に移る前に、1 つの機能を最初から最後まで完了させます。そのルートを next dev で読み込み、インサイトに対処します。インサイトはビルドをブロックせず、各ルートは独立しているため、確認が途中でもアプリは動作します。また、各機能の変更はそれぞれ独立しているため、ユーザーは個別にレビューしたり、リリースしたりできます。

環境上、確認全体を完了できない場合（初回コンパイルが遅い、負荷で開発サーバーが停止する、ブラウザーがまったく使えないなど）は、引き継ぐ前にブラウザーなしでできる作業を可能な限り進めます。静的に対応できるルートはすべて対応します。型チェックを通しながら、URL data に記載された修正を新しい <Suspense> 境界まで適用します。キュー全体を一度に進めてください。大規模なリファクタリングは先送りする理由になりません。また、次のルートや段階に進んでよいか尋ねることはチェックポイントではありません。作業を続けてください。本当に判断が必要な場合にのみ停止し、最後の引き継ぎレポートにまとめてください。静的に対応したルート、ライブのシェルチェックがまだ必要なルート、そしてキューを報告します。

Insights タブと開発ログで、Next.js encountered … data の行を確認します。このステップで追加されるシグナルは URL data です。サスペンドされたサブツリー内で params または searchParams を高い階層から読み取ると、共有シェルが 1 つの URL に結び付けられます。このインサイトが表示される範囲は限られており、最も確実に確認できるのは generateStaticParams を使うルートです。この場合、params はすでに <Suspense> の内側にありますが、URL 固有のリーフ境界より前に await されています。代わりに blocking-prerender-* エラーが発生した場合も、同じ構造上の修正を適用します。

フラグをオンにしてルートを読み込むと、App Shell がプリレンダリングされるため、Cache Components のビルドよりもルートの広い範囲が検証されます。そのため、Cache Components で問題なくビルドされたルート（すべてのルートが ◐ で、エラーがない）でも、シェルが初めてプリレンダリングされる際に blocking-prerender-* エラーが表面化することがあります。原因は runtime data（cookies()／headers()）、uncached data（キャッシュされない fetch／DB 呼び出し）、または Date.now()／new Date() のような同期 IO です。これは Cache Components の導入が不完全だったという意味ではありません。ビルドでは実行されなかったパスまで、新たな検証が行われたということです。これらは Partial Prefetching のインサイトではありません。それぞれに、ほかの blocking-prerender エラーと同じ方法で対処してください。

こうした修正でユーザーに確認することはほとんどありません。各インサイトには問題のある読み取り箇所が示され、ドキュメントページに修正方法も記載されているため、修正して確認を続けます。まれにある例外は、最後にまとめて質問してください。すべてが URL に依存する領域であるページ（全体をラップするとシェルが空になる）や、オプトアウトしたままにするのが妥当と思われるルートなどです。コメントでリファクタリングの説明を書かないでください。<Suspense> 境界がそれ自体を示します。

ステップ 6：検証

ユーザーに確認する前のチェックリスト：

• Cache Components の導入が問題なく完了した場合、スイープで何も検出されないのは想定どおりです。 ログに何も出ないのは成功であり、シグナルが欠けているわけではありません。検証パスを意図的に調べる場合は、params を <Suspense> 内で読み取るものの、URL 固有のリーフ境界より前に読み取る generateStaticParams ルートを使用してください。それ以外の構成では、代わりに blocking-prerender-* が現れる場合があります。
• App Shell は実際に機能しています。変更した各ルートについて、ナビゲーション後の最初の描画で、空のシェルや固まったフォールバックではなく、意図した共有コンテンツが表示されることを確認してください。ページ本文全体を囲む <Suspense> は、空のシェルでも検証に通ってしまうため、目的に反します。
• インサイトで検証できるのはシェルの 構造 であり、実際にプリフェッチが行われたかどうかではありません。本番実行時（自動プリフェッチが動作するのは本番環境のみ）に、変更したリンクをクリックして共有シェルが即座に表示されることを確認してください。
• テストで維持を確認する場合、監査対象の <Link prefetch={true}> ごとに、固定した instant() テストがすべて本番実行で成功することを確認してください。手動で維持を確認する場合は、変更前後の一覧と、後で対応するテストの記録を残してください。
• 更新可能なデータを持つ新規または拡張したキャッシュにデータを投入した後、該当する既存のテストスイート、またはカバレッジがないプロジェクトでは記録した手動チェックを使って、次の読み取りで変更が反映されることを確認してください。
• アプリが命令的にプリフェッチする場合、インサイトのスイープでは対象にならないため、スイープで何も検出されなくても、フラグを有効にした後もプリフェッチが維持されている証拠にはなりません。 next start で呼び出しを検証してください。_rsc プリフェッチレスポンスまたはリソースのタイミングを変更前後で比較し、意図的に維持したフルプリフェッチに、従来の呼び出しでウォームアップしていたデータが引き続き含まれていることを確認してください。App Shell しか返らなくなった場合は、その呼び出し箇所を、最も近い <Link prefetch={true}> の遷移先と同じ判断に基づいて移行してください。つまり、データをキャッシュするか、ドキュメントでサポートされている <Link prefetch={true}> にリンク単位のプリフェッチ動作を移してください。
• フラグのせいでルートが壊れたと判断する前に、partialPrefetching をオフにする（またはフラグを導入する前のブランチで）再現を試してください。このフラグによって、リクエスト時の脆弱な認証ゲート、リライト、デプロイの不整合など、既存の問題がより早く、目立つ形で表面化することはありますが、問題の原因になることはほとんどありません。フラグをオフにしても壊れるなら、それは Partial Prefetching の問題ではありません。ここではなく、その環境で修正してください。
• next build が引き続き成功することを確認してください。

その後、ユーザーに確認します。ユーザーの言語で話し、インサイトのスラッグやステップ名は使わないでください。

• 実施したこと：監査したリンク、導入した遷移先、それぞれのリンクが現在プリフェッチする内容。
• 変更内容：削除したプロパティ、追加した use cache 境界、後で対応するために TODO(per-link-prefetch) マーカーを付けたルート。
• 本番実行でのデモ。自動プリフェッチは本番環境でのみ動作するため、next dev では結果を確認できません。next build と next start を実行し、その URL をユーザーに共有してください。この実行には、アプリの実環境（データベース、認証情報、シークレット）が必要です。また、不完全または古いインストール、残った生成済みアーティファクトがあると、導入とは無関係な理由でビルドに失敗することがあります。手短な確認ではなく、認証情報をそろえた完全な本番実行が必要であることを、あらかじめ伝えてください。
• 言葉ではなく、実際に見せてください。本番サーバーに対して、ブラウザーを表示した状態でリンクをひとつ操作し、共有 App Shell が即座に描画され、URL 固有の領域がストリーミング表示される様子を見せてください。実際にブラウザーを使えない場合に限り、変更前後のスクリーンショットを添付してください。
• クリックして確認できるようにしてください。変更した各ルートについて、クリックするリンクと、クリック後に期待される表示内容（即座に描画されるもの、ストリーミング表示されるもの）を表にまとめ、ユーザー自身で各結果を確認できるようにしてください。
• 質問：「URL 固有のコンテンツもプリフェッチすべきルートを確認する前に、これをコミット（または PR を作成）しますか？」回答を待ってください。導入とリンク単位のプリフェッチは、それぞれ別の変更として扱うのが適切です。

ステップ 7：リンク単位のプリフェッチ（任意）

監査では、候補を判定せず、すでに維持されている従来の契約を超えるものとしてマークしました。TODO(per-link-prefetch) を grep し、1 回の会話でユーザーと一緒にリストを確認してください。ルートごとに、クリック前に URL に依存する追加コンテンツをプリフェッチするか、遷移後にストリーミングする形で問題ないかを確認します。リンク単位のプリフェッチでは、プリフェッチ可能なリンクごとにサーバー呼び出しが発生します。ガイドのトレードオフのセクションをチェックリストとして使ってください。これらの判断を独断で行わないでください。

回答が「いいえ」の場合は、マーカーを削除し、ルートを App Shell のデフォルト設定のままにします。「はい」の場合は、プリフェッチの最適化ガイドに従い、本番環境で実行してオプトインしたリンクを確認し、選択した結果が検証できたらマーカーを削除します。

完了したステップに TODO(per-link-prefetch) マーカーが残らないようにしてください。リンク単位の最適化は、導入とは別のコミットまたは PR にします。

最後に、実質的に有効な prefetch={false} のリンクを、簡潔な ナビゲーション | 不要になった可能性がある理由 の表に示します。false はすべてのプリフェッチを無効にする一方で、Partial Prefetching のデフォルトである auto の動作では共有 App Shell のみがプリフェッチされるため、従来の全ルートプリフェッチを避けるために追加されたオプトアウトは不要になっている可能性があることを説明してください。これらのリンクは、別途見直すようユーザーに案内してください。

さらに読む

• 即時ナビゲーション — より広範な検証モデルとローディング状態のツールについて説明しています。
• e2e テストでリグレッションを防止する — @next/playwright の instant() ヘルパーを使ってフラグ無効時のベースラインスイートを構築し、CI のリグレッションガードとして維持します。
• next-cache-components-optimizer — 各ルートの静的シェルを拡張し、App Shell により多くの内容を持たせます。