next-cache-components-optimizer
2つのループ、共有のレバーとプリミティブ、異なる診断:
- ページレンダリングループ (ppr-loop.md) — 単一ページの静的シェルを拡大します。シェルのみのレンダリングでSuspenseのフォールバック領域をランク付けします。
- ナビゲーションループ (instant-nav-loop.md) — ユーザーがリンクAからBへクリックしたとき、Bのデータが解決されるのを待たずにBの静的レイアウト(クローム、構造、コンテンツ形状のフォールバック)を即座に表示します。
pushstate後にBのサスペンドされた境界をキャプチャし、各々をsuspended_by[].nameで分類し、SSR専用のクライアントフックを削除します。
一つを選択し、エンドツーエンドで実行します。
必要条件
- このセッションで
next-dev-loopが開始されていること — これによりヘッドレスブラウザが開き、agent-browserCLIが公開され、mcp get_logsを提供する開発MCPサーバーが配線されます。 next.config.tsでcacheComponents: trueが設定されていること。そうでない場合は拒否します。
事前チェック(共有)
cacheComponents: trueを確認します。- (
next-dev-loopからの)ヘッドレスブラウザで、各ループが必要とするページにユーザーが既にいること — ログイン済みで、任意の状態がセットアップされていること。このスキルは認証、SSO、MFAを駆動できません。手動セットアップを開始点とします。(各サブループは、どのページを期待するかを指定します。) agent-browser get urlで現在のルートを固定します。
各ループは、必要に応じてインスタントCookieを設定します(下記の共有 instant cookie セクションを参照)。
インスタントCookie(共有)
両方のループは next-instant-navigation-testing Cookieを使用して、フレームワークの動的データ書き込みを凍結します。設定されると、ページ上の可視コンテンツは静的シェル + Suspenseフォールバックになります — これをキャプチャして最適化を評価します。
保留ロックタプル [0, "<ユニークID>"] で設定します。IDは任意のユニークな文字列です。慣例として、競合するスコープが衝突しないように p で始まるランダムスタンプを使用します:
agent-browser cookies set next-instant-navigation-testing '[0,"p<random>"]' \
--url <origin>
各ループの事前チェックは、フロー内でいつ設定するかを指定します。最後にクリアします(下記の teardown を参照)。
ループの決定
- ページレンダリング — 1つのルートの初期読み込みに関する問題の場合。ppr-loop.md を読んでください。
- ナビゲーション — 2つのルート間のナビゲーションに関する問題の場合。instant-nav-loop.md を読んでください。
曖昧な場合 → ユーザーに尋ねてください。
共有リファクタリングレバー
- プッシュダウン — I/OをSuspenseでラップされた子コンポーネントに抽出し、親を静的に保ち、静的な兄弟をシェルに引き上げます。
- 再帰的に行い、盲目的にラップしないでください。 Suspense境界がすでに静的コンテンツとI/Oの両方を含むコンポーネントをラップしている場合、内部を読み取り、I/O依存のJSXを新しいリーフに抽出し、静的な兄弟を引き上げます。
- キャッシュ —
'use cache'+cacheLife(<プロファイル>)。常にユーザーに鮮度を尋ね、プリセット(seconds/minutes/hours/days/weeks/max/default)にマッピングします。
プッシュダウンとキャッシュは組み合わせ可能です: プッシュダウンは静的な構造を引き上げ、キャッシュは残りのデータギャップを排除します。
計画モードでの提案(共有)
各リファクタリングは、適用前に計画モードを経由します。これをシグナルとして扱ってください: 適用作業は、テンプレート化された編集ではなく、重要なエージェントエンジニアリングです。このスキルはフレームワークを提供します — どのレバーを使うか、どの候補を修正するか、期待される可視デルタは何か — しかし実際の作業(どのファイルを編集するか、I/Oをクリーンに抽出する方法、新しいSuspense境界をどこに配置するか、どの cacheLife プロファイルをユーザーに尋ねるか)は、あなたが熟考して判断する必要があります。計画モードは、コードに触れる前に首尾一貫した提案を強制し、ユーザーにそれらの決定のいずれかを変更する機会を与えます。
シェルなしの早期終了(共有)
レバーは、拡大またはキャッシュするシェルが存在することを前提としています。ルートが完全にブロッキングされている場合 — mcp get_logs で blocking-route または NEXT_STATIC_GEN_BAILOUT のHTTP 500、または可視的にレンダリングされたページでSuspense境界がゼロの場合 — シェルはありません。構造的なブロッカーを表面化して停止します。ユーザーは、問題のある動的アクセスを <Suspense> でラップしてからでないと、どちらのループも役に立ちません。
検証には可視デルタが必要(共有)
各ループは、変更を適用する前にシェルのベースラインスクリーンショットをキャプチャし、その後再スクリーンショットを撮ります。最終サマリーで両方のパスを報告し、ユーザーが何が変更されたかを確認できるようにします。2つのキャプチャは明らかに異なっていなければなりません — フォールバック領域が縮小された、コンテンツが静的サーフェスに昇格した、ターゲットのフォールバックが消失した、またはコンテンツ形状になった。同一に見えるキャプチャは、リファクタリングが機能しなかったことを意味します。元に戻してください。「クリーンにコンパイルされる」は基準ではありません。
各スクリーンショットの前に開発オーバーレイを非表示にします。 Next.jsの開発オーバーレイ(ドキュメントルートの <nextjs-portal>)は、インスタントナビゲーションガイダンス、ビルドエラー、および他の開発用クロームをレンダリングし、Before/Afterの比較を汚染します。非表示にし、スクリーンショットを撮り、復元します:
agent-browser eval "document.querySelector('nextjs-portal').style.display='none'"
agent-browser screenshot <path>
agent-browser eval "document.querySelector('nextjs-portal').style.display=''"
アンチパターン(共有)
詳細なSuspense境界をトップレベルのローディングスケルトンに置き換えないでください。 セグメント全体に対する loading.tsx、またはルートレベルの <Suspense fallback={<Skeleton />}>(さらに悪いことに、UIを空白にする fallback={null})は、このスキルの最適化を無効にします — 各詳細な境界の上に実際の静的クロームを抽出し、領域ごとにコンテンツ形状のフォールバックを使用することです。粗い「ページ読み込み中」の代用品は、作業を完全にバイパスします。
注意点(共有)
- 開発環境は本番環境のようにプリフェッチせず、ルートは初回ヒット時にコンパイルされます。そのため、ナビゲーションまたはリロード後、DOMは最終的な本番エクスペリエンスよりも著しく長く更新され続けます。Reactツリーをキャプチャしたりスクリーンショットを撮ったりする前に、DOMが安定するのを辛抱強く待ってください — 例えば、
document.documentElement.innerHTML.lengthを2回連続して読み取り、変更がなくなるまでポーリングします。固定の短い遅延では、レンダリング途中のサンプリングリスクがあります。 - 開発ネットワークトラフィックを調べることでナビゲーションプリフェッチを検証しようとしないでください — 開発環境はプリフェッチ要求をまったく発行しません。そのため、ネットワークタブ、手動の
router.prefetch()呼び出し、<Link prefetch={true}>は、コードが正しいかどうかに関係なくすべて壊れているように見えます。instant-nav-loop.md のverifyにあるCookieロックされたSPAナビゲーションレシピは、これに対する正規のレシピです — プリフェッチが実際に発火することを要求せずに、本番環境がプリフェッチされたRSCにプリレンダリングするものをシミュレートします。それを使用してください。ネットワークタブの代替を発明しないでください。 - 診断パイプラインは不安定になる可能性があります — DevToolsのアタッチメントタイミング、DOMセトルの競合、開発コンパイルの影響により、実行ごとに一貫性のないキャプチャが生成されることがあります。結果がおかしいと感じた場合(予期しない候補が現れた、または期待した候補が現れない場合)、診断を2〜3回再実行してクロスチェックしてください。一貫して現れる境界は本物で、1回限りの出現はノイズです。
リファレンス(共有プリミティブ)
agent-browser react suspense add --only-dynamic to filter
--json server-side to actually-
suspended boundaries. Each
entry has jsx_source +
suspended_by[] with raw blocker
names (usePathname, cookies,
fetch, cache, ...); classify by
name for per-loop rules
POST /__nextjs_original-stack-frames body { frames: StackFrame[],
isServer, isEdgeServer,
isAppDirectory }; returns one
result per frame with
file:line:column
mcp get_logs dev MCP tool from
next-dev-loop; surfaces
blocking-route /
NEXT_STATIC_GEN_BAILOUT 500s
cacheLife('<profile>') default | seconds | minutes
| hours | days | weeks | max
ループごとのプリミティブは instant-nav-loop.md にあります。
後片付け(共有)
名前でCookieを削除します — 期限切れスタンプで上書きします:
agent-browser cookies set next-instant-navigation-testing x \
--url <origin> --expires 1
agent-browser cookies clear(引数なし)は決して使用しないでください — 認証を消去します。
next-dev-loop の兄弟 — 最初にそれを開始してください。