next-dev-loop
next dev 中の編集/検証リズム — 変更を加え、それが実際にランタイムで動作することを確認します。型やビルドが通るだけでは不十分です。
同じ実行中のアプリを2つのビューから検証します。
/_next/mcp— Next.js が自身について公開する HTTP エンドポイントです。ルート、セグメント、RSC、サーバーアクション、サーバーログ、Next.js が捉えたエラーなど、フレームワーク固有の情報を提供します。現在の対応ツール一覧はtools/listを呼び出してください。agent-browser— 実際の Chrome を操作する CLI です。DOM、コンソール、ネットワーク、React ファイバー、Web バイタルなど、フレームワークに依存しないブラウザ情報を提供します。操作を始める前に、バージョンに合った使用方法ガイドを取得するためagent-browser skills get coreを一度実行してください。サブコマンドを記憶から推測しないでください。
2 つのビューは相互に検証し合います。
必要条件
- Next.js 16.3+ かつ Turbopack 使用 —
/_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にない場合は、続行する前にインストールしてください — プリフライトでは直接呼び出せることを前提としています。
プリフライト
セッションごとに一度、両方のビューが稼働していることを確認します。
-
agent-browserをターゲット URL で開き、保存されたログイン状態があれば復元します。 まず、このチェックアウト用に安定したセッション 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 --headed --enable react-devtools open <url>--scope worktreeは、並行するワークツリーやコピーされたチェックアウトが衝突するのを防ぎます。--restoreのみを指定すると、セッション ID を永続化キーとして使用し、ナビゲーション前に保存されたクッキー/localStorage があれば読み込み、ブラウザを閉じると自動的に状態を保存します。open時には必ず希望する起動フラグを渡してください。agent-browser は必要に応じてスコープ化されたバックグラウンド状態を再利用、再起動、または起動し直します。ブラウザはユーザーのものです。状態が復元されなかった場合(初回起動、セッション期限切れ)でページがログインを必要とする場合、ユーザー自身がログイン操作を行います — 完了するまで待機してください。ログイン後は同じセッションと復元コンテキストを使用し続けてください。
agent-browser closeでクッキー状態が保存され、次回のopenで復元されます。 -
/_next/mcp(tools/list) をプローブ — 到達可能でget_compilation_issuesが一覧にあることを確認:- 到達不能 →
next devが実行されていないか、Next.js が 16.3 未満です。package.jsonを確認して切り分け、その後拒否してください。 get_compilation_issuesが一覧にない → Next.js が 16.3 未満です。拒否し、ユーザーにアップグレードを伝えてください。
- 到達不能 →
-
get_compilation_issuesは Turbopack プローブとしても機能します。エラーレスポンスが"Turbopack project is not available..."の場合、ユーザーは webpack を使用しています。拒否してください — Turbopack は必須です。 -
get_routes→ セッションの残りのルートマップを取得します。
ループ
編集前 — スコープを絞り込む
コードベースではなく、実行中のアプリに問い合わせてください。/_next/mcp は現在のルートをレンダリングしたファイルを把握しています。それらを検索スコープとして使用します。コードベースが大きくてもランタイムイントロスペクションは低コストで済みます。エージェント的な検索は行わないでください。
編集後 — 検証
4 つの障害モードがあります。それぞれを確認してください:
- コンパイル —
get_compilation_issues。 - エラーなく実行 —
/_next/mcp(サーバーエラーとブラウザからバブルアップしたエラーの両方がここに現れます)。 - 意図したとおりに動作 —
agent-browserでページを操作し、ユーザーが実際に何を見ているかをアサートします。 - React レベルの動作 —
agent-browserで react-devtools を有効にすると、コンポーネントツリー、props、state、レンダリング回数を公開します。フレームワークレベルのチェック(余分なレンダリング、サーバー/クライアント境界の移動、Suspense のフォールバック)はここで行います。DOM アサートだけではこれらを見逃します。
特定のツールは、記憶からではなく tools/list または agent-browser のマニュアルから選択してください。
注意点
- すべての
agent-browserコマンドは、セッションと復元キーを認識している必要があります。認識していないと、空のデフォルトブラウザを使用したり、ログイン状態の保存に失敗したりする可能性があります。 最も簡単な方法:agent-browserを実行する各シェルの先頭でAGENT_BROWSER_SESSION="$SESSION"とAGENT_BROWSER_RESTORE="$SESSION"の両方をエクスポートしてください。エクスポートしない場合は、すべてのコマンドで--session "$SESSION" --restoreを渡してください。 - 2 つのビューが矛盾する場合は、まずツールの問題を疑ってください。
agent-browserがルートは壊れていると言うが、/_next/mcpとサーバーは正常にレンダリングされたと言っている場合、実際のバグよりも、古いまたは誤ったブラウザセッションが原因である可能性が高いです — アプリのデバッグを始める前にビューを調整してください。 - クリックやナビゲーションの確認: ページの安定には少し時間がかかります。
wait --load networkidle(パスを間違えるリスクなし) で待機し、その後スナップショット/読み取りでページを確認してください。wait --urlは、リンクの正確な href を渡す場合を除いて避けてください。推測やプレースホルダのパスは実際の URL と一致せず、25 秒後にタイムアウトします。 - 空の読み取り、空のスナップショット、
about:blank、または「ブラウザセッションがありません」というエラーが、open直後やクリック後(openがページを報告した場合でも)に発生した場合、それはブラウザがページをドロップした(古いセッション)ことを示し、ルートが壊れているわけではありません。--session "$SESSION" --restoreを付けて URL でセッションを再度開き、スナップショットを取り直してください。それでも空の場合は、agent-browser --session "$SESSION" --restore closeを実行してから再度開いてください。curlにフォールバックしないでください。テスト対象のブラウザをバイパスしてしまいます。 - ナビゲーション後、React イントロスペクションの出力は古くなります。再実行してください。
/_next/mcpの応答は SSE です。data:行から JSON を読み取るにはsed -n 's/^data: //p'を使用してください (単純なsed 's/^data: //'ではevent:行が残り、パースに失敗します)。- 3000 以外のポートの dev サーバー:
next devのバナーを確認し、NEXT_MCP_URL=http://localhost:<port>/_next/mcpを設定してください。 get_errorsとget_page_metadataは、少なくとも 1 回のナビゲーションが行われないとデータが入りません。
リファレンス
プリフライトが成功すれば、以下のすべてのツールが利用可能になります。tools/list にこれらのいずれかが欠けている場合、プリフライトは拒否すべきでした — 再確認してください。
# /_next/mcp 備考
get_project_metadata projectPath, devServerUrl, bundler
get_routes ファイルシステムスキャン; ブラウザセッション不要
get_errors ランタイム + ビルド; ブラウザセッションが必要;
dev サーバーがキャッチしたブラウザ側のエラーを含む
get_page_metadata セグメントツリー + routerType; ブラウザセッションが
必要; ルートを提供するファイルを特定するための
探索ショートカットとして使用
get_logs logFilePath を返す
get_server_action_by_id ハッシュ化された ID → ファイル + functionName
get_compilation_issues Turbopack のみ; webpack ではエラー
("Turbopack project is not available")
後片付け
同じセッションと復元コンテキストでセッションを閉じます:
agent-browser --session "$SESSION" --restore close。close はそのセッションのクッキーとストレージを保存するため、次のループの --restore open でユーザーのログイン状態を維持できます。next dev は次のループのために起動したままにしておいてください。
next-dev-loop-<トピック> の兄弟スキル (例: next-dev-loop-rsc, next-dev-loop-debug) は、このプリフライトがすでに実行されていることを前提としています。ループから開始します。