Communitygithub.com

Next.js 開発ループ検証

Next.jsアプリのコード編集後、実際のランタイム動作を確認します。単にコンパイルや型チェックが通るだけでなく、動作しているアプリで変更が正しく機能することを確認するためのスキルです。/next/mcp(Next.jsのビュー)とagent-browser(ブラウザのビュー)を組み合わせて検証します。next devの実行が必要です。

Next.js 開発ループ検証 とは?

このスキルは、Next.jsアプリケーションの開発中に「編集→検証」のサイクルを効率的に行うためのツールです。主に2つのビューを使用します。1つはNext.js自身が公開する/next/mcpエンドポイントで、ルート、セグメント、RSC、サーバーアクション、サーバーログ、エラーなどフレームワーク固有の情報を提供します。もう1つはagent-browser CLIで、実際のChromeブラウザを操作し、DOM、コンソール、ネットワーク、Reactファイバー、Webバイタルなどブラウザレベルの情報を取得します。この2つのビューを相互にクロスチェックすることで、コンパイルエラー、ランタイムエラー、意図した動作、Reactレベルの動作の4つの障害モードを確実に検証します。Next.js 16.3以上(Turbopack必須)、agent-browser 0.31.1以上が必要で、事前に両方のビューが稼働していることを確認するプリフライトチェックを行います。開発ループの中でコード編集前には現在のルートのスコープを絞り込み、編集後は各検証ステップを順に実行します。

対応~Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add https://github.com/0n6k4v-Coder/skills/tree/HEAD/next.js/next-dev-loop

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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 や弱いプローブにフォールバックしないでください — このスキルは両方のビューが上記のバージョンで稼働していることを前提としています。

プリフライト

セッションごとに一度、両方のビューが稼働していることを確認します。

  1. 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 で復元されます。

  2. /_next/mcp (tools/list) をプローブ — 到達可能で get_compilation_issues が一覧にあることを確認:

    • 到達不能 → 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 レベルの動作 — 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) は、このプリフライトがすでに実行されていることを前提としています。ループから開始します。

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

0n6k4v-Coder/skills

Translates Figma motion and animations into production-ready application code. Use when implementing animation/motion from a Figma design — user mentions "implement this motion", "add animation from Figma", "animate this component", provides a Figma URL whose node is animated, or when `get_design_context` returns motion data or instructs you to call `get_motion_context`.

0n6k4v-Coder/skills

Motion / animation context for the `use_figma` MCP tool — animating Figma nodes via manual keyframes, animation styles, easing, and timeline duration. Load alongside figma-use whenever a task involves adding, editing, or inspecting animation on a node.

0n6k4v-Coder/skills

Generate motion specification annotations from After Effects timeline data. Use when the user mentions "motion", "motion spec", "animation spec", "timeline", or wants to document a component's animation properties.

0n6k4v-Coder/skills

Turn on Cache Components in a Next.js app and resolve the blocking routes it surfaces. Use when the user wants to enable, adopt, or migrate to Cache Components, flip the `cacheComponents` flag, work through a flood of blocking-prerender / instant validation errors, run the `cache-components-instant-false` codemod, or decide between opting routes out with `export const instant = false` and fixing them in place.

0n6k4v-Coder/skills

Optimize a Next.js app that has `cacheComponents: true` — either the static shell on first paint, or the in-app navigation between routes. Picks the matching diagnostic loop and runs it.

関連スキル