next-dev-loop

next-dev-loop

next dev 実行中の編集と検証のサイクルです。変更を加えたら、型やビルドが問題ないだけでなく、実行時にも実際に動作することを確認します。

実行中の同じアプリを、次の 2 つの視点から検証します。

• /_next/mcp — Next.js が自身について公開する HTTP エンドポイントです。 Next.js が認識したフレームワーク固有の情報、つまりルート、セグメント、RSC、サーバーアクション、サーバーログ、エラーを把握しています。現在利用できる機能を確認するには、tools/list を呼び出します。
• agent-browser — 実際の Chrome を操作する CLI です。 DOM、コンソール、ネットワーク、React ファイバー、バイタルなど、フレームワークに依存しないブラウザー情報を把握しています。操作する前に、バージョンに合った使用ガイドを確認するため、agent-browser skills get core を一度実行してください。記憶に頼ってサブコマンドを推測しないでください。

この 2 つの視点を相互に照合します。

必要条件

• Turbopack を使用する Next.js 16.3 以降 — /_next/mcp と、get_compilation_issues による事前のコンパイルチェックに必要です。
• agent-browser 0.31.1 以降 — React のイントロスペクション、ワークツリーごとの session id、冪等な --restore、起動フラグの調整に必要です。

これらは最低要件であり、推奨要件ではありません。不足しているものがあれば、アップグレード方法をユーザーに伝えて停止してください。ソースの grep や、より弱いプローブに代替しないでください。このスキルは、上記バージョンで両方の視点が利用可能であることを前提としています。

• Next.js のアップグレード：pnpm next upgrade（または npx next upgrade）。 ドキュメント：https://nextjs.org/docs/app/getting-started/upgrading （バージョン 16 のガイド： https://nextjs.org/docs/app/guides/upgrading/version-16）
• agent-browser のインストールまたはアップグレード：npm i -g agent-browser@latest。 CLI が PATH にない場合は、続行する前にインストールしてください。事前チェックでは CLI を直接呼び出す必要があります。

事前チェック

セッションごとに一度、両方の視点が利用可能であることを確認します。

1. 保存済みのログイン状態があれば復元して、対象 URL を agent-browser で開きます。 最初に、このチェックアウト用の固定セッション ID を 1 つ決め、すべての agent-browser コマンドでそれを使用します。

   SESSION="$(agent-browser session id --scope worktree --prefix next-dev-loop)"
   export AGENT_BROWSER_SESSION="$SESSION"
   export AGENT_BROWSER_RESTORE="$SESSION"
   

   次に、対象 URL を開きます。

   agent-browser --session "$SESSION" --restore --enable react-devtools open <url>
   

   --scope worktree を使うと、並行するワークツリーやコピーしたチェックアウト間で競合を防げます。引数だけの --restore は、セッション ID を永続化キーとして使用し、保存済みの Cookie や localStorage があればナビゲーション前に読み込み、終了時に状態を自動保存します。open には、必ず希望する起動フラグを渡してください。必要に応じて、agent-browser がスコープ付きのバックグラウンド状態を再利用、再起動、または再生成します。

   通常の検証ではヘッドレスのままにしてください。ユーザーが UI の表示を求めた場合は、コーディングハーネスのインラインブラウザーで現在の URL を開きます。これは別のブラウザーコンテキストなので、状態が引き継がれると想定しないでください。ログイン状態や既存の agent-browser の状態を引き継ぐ必要がある場合は、代わりにそのセッションをヘッドありで開き直します。

   agent-browser --session "$SESSION" --restore --headed --enable react-devtools open <url>
   

   ユーザーがログインを操作する間は待ち、その後、同じセッションを使って続行し、残りのサイクルではヘッドありの状態を保ちます。

2. /_next/mcp の tools/list をプローブし、到達可能であり、get_compilation_issues が一覧に含まれていることを確認します。まず next dev のバナーからポートを確認してください。3000 以外の場合は、プローブする前に NEXT_MCP_URL=http://localhost:<port>/_next/mcp を設定します。

   • 到達できない場合は、next dev が実行されていないか、Next.js が 16.3 未満です。どちらかを判別するため package.json を確認してから、続行を拒否してください。
   • 一覧に get_compilation_issues がない場合は、Next.js が 16.3 未満です。続行を拒否し、アップグレードするようユーザーに伝えてください。

3. get_compilation_issues は Turbopack のプローブも兼ねています。"Turbopack project is not available..." というエラーレスポンスが返された場合、webpack が使われています。Turbopack が必須なので、続行を拒否してください。

4. get_routes を呼び出して、セッション中に使うルートマップを取得します。

サイクル

編集前 — 範囲を絞り込む

コードベースではなく、実行中のアプリに問い合わせます。/_next/mcp は、現在のルートをレンダリングしたファイルを把握しています。それらを検索範囲として使ってください。コードベースが大きくなっても、実行時のイントロスペクションは低コストのままですが、エージェントによる検索はそうではありません。

編集後 — 検証

4 つの失敗モードをそれぞれ確認します。

• コンパイルできること — get_compilation_issues。
• エラーなしで実行できること — /_next/mcp（サーバーのエラーと、上位に伝播したブラウザーのエラーの両方がここに表示されます）。
• 意図したとおりに動作すること — agent-browser でページを操作し、ユーザーに実際に見える内容をアサートします。
• React レベルの動作 — react-devtools を有効にした agent-browser では、コンポーネントツリー、props、state、レンダー回数を確認できます。フレームワークレベルのチェック（余分なレンダー、サーバー／クライアント境界の変化、Suspense のフォールバック）はここを基準にします。DOM のアサーションだけでは検出できません。

記憶に頼らず、tools/list または agent-browser のマニュアルから該当するツールを選んでください。

注意点

• 開発サーバーの実行中は .next を保持してください。 移動または削除すると、サーバーが生成済みの状態を参照できなくなり、増分キャッシュも破棄されます。バックアップへの移動もリセットになります。本番ビルドで出力を分離する必要がある場合は、別の distDir を設定してください。
• すべての agent-browser コマンドでセッションと復元キーを指定してください。指定しないと、空のデフォルトブラウザーが使われたり、ログイン状態の保存に失敗したりすることがあります。 最も簡単な方法は、agent-browser を実行する各シェルの先頭で AGENT_BROWSER_SESSION="$SESSION" と AGENT_BROWSER_RESTORE="$SESSION" の両方をエクスポートすることです。エクスポートしない場合は、すべてのコマンドに --session "$SESSION" --restore を渡してください。
• 2 つの表示内容が食い違う場合は、まずツールを疑ってください。 agent-browser がルートの破損を報告している一方で、/_next/mcp とサーバーが正常にレンダリングされたと報告しているなら、実際のバグよりも、古い、または誤ったブラウザーセッションが原因である可能性が高いです。アプリをデバッグする前に、表示内容を照合してください。
• クリックまたはナビゲーションを確認する場合、ページが落ち着くまで少し待ってから、wait --load networkidle（間違えるパスがありません）を実行し、スナップショットまたは読み取りでページを確認してください。リンクの正確な href を渡さない限り、wait --url は避けてください。推測したパスやプレースホルダーのパスは実際の URL と一致せず、25 秒後にタイムアウトします。
• open の直後やクリックの後に（open でページが報告されていても）読み取り結果が空、スナップショットが空、about:blank、または「no browser session」エラーになる場合は、ルートの破損ではなく、ブラウザーがページを閉じた（セッションが古くなった）ことを示しています。実行中のループと同じ起動フラグを使い、URL を指定してセッションを再度開き、もう一度スナップショットを取得してください。それでも空の場合は、agent-browser --session "$SESSION" --restore close を実行してから、同じフラグで再度開いてください。テスト対象のブラウザーを迂回する curl には切り替えないでください。
• React のイントロスペクション出力は、ナビゲーション後には古くなっています。再実行してください。
• /_next/mcp の応答は SSE です。sed -n 's/^data: //p' を使って data: 行から JSON を読み取ってください（単純な sed 's/^data: //' では event: 行が残り、解析に失敗します）。
• get_errors と get_page_metadata でデータを取得するには、少なくとも 1 回のナビゲーションが必要です。

参照

以下のツールはすべて、事前チェックに合格すると利用できます。tools/list にいずれかが含まれていない場合は、事前チェックで拒否されているはずです。もう一度確認してください。

# /_next/mcp                 notes
get_project_metadata         projectPath, devServerUrl, bundler
get_routes                   fs-scan; no browser session needed
get_errors                   runtime + build; needs a browser session;
                             includes browser-side errors caught by the
                             dev server
get_page_metadata            segment trie + routerType; needs a browser
                             session; use as a discovery shortcut for
                             which files power a route
get_logs                     returns logFilePath
get_server_action_by_id      hashed id → file + functionName
get_compilation_issues       Turbopack only; errors on webpack
                             ("Turbopack project is not available")

後処理

同じセッションと復元コンテキストを指定して、セッションを閉じてください。 agent-browser --session "$SESSION" --restore close。close はそのセッションの Cookie とストレージを保存するため、次のループで --restore を指定して開くと、ユーザーはログイン状態を維持できます。次のループに備えて next dev は起動したままにしてください。

Next.js の問題点を報告する

プロジェクト用の管理された Next.js フィードバック手順がすでに読み込まれている場合に限り、エージェントのフィードバックに参加してください。手順が存在する場合は機能が有効であり、存在しない場合は無効です。

有効な場合は、検証中に見つかった該当するフィードバック候補を、現在のユーザーリクエストのフィードバック候補キューに追加してから、検証を続けてください。このスキルのループ中や終了時に、フィードバックコマンドを実行したり、レビュー用フォームを開いたりしないでください。

管理された手順では、最終応答の直前に行う単一の報告処理が定められています。手順がない場合は、フィードバックをキューに追加したり、報告したりしないでください。