Modern Web Guidance 1.0：Claude Code・Codex・Cursorの設定

Modern Web Guidance 1.0をプロジェクト用スキルとして導入し、まず1つのフロントエンド作業でガイドが使われることを確認します。legacy-scanはレビューする改善案の作成に使い、無人でコードを書き換える用途には使わないでください。Modern Web Guidanceの利用状況を送信しない場合は、最初のコマンドを実行する前にDISABLE_TELEMETRY=1を設定します。

Modern Web Guidance 1.0で変わること

Modern Web Guidanceは、既存のコーディングエージェントがコードを書く前に、ブラウザー機能に関する具体的な指針を渡します。2026年11月10日に公開された1.0リリースには、用途別のガイドが203本あり、Webプラットフォームの250機能を扱っています。Chrome、Edge、Firefox、MDNの各チームが、コミュニティの貢献者とともにプロジェクトを運営しています。

スキルは、エージェントに与える指示のまとまりです。関連するガイドを検索し、本文を取得して、実装上のルールを適用するよう促します。対応していない環境で使う代替処理、つまりフォールバックもその対象です。

検索には、ローカルの埋め込みモデルと、キーワードで順位を付けるBM25を組み合わせています。公式READMEによると、検索時の照合に外部モデルのAPIやAPIキーは必要ありません。

エージェントがブラウザーAPIの存在を知っていても、トランジションの動作や互換性のためのフォールバックを見落とす場合に役立ちます。ただし、対応ブラウザーの決定、変更のレビュー、アプリケーションのテストは引き続き開発者の責任です。

Claude Code、Codex、Cursorにインストールする

3つのエージェントには、同じCLI手順でプロジェクト単位のインストールを行えます。インストール処理はVercel Skillsを呼び出します。2026-11-13時点では、Skillsインストーラーの要件を満たすため、Node.js 22.20以降を使ってください。npm/npxと、必要なパッケージをダウンロードする権限も必要です。

プロジェクトのルートでBashを開きます。公式のインストールコマンドを実行する前に、Modern Web Guidanceのテレメトリーを停止します。

export DISABLE_TELEMETRY=1
npx modern-web-guidance@latest install

対話式インストーラーで対象のエージェントを選択できます。Claude Code、Codex、Cursorのうち、実際に使うものを選びます。1つのリポジトリで試す段階では、インストール範囲をプロジェクト内に保ってください。これはインストーラーの既定の範囲でもあります。

このCLI方式でインストールした場合は、次のファイルと呼び出し方法を確認します。

エージェント	プロジェクト内のスキルファイル	明示的な呼び出し
Claude Code	`.claude/skills/modern-web-guidance/SKILL.md`	`/modern-web-guidance`を入力します。
Codex	`.agents/skills/modern-web-guidance/SKILL.md`	`/skills`を使うか、`$modern-web-guidance`を指定します。
Cursor	`.agents/skills/modern-web-guidance/SKILL.md`	Agentチャットで`/`を入力し、スキルを選択します。

これらは、現在のインストーラーが各エージェントに割り当てているディレクトリです。プラグインのキャッシュや、グローバルインストールの保存先ではありません。

同じリポジトリでエージェントの新しいセッションを開始し、最初の確認ではスキルを明示的に呼び出します。表示されない場合は、再インストールの前に、選んだエージェント、インストール範囲、ファイルの場所を確認してください。

CLIでインストールしたスキルは、プロジェクトのディレクトリから次のコマンドで更新します。

npx modern-web-guidance@latest update

更新後はスキルファイルの差分を確認し、次の節にあるガイド取得の確認を繰り返します。これらのコマンドは@latestを使うため、将来の更新でもバージョン1.0が維持されるとは限りません。

プラグインのマーケットプレイスからのインストールは別の方法です。その更新手順と、このCLIの手順を混同しないでください。Claude Codeのプラグイン構成や管理については、プラグインのインストール・確認・削除の手順を参照してください。

検索、取得、エージェントによる利用を確認する

CLIの動作だけでなく、エージェントが取得した内容を使っていることも確認します。ターミナルでコマンドが成功しただけでは、エージェントがスキルを読み込んだ証拠にはなりません。

ドキュメントにあるダイアログの例をBashで実行します。

npx modern-web-guidance@latest search "animate a dialog modal backdrop"
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"

検索は、ガイドのIDと説明を含むJSONを返します。取得処理は、選択したガイドの本文を返します。出力が大きい場合、CLIは本文の代わりに保存先のファイルパスを表示することがあります。その場合は、エージェントにファイルを最後まで読ませてください。

続いて、インストールしたスキルを呼び出し、範囲を限定した作業を依頼します。次の依頼では、既存のフレームワークとブラウザー対応方針を維持し、編集前にガイドを取得するよう指定しています。

Use the modern-web-guidance skill to add an animated modal dialog.
Keep the existing framework and browser support policy.
Retrieve the relevant guidance before editing.
Afterward, report the guide IDs, required fallbacks, and tests run.

ツールの呼び出し履歴で、検索と取得が実際に行われたかを確認します。最終報告には、使ったガイドと、それを根拠に決めた実装内容を記載させます。「ベストプラクティスに従った」という説明だけでは不十分です。

リリースに含まれるダイアログのアニメーションガイドには、具体的なレビュー項目があります。transitionの一括指定を使う場合は、その後にtransition-behavior: allow-discreteを記述する必要があります。先に書くと、後のtransitionによって値がリセットされます。

表示時と終了時の動作、動きを減らす設定での動作、既存のダイアログ操作をテストしてください。

最初のコマンドが検索結果を返す前に失敗する場合は、まずNode.jsとパッケージのダウンロード権限を確認します。リリース時のスキル指示でも、パッケージの取得とオフライン動作は区別されています。必要なパッケージのコマンドだけを許可し、任意のnpx実行を許可しないでください。

検索結果が合わない場合は、「confirmation modal dialog」のように、具体的なブラウザー上の動作で検索します。手順を成功したように見せるために、関係のないガイドを取得する必要はありません。

legacy-scanは自動書き換えではなくレビューに使う

legacy-scanは、リポジトリやディレクトリ全体から改善候補を探すために使います。特定のコンポーネントを変更する場合は、ガイドの検索と取得を使ってください。この使い分けはモダナイゼーション手順のドキュメントでも説明されています。

読みやすい形式で結果を得るには、プロジェクトのルートから次を実行します。

npx modern-web-guidance@latest legacy-scan .

エージェントが確認できる構造化された出力には、次を使います。

npx modern-web-guidance@latest legacy-scan . --json

返されるのは、関連するガイドに対応付けられた変更候補です。ソースファイルが書き換えられるわけではありません。静的スキャナーは言語モデルを呼び出しませんが、その後の確認や編集では、エージェントが通常使っているモデルにアクセスします。

エージェントには、ドキュメントの4段階の手順に従うよう依頼します。

対象のディレクトリをスキャンし、変更候補を集めます。
周辺のコードとkeepWhen/dropWhenのルールに照らして、各候補を確認します。すべての一致箇所を変更必須とせず、誤検出を対象から除外します。
確認済みの候補と変更案を報告します。変更を始める前に、開発者の承認を求めます。
承認された候補について対応するガイドを取得し、その内容に従って変更します。既存のテストを実行し、変更した範囲を再びスキャンします。

意図的に残したフォールバックや、機能の対応状況を確認してから実行する互換性コードには特に注意します。古く見える実装でも、プロジェクトのブラウザー対応方針によっては必要な場合があります。

バージョン1.0のスキャナーが対象とするのは、ガイド全体の約20%です。古いパターンを確定的なルールで検出できるガイドに限られます。この割合はガイドのカタログに対するものであり、コードベースの割合ではありません。検出結果がゼロでも、コード全体の改善、アクセシビリティ、正しさが確認できたことにはなりません。

変更前にブラウザー対応方針と.mwgrcを設定する

互換性の要件を明示し、必要がなければ実験的なガイドは無効のままにします。既定では、スキルはBaseline Widely availableの機能をフォールバックなしで利用できるものとして扱います。

Baselineの設定手順では、プロジェクトの対象範囲をAGENTS.mdまたはCLAUDE.mdに記録する方法を説明しています。実際のサポート方針を使ってください。提案された置き換えを受け入れるためだけに、その方針を変えないでください。

プロジェクトのルートに置く任意のJSONファイル.mwgrcで、実験的なガイドへのアクセスを制御できます。保守的な方針を記録するには、既存の設定に次のフィールドを追加、または統合します。

{
  "allowOriginTrials": false,
  "allowVolatileFeatures": false
}

volatile扱いのガイドは、単一のブラウザーエンジンで提供される機能のうち、直近3か月に公開されたものや、まだ安定化の途中にあるものを対象にします。これらのガイドは検索できますが、本文の取得には明示的な許可が必要です。Origin Trialのガイドには別の許可設定があります。

volatile機能のガイドを許可するには、開発者自身の対話式Bashターミナルで次を実行します。

npx modern-web-guidance@latest set-allow-volatile-features

Origin Trialのガイドが必要な場合だけ、別のコマンドを使います。

npx modern-web-guidance@latest set-allow-origin-trials

各コマンドは確認を求め、対応する真偽値をtrueに設定します。表示された設定ファイルのパスと、変更されたキーを確認してから、ガイドの取得をやり直します。

エージェント内や非対話式シェルで拒否されるのは、意図された動作です。許可処理の実装は、人が操作する対話式ターミナルを要求しています。エージェントにこの確認を回避させないでください。

これらの設定が開放するのはガイドへのアクセスだけです。ブラウザーの機能を有効にしたり、サイトをOrigin Trialへ登録したり、プロジェクトの対応ブラウザー方針を広げたりはしません。

テレメトリーとコンテキストの費用を管理する

テレメトリーは、Modern Web Guidanceを実際に起動する環境で停止します。無関係なターミナルに設定するだけでは不十分です。プロジェクトのプライバシー説明によると、収集対象にはインストール数、呼び出したエージェント名、取得したガイドのID、エージェントが作成した検索クエリが含まれます。ユーザーの元のプロンプトは収集しないと説明されています。

ただし、検索クエリからも作業内容が伝わる可能性があります。.bashrcなどのBash起動設定にexport DISABLE_TELEMETRY=1を追加し、エージェントのコマンド実行環境がその変数を引き継ぐことを確認してください。必要に応じて、起動済みのエージェントやIDEを新しい環境で再起動します。

ツール呼び出しに使うBash環境で、次のコマンドを実行すると、値を表示せずに設定を確認できます。

test "${DISABLE_TELEMETRY:-}" = 1

終了ステータス0は、その環境で変数が1に設定されていることを示します。これはネットワーク通信の監査ではありません。また、エージェントの提供元や、他のツールのテレメトリー設定を確認するものでもありません。

検索がオフラインでも、作業全体がオフラインになるわけではありません。パッケージのダウンロードにはネットワークが必要です。Modern Web Guidanceのテレメトリーも、停止するまでは有効です。

コンテキスト量の目安として、READMEはmodern-web-guidanceを約205 tokens、chrome-extensionsを約175 tokensと案内しています。これらは、エージェントの作業全体で消費する量の上限ではありません。取得したガイド本文がコンテキストに加わり、検証や編集にも追加のエージェント作業が必要です。

代表的な作業で実際の使用量を測定してください。案内されているスキルのサイズだけから、削減額を計算しないでください。

評価結果を参考に、自分の作業で比較する

Googleの評価結果は試用の根拠になりますが、あらゆる作業での成功率やトークン削減を保証するものではありません。2026-11-08の公式READMEの評価結果は次のとおりです。

エージェントとモデルの表記	タスク / 検証項目	ガイドなし	ガイドあり	改善幅
`claude_code` / `opus-5-5`	215 / 1801	57%	88%	31パーセントポイント
`codex_cli` / `gpt-6.1-sol`	215 / 1795	54%	82%	28パーセントポイント
`antigravity_cli` / `gemini-4-argon`	214 / 1673	58%	94%	36パーセントポイント

これは個別の検証項目に合格した割合であり、本番プロジェクトを成功裏に完了した割合ではありません。タスク数と検証項目数も行ごとに異なります。同一の作業条件でモデルを順位付けした表としては扱わないでください。

評価ダッシュボードの手法説明では、合格率を「合格したチェック数 ÷ 実行したチェック数」と定義しています。採点前にクラッシュした実行やタイムアウトした実行は、比較相手となる実行とともに除外されます。

Googleは、自社のガイドを基準にこの評価を設計しています。エージェントによくある誤りの解説でも、ガイドが定める期待事項と出力を照合する方法が説明されています。提供元が実施した評価として読み、自分のアプリケーションの品質が独立に検証されたとは考えないでください。

導入を判断するには、代表的なコンポーネントの作業を、ガイドありとなしで比較します。モデル、プロンプト、ブラウザー対応方針は固定します。関連するブラウザー動作、回帰テスト、作業時間、実際の使用量を確認してください。

費用の判断には、トークン単価だけでなく、コーディング作業を完了するまでの費用を使います。リポジトリで重視する検証項目が改善し、レビューや利用の費用が許容範囲に収まる場合に、Modern Web Guidanceを継続して使ってください。