0xKyosuke Blog
既存コードの古い回避策をエージェントに直させる——Modern Web Guidance 1.0のモダン化ワークフロー

既存コードの古い回避策をエージェントに直させる——Modern Web Guidance 1.0のモダン化ワークフロー

一言で言うと

Modern Web Guidance は、コーディングエージェントに「今どきの Web の正しい書き方」を教え込む Skills のセットよ。Web プラットフォームの専門知識、ベストプラクティス、それにブラウザの互換性データを、エージェントの手元に直接埋め込む。Chrome が 2026年5月の Google I/O でプレビューを出してて、2026年11月10日に version 1.0 が stable になった。

v1.0 からは Firefox と Edge も加わって、ブラウザ横断のプロジェクトになってる。公式のリリースノートだと、steward は Google Chrome、Microsoft Edge、Mozilla Firefox、それに MDN のチーム。ガイドは 203 本で、カバーしてる Web プラットフォーム機能は 250。

で、今回アタシが一番話したいのは、既存コードをスキャンして、古い回避策や要らない polyfill を安全に置き換えさせる modernization ワークフローよ。新規に書くときの案内だけじゃなくて、「もう動いてるコード」に手を入れる側に踏み出した、ってこと。

なぜ必要なのか

最新の frontier モデルでも、「動くコード」はだいたい書ける。でも Web の専門家が見ると、もっと速く、アクセシブルに、安全にできる箇所がほぼ見つかる——公式ブログはそう書いてるわ。公開されてる eval dashboard でも、Modern Web Guidance を入れない場合と比べてどれだけ良くなるかを見せてる。

evals でモデルが弱いと出た分野は、このあたり。

  • Accessibility：キーボードフォーカスや inert の管理、prefers-reduced-motion、フォームのアクセシブルなバリデーション。中途半端な ARIA は、付けないより悪くなるわ
  • User experience：スワイプやタッチ、dialog や popover のトランジション、ライト/ダークテーマ
  • Performance：メインスレッドのタスク分割、画面外描画の分離、レイアウトシフト対策
  • Security：安全な HTML サニタイズ、厳しめの Content Security Policy、passkey の資格情報管理

それと、AI は JavaScript で無理やり解決しがちなのよ。HTML や CSS のネイティブ機能で済む場面でもね。公式が挙げてる例は、popover や dialog のアニメーション、スクロールやスワイプのインタラクション、ページ遷移の API。ログインなら Passkeys と WebAuthn、チェックアウトなら Autofill。カスタムの JavaScript フォーム部品だと、特にモバイルで Autofill が壊れやすい、って話も出てる。

ガイドには Baseline の互換性データが埋め込んであるから、プロジェクトの対象ブラウザに合わせて「今使っていい新機能」を勧めてくれる。Web プラットフォームは動く標的でしょ。新しい機能が milestone ごとに出て、以前は使えなかったものが Baseline になっていく。案内の側がブラウザエンジニアや標準化、アクセシビリティの専門家にメンテナンスされてるから、プラットフォームと一緒に勧める内容も更新される、って立て付けよ。

利用者向けのガイドは、支援技術を普段使ってる専門家が実機で検証してる。全ガイドに eval があって、入れない場合との差は公開ダッシュボードで見られる。Chrome は別記事で、unguided の合格率は平均だいたい 50%、入れた場合は 90% 前後、とも書いてるわ。

まずは入れなさい

先に言っておくわ。この先に出てくる /modern-web-guidance は、スキルを入れてあるエージェントでしか呼べない。入れてない状態で打っても、そんなコマンドは無いって言われて終わりよ。だから最初にインストール。

いちばん素直なのは公式推奨の CLI。モダン化したいプロジェクトのディレクトリで、これを叩くの。

npx modern-web-guidance@latest install

既に古いバージョンを入れてるなら、更新はこっち。

npx modern-web-guidance@latest update

install は対話式のウィザードで、質問に答えながら入れていく形よ。CLI で入れておけば update で追従できるのも強みね。エージェント側のプラグインとして入れる手もあるけど、ほとんどの方法は自動更新に対応してない、って公式ドキュメントに注意書きがあるわ。

使ってる人が多い3つは、具体的にこうよ。

Codex

codex plugin marketplace add GoogleChrome/modern-web-guidance
codex plugin add modern-web-guidance@googlechrome

Claude Code

claude plugin install modern-web-guidance@claude-plugins-official

セッションの中で入れるならこう。最後の /reload-plugins を忘れるんじゃないわよ。

/plugin marketplace add GoogleChrome/modern-web-guidance
/plugin install modern-web-guidance@googlechrome
/reload-plugins

Cursor

Cursor Marketplace に Modern Web Guidance のプラグインが公式で載ってる。そこからインストールすればいいわ。CLI は要らないわよ。

Antigravity

本家 Google のエージェントだから、これも挙げておくわ。

agy plugin install https://github.com/GoogleChrome/modern-web-guidance

ほかにも GitHub CLI、Copilot CLI、Vercel の Agent Skills（npx skills）、Grok Build、Kimi Code、WebStorm、Goose 向けの入れ方が公式ドキュメントに載ってる。使ってるならそっちを見なさい。

入れ終わったら、そのプロジェクトでエージェントを開いて、次の節のとおりに頼めばいいわ。

ドキュメント、ガイドのカタログ、公開 eval dashboard、GitHub リポジトリ も公開されてる。ガイド自体を学習用に読む人もいるらしくて、CLI の search でユースケースを探す使い方も案内されてるわ。

目玉は既存コードのモダン化

Web 開発の大半は、真っさらなプロジェクトじゃ起きないのよ。何年も積み上がった古い回避策、もう要らない依存、ブラウザがネイティブでやってくれるようになった polyfill。しかも古いコードは壊れない。動くからバグにもならない。動いてるものを触るのは信頼が要るから、みんな躊躇する。

放置すると、バンドルサイズ、ページの応答性、アクセシビリティで静かに損をする。もっと厄介なのは、そういうコードベースでコーディングエージェントを使うと、周囲の 2015 年頃の書き方と、学習データに残った古いパターンを一緒にコピーすること。公式ドキュメントはそう指摘してるわ。

新しいものを書くときは、Modern Web Guidance がエージェントをモダンな Baseline 機能へ誘導する。既存コード向けに v1.0 が足したのが、この modernization ワークフローよ。既存の HTML、CSS、JavaScript、それに package.json を分析して、安全に上げられる箇所を見つけて、変更までエージェントを案内する。

インストールが済んでるなら、頼むときはこうでいい。

/modern-web-guidance Modernize the code in this directory

ドキュメント側の言い方だと、リポジトリ全体なら「legacy patterns をスキャンして、検証して、編集前に計画を出して」でもいいし、src/components/forms みたいにフォルダを指定してもいい。スラッシュで呼べないエージェントでも、自然言語で “legacy patterns” や “modernize” と頼めばスキャナーが走る。ただし、特定のコンポーネント名だけを指定すると、通常のガイド検索になる。そこはちょっと注意ね。

手動で叩くなら、CLI もある。

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

JSON が要るときは legacy-scan --json。CI/CD への自動組み込みは、公式曰く開発中よ。

何を、どうスキャンするのか

スキャンそのものはローカルで、LLM 呼び出しもトークン消費もゼロ。HTML、CSS、JavaScript/TypeScript、フレームワーク固有のコンポーネント、package.json を、AST と DOM、CSS パーサーで見る。

ルールの作り方も慎重よ。何でもかんでも拾うスキャナーは、そのうち無視される。公式は候補ルールをオープンソース約 45,000 リポジトリで試してて、半分で書いて調整し、残りの unseen な半分で採点した。捨てた候補の方が多くて、レガシーコードに対応物がない機能や、動いてる + や ~ の兄弟セレクタを :has() に書き換えるみたいな、実利のない構文だけの置換は外してる。デフォルトで載せる条件は、unseen なコードに対して静的マッチャー精度 80% 以上、検証後精度 90% 以上。

それと、ヒットには全部、明示的な keepWhen / dropWhen の rubric が付く。意図したフォールバック、CSS の @supports ガード、似て非なるコードは、エージェントが周辺を見てから捨てる。

対象は狭い。legacy-scan が見るのは、およそ 200 本のガイドのうち、決定的に（deterministically）レガシーを拾えて、偽陽性が少ない部分集合、だいたい 20%。公式ブログも、最初のリリースでは静的解析で限られたパターンだけを見る、予測可能な結果を出すために狭い範囲から始めた、って書いてる。広げていく予定で、その先には、既知パターンの照合だけじゃなくて、エージェント自身がコードを推論する agentic audits も入る予定よ。

4ステップで、いきなり書き換えない

動いてるアプリのリファクタは信頼が要る。自動でコードがわーっと変わるのも、微妙な回帰も、誰も欲しくない。だから --fix フラグは無い。一見ただの置換に見えても、実際はレイヤーをまたぐことが多いのよ。命令的な JS のリスナーや npm パッケージを消して、振る舞いを HTML と CSS に移す、みたいな。挙動とブラウザサポートの判断が要る。

代わりに、エージェントとの 4ステップのループになってる。

  1. Scan（legacy-scan）
    エージェントが npx modern-web-guidance legacy-scan --json を走る。関連しそうな文字列でファイルを先に絞って、候補だけ AST / CSS / HTML パーサーにかける。ここまで残った発見は、偽陽性じゃない確率がおよそ 92%。ヒットには、エージェント向けの検証チェックリストが付く。

  2. Contextual verification（keepWhen / dropWhen）
    リポジトリを開いてるエージェントが、周辺コードを rubric と突き合わせる。たとえば scrollHeight の読み取りが、textarea の高さハックじゃなくて仮想スクロールの一部なら捨てる。@supports で既に守られてるプロパティも捨てる。

  3. Report
    検証を通った発見をまとめる。legacy-scan が見るのは決定的ルールがあるガイドの部分集合だ、という注記も付ける。編集前に計画を見てほしい、と頼んでおけば、モダン化の計画もここで出る。

  4. Guide retrieval、リファクタ、テスト
    モダン化まで頼んだときだけ、エージェントが npx modern-web-guidance retrieve で該当ガイドを取る。ガイドの Baseline 互換パターンに沿って直し、変更したファイルに対して legacy-scan を再実行し、プロジェクトのテストスイートも回して確認する。

スキャンで落ちた発見や、残すと決めたフォールバックは、静的スキャンにはまた引っかかる。0件にするために安全なコードをいじるな、ってスキル側でも注意されてるわ。

実際に何が置き換わるのか

対象ドメインは、Forms and UI、dialogs and controls、CSS のレイアウト・タイポグラフィ・ビジュアル、それに Security。公式ドキュメントの例を、いくつか拾うわ。

領域拾うレガシー今の置き換え
Forms and UIJS で scrollHeight を見て textarea を自動リサイズCSS の field-sizing: content
Forms and UIIME ガードのない Enter の keydown 送信e.isComposing などを見た送信
Forms and UI未操作の入力まで :invalid で装飾してしまう:user-invalid / :user-valid
Forms and UI認証やチェックアウトで autocomplete が足りない標準の autocomplete 値
Dialogs and controlsオーバーレイを命令的な addEventListener で開く宣言的な popover と popovertarget
CSSアコーディオンを max-height: 9999px でアニメーションinterpolate-size: allow-keywords や calc-size()
CSS子の状態で親クラスを JS が付け外し:has(:checked) や :has(:focus-visible)
CSSダークモード用の @media (prefers-color-scheme: dark) の重複CSS の light-dark()
Security外部 CDN の script に Subresource Integrity が無いintegrity と crossorigin="anonymous"

変換の実例も、公式のまま置いとくわ。textarea の自動伸縮は、キー入力のたびにレイアウトを再計算してて、INP を悪化させうる。今は CSS で足りる。

// Before: Imperative layout recalculation on every keystroke
textarea.addEventListener('input', () => {
  textarea.style.height = 'auto';
  textarea.style.height = `${textarea.scrollHeight}px`;
});
/* After: Native declarative field sizing */
textarea {
  field-sizing: content;
  min-block-size: 3lh;
  max-block-size: 15lh;
}

popover も、クリックリスナーを書いて showPopover() するだけなら、属性で済む。

<!-- Before: a click listener that only calls showPopover() -->
<button id="openBtn">Open Menu</button>
<div id="menu" popover>Menu Content</div>
<script>
  openBtn.addEventListener('click', () => menu.showPopover());
</script>

<!-- After: declarative control, no JavaScript -->
<button popovertarget="menu">Open Menu</button>
<div id="menu" popover>Menu Content</div>

日本語、中国語、韓国語の IME で文字を確定してる途中に、無防備な Enter リスナーが送信してしまう件も、ちゃんとガイドに入ってる。ここ、地味だけど大事よ。

// Before: Fires mid-composition when confirming kanji/hanzi characters
textarea.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' && !e.shiftKey) {
    e.preventDefault();
    sendMessage();
  }
});

// After: Accurately checks IME composition state
textarea.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' && !e.shiftKey) {
    e.preventDefault();
    if (e.isComposing || e.keyCode === 229) return;
    sendMessage();
  }
});

勧める機能は、プロジェクトのブラウザサポート要件を見る。ガイドに Baseline と互換性データが入ってるから、対象外のブラウザ向けには、必要なところだけ条件付きでフォールバックや polyfill を載せる、って案内になってるわ。

書く側と、確かめる側

コードを書くのはワークフローの半分で、動かして期待どおりか見る必要がある。だから公式は、Modern Web Guidance と Chrome DevTools for agents の併用を勧めてる。前者が「書く前の知識」、後者が「実行して確かめる」側。両方あると、より良い解に少ないターンで着く、って説明よ。

例は3つ出てる。

  • パフォーマンスの目標まで回す。長い JavaScript タスクの分割の仕方は Modern Web Guidance が教えられるけど、実際にメインスレッドを何ミリ秒止めるかの測定はできない。Chrome DevTools for agents で、低スペック CPU のシミュレーション上にパフォーマンストレースを取り、メインスレッドを 50ms 以上ブロックしなくなるまで直す。INP を悪化させないための数字ね。
  • アニメーションの確認。modal、tooltip、popover の正しい動かし方は案内できるけど、アプリ全体の中でちゃんと動いて、見た目も周りと合うかは別。DevTools 側がページを操作してスクリーンレコードを撮り、動きを見る。prefers-reduced-motion が付いてるときに、ユーザーの設定を尊重してるかの確認も、こっちの役割。
  • メモリリークを見ながらビューをキャッシュする。SPA の遷移を速くするためにビューをメモリに残しつつ、アクセシビリティツリーからは隠す、というやり方は案内できる。でも長いあいだ同じページにいると、使い終わったビューを掃除しないとメモリが増え続ける。メモリのデバッグは DevTools 側よ。

要するに、静的なモダン化で終わらせず、実行時の検証までつなげる、って話。

事例に出た数字

公式ブログに載ってるチームの話を、数字はそのまま書くわ。

note inc. は、自前のデザインシステムと併用して、Next.js のフロントエンドをモダン化する取り組みの一環で使ってる。本番コードで 180 回 eval を回して、モダン Web チェックの合格率が 61% から 94% に上がった。スクロールアニメーション、tooltip、アコーディオンを、カスタム JavaScript じゃなくネイティブの HTML / CSS に寄せた、ってこと。マージ済みの 431 PR では、LCP 画像を正しく優先読み込みする率が 28% 増えてる。

MetaMask は、オープンソースのブラウザ拡張のすべてのプルリクエストに、3行のプロンプトで自動レビュー bot として載せてる。最初の5週間でおよそ 480 PR を見て、64件にコメントし、エンジニアが 43件を直した。内容はほとんどアクセシビリティ、HTML のセマンティクス、フォームまわりで、linter じゃ拾えない指摘。コメントから修正までの中央値は 15分。Interest invokers や Popover API みたいな新しい API をエンジニアが知るきっかけにもなって、レビュー時間は増えてない、むしろ減ったかもしれない、というコメントが載ってる。

WeTV（Tencent の国際向け動画配信）は、CI/CD に AI のコーディングエージェントを入れて、パフォーマンス回帰の診断を Chrome DevTools for agents、修正を Modern Web Guidance が担当してる。失敗したパフォーマンスチェックの 90% を自動で診断して解消し、デバッグと解消の時間は 87% 短くなった（4時間から30分。手動評価を含む）。

Pensionbazaar は、ページの構築と検証にこの2つを組み合わせて、ターンアラウンドを 90% 超短縮（約4日から数時間）、新しい画面の UI バグも 90% 超減らした、とある。姉妹の Policybazaar は、Chrome DevTools for agents でトラフィックの多いランディングページ約 30本のパフォーマンス監査を自動化して、手作業を 92% 減らした。こっちは監査側の話ね。

アタシの見立て

これはハーネスの話じゃないわ。エージェントの運行装置を新しくするものじゃなくて、ループの側にドメイン知識を足す Skill。モデルがツールを呼び、ガイドを取り、直して、またスキャンする。手順に乗せる知識のセットよ。

一番効くのは既存のコードベースよ。新規のコンポーネントを書くときにも案内はするけど、v1.0 がわざわざ足したのは「もう動いてるコード」のスキャンだし、公式もほとんどの Web 開発はそこで起きるって言ってる。古い回避策、用済みの依存、今はネイティブで足りる polyfill。そこを機械的に拾って、ガイド付きで置き換えられるんだから、実務で使う意味は十分あるわ。

ただし、期待しすぎないことね。v1 のスキャンは静的解析で、対象パターンもまだ狭い。ガイド全体のおよそ 20% にしか、決定的なレガシー検知ルールが無いのよ。--fix で一発適用するものでもないし、エージェント自身がコードの意味を推論する監査はこれから。だから「入れたらフロントが全部モダンになる」なんて思ってたら、バッカじゃないのって話。拾った発見を検証して、計画を見て、テストで確かめる。その前提で使う道具よ。

書く前の知識は Modern Web Guidance、実行時の検証は Chrome DevTools for agents。この分担を押さえておけば、迷うことはないでしょ。

元の発表は Chrome の公式ブログ（Modern Web Guidance v1.0） よ。モダン化ワークフローの詳細は Modernization workflow のドキュメント、使い始めるなら Modern Web Guidance のドキュメント を読みなさい。

記事一覧へ