Tech Teardown 046｜modern-web-guidance：Coding agentに「現代のWebマニュアル」を設置する

背景：v1.0.0 リリース一日で3000星と一つの議論

2026年11月10日、GitHubリポジトリ「GoogleChrome/modern-web-guidance」がv1.0.0をリリースし、Apache-2.0ライセンスを採用。11月11日時点で3,000★（3,109）を超えていた。同日にShow HNに掲載され、209ポイント、58件のコメントが寄せられた。

このプロジェクトで最も注目すべきは星数ではなく、署名である：READMEマニュアルはGoogle Chrome、Microsoft Edge、Mozilla Firefox、MDNの4つのチームとWeb開発コミュニティによって共同で維持されている。4大ブラウザメーカーが同じ「エージェントマニュアル」に支持を与えているのは、Web標準の歴史において稀なことだ。

解決しようとしている問題は一言で言えば：LLMの訓練データには古いコードが詰め込まれており、エージェントはデフォルトで複雑なJSを生成するが、実際には既に高性能なソリューションがある場合も多い。モデルがAPIの存在を知っていても、実際の実装パターンが不足している。ChromeチームのpaulirishはHNで例を挙げている：ブラウザ自体で過去には50行のJSや一つの依存関係が必要だったことを処理でき、CSS.highlightsはテキストのハイライトを行い、dialogにはshowModal()が自動的に背景とフォーカス管理を提供し、field-sizingはtextareaが入力に応じて自動的に高くなるようにする。モデルはこれらのAPIの名前を知っているが、デフォルトで使用することはない。

その方法は、Webプラットフォームの専門知識、ベストプラクティス、ブラウザの互換性データをskillsとしてまとめ、直接コーディングエージェントのワークフローに組み込むことである。カテゴリのシグナルはインストールリストに隠されている：Vercel Skills CLI、gh skill install、各エージェントのプラグインマーケット、一つのREADMEには8つの配布チャネルが集まっており、「エージェントに外部知識を装備させる」ことがインフラストラクチャになりつつあり、ブラウザメーカーが集団でコンテンツ供給者になるのは初めてのことだ。また、リポジトリの分担にも注意すべき：このリポジトリは配布・パッケージング用のもので、コンテンツのソースコードはGoogleChrome/modern-web-guidance-srcにあり、浅いクローンにはRelease v1.0.0のみがコミットされており、プロジェクトの開発歴史はすべて-src側にある。

アーキテクチャと原理：ドキュメント即ち製品、検索即ちパイプライン

ローカル統計（.gitを含まない）：265ファイル、そのうち236ファイルがmarkdown形式で、従来のソースコードは存在しない。本質的には「ドキュメント即ち製品」のリポジトリである。主体はskills/modern-web-guidance/の下にあり、209のガイドラインが17のカテゴリーに分かれている：css、js、html、forms、accessibility、performance、security、privacy、pwa、wasm、webmcp、built-in-ai、ui-components、ui-atoms、ui-behaviors、visual-design、user-experienceなど。また、第二のskillパッケージchrome-extensions（Manifest V3、バックグラウンドワーカー、拡張API、Chrome Web Storeでのリリース）も含まれている。README自述は250の現代Webの特徴をカバーし、すべてBaselineプロジェクト（web-platform-dx）の特徴ページにリンクされており、互換性は4つのブラウザで共通にサポートされている。

作業パイプラインは3ステップ：agentがタスクによってskillをトリガーする；ローカルで検索を行い、README自述ではオフラインのゼロ依存のエンバインドモデルとBM25を用いて検索を行い、ネットワークリクエストやAPIキーを使用しない；ヒットした場合、retrieveがガイドラインの全文をコンテキストに注入する。2つのエンジニアリングの詳細は注目に値する：一つ目は、検索コマンドには必ず—skill-version 2026_11_09-5bcc021bパラメータが必要であり、ガイドラインの内容とskillのバージョンが固定され、ドリフトを防ぐ。二つ目は、実験的なOrigin Trial APIと「変動する特徴」（単一エンジン、3ヶ月以内にリリースまたはまだ安定化中）が検索で表示されるが、retrieveは制御されており、開発者は明示的にset-allow-origin-trialsまたはset-allow-volatile-featuresを実行してロックを解除する必要がある。agentは不安定なAPIを勝手に使用することはできない。

内容側には自己剪除メカニズムもある。README自述ガイドラインは「トークンを節約するために設計されている」とされ、評価プロセスも重視されている：opportunity（100%から指導なしでの通過率を引く）とuplift（指導ありの場合と指導なしの場合の通過率の差）。モデルはガイドラインを見なくても正しく実行できる内容は直接切り捨てられ、agentが苦労する部分には密度が加えられる。SKILL.md自体も約205トークン、chrome-extensionsパッケージは約175トークンで、インストール時に—chooseを使用して必要なパッケージのみを選択できる。カテゴリーのカバレッジも野心を示している：webmcpディレクトリではagentにWebMCPを使ってウェブフォームとクライアントJSファンクションをAIツールにエクスポートする方法を教え、built-in-aiディレクトリではブラウザ内で翻訳、要約、言語検出を行うネイティブAPIについて説明しており、これらはすべて最先端の能力である。

重要なメカニズムの詳細：「トリガー」を強制条項として記述

SKILL.mdにはわずか90行しかなく、設計はかなり抜け目のないものです。descriptionには「MANDATORY: ALL HTML/CSSおよびクライアントサイドJSタスクではFIRST実行する必要があります。スキップしないでください」と記載されています。その理由は、web APIが急速に進化しており、トレーニングの重みには古いパターンが含まれているからです。その後、モダールーム、popover、container queries、view transitions、scroll-driven animations、autofill、passkeys、CWV、built-in AI、WASMなどの一連のトリガーシナリオが列挙されていますが、トリガーしないシナリオも明確に記載されています：バックエンドSQL/ORM、CI/CD、Docker、Python/Go、ビルドツール、テスト。境界線は、ほとんどの人間チームの規範よりも明確に設定されています。

4ステップのワークフローも同様に具体的です。searchでは、2〜5語のアクション指向のクエリが求められ、一度に1つの能力点のみを検索します。フレームワーク名やアプリケーション用の名詞は使用禁止です。ユーザーが「削除前に確認」と言った場合は、「confirmation modal dialog」として翻訳してから検索します。結果がない場合は、別の具体的な名詞を使って再検索し、さらにレベルダウンします。retrieveでは、カンマを使って複数の結果を取得でき、出力は9.5KBを超える場合は自動的に一時ファイルに保存され、截断を防ぎます。また、エージェントにはcat/head以外のファイル読み取りツールを使用するよう要求されています。3ステップ目では、ガイドラインを参照して自己検証を行い、legacy-scanはこのステップでは使用しないと明確に述べられています。4ステップ目の納品時には、「### Modern Web Guidance」という節が付属し、どのidが適用され、どのような問題を防いだかを項目別に記載しています。また、ガイドラインの原文の短い引用も含まれており、記憶だけで引用文を作ることは禁止されています。

ガイドライン本体の質は、navigation-drawerの記事から確認できます。ダイアログボックスはtop-layer要素（modal dialogまたはpopoverのmanualモード）を使用して実現され、スライドジェスチャーは横スクロールコンテナと2つのscroll-snapポイントによって処理されます。動き、速度、中断の追跡はすべてブラウザのネイティブ処理によって行われ、JS pointer-eventコードは一切使用されていません。背景の透明度はscroll-driven animationを使ってスクロール位置にリンクされています。さらに、IntersectionObserverが開閉状態を判定します。これが「モデルはAPI名を知っていても、このように組み合わせることはできない」という密度の補完です。

legacy-scanは独立した入口です：既存のコードをスキャンして遺産パターンを探しますが、ガイドラインのサブセットの約20％のみをカバーしています。スキャン結果は、keepWhen/dropWhenルールを人手で照合して偽物を排除する必要があります。

実行環境の問題も事前に解決しました。SKILL.mdでは、権限許可リストをnpx -y modern-web-guidance@latest *まで正確に指定し、裸のnpxの使用は禁止されています。サブマシンや承認制環境（Codex、Claude Code）では、初回実行前にネットワークアクセス許可を積極的に申請する必要があります。これによりタイムアウトを防ぎます。~/.npmが読み取り専用の場合は、NPM_CONFIG_CACHEを/tmpに指定します。ネット切断時はnpx —offlineで再試行します。pnpmがある場合は、pnpxを優先して使用します。また、ガイドラインには一つの基準があります：常にsearchを行い、記憶に頼ることなくガイドの内容を作成しないこと。ガイドはユーザープロジェクトの最適なローカル標準です。

配布と評価：一つのコンテンツで8つのエージェントエコシステムに供給

配布は3層構造になっています。CLI層：npx modern-web-guidance@latestに7つのサブコマンド（install/search/retrieve/legacy-scan/update/set-allow-origin-trials/set-allow-volatile-features）を追加します。Node 22以降から使用可能です。インストール層：READMEには8種類の方法が記載されており、インタラクティブなガイド、Vercel Skills CLI（npx skills add）、gh skill install、Google Antigravity、GitHub Copilot CLI、Claude Codeプラグイン、Grok Build CLI、Kimi Code、OpenAI Codexなど、各社の1つのコマンドがあります。リスト層：リポジトリにはplugin.json（agent-plugins.org schema 1.0.0）、gemini-extension.json、kimi-plugin.jsonの3つのマニフェストが同時に保存され、同じスキルを一般的なエージェント、Gemini、Kimiにそれぞれパッケージ化します。さらにpolicies/modern-web-guidance.tomlがあり、modern-webコマンドをplanモードでask_userに設定します。

効果の数値はすべてREADMEの自己説明に基づいています：11月8日の一回のevalで、antigravity_cli（gemini-4-argon）は58％から94％（+36pp）、claude_code（opus-5-5）は57％から88％（+31pp）、codex_cli（gpt-6.1-sol）は54％から82％（+28pp）でした。約215のタスクと約1800の断言がありました。evalの問題作成方法は注目に値します：完全なベンチマークアプリケーション（daily-grind、devtools-times）上で、実際の開発者を模倣したpromptを定義しています。例えば「画像の読み込みを速くしてほしい」といったものです。どのAPIも明示的に指定せず、エージェントが自然にガイドを見つけて使えるかを試験しています。評価器はClaude/Codex/AGYの3つのエージェントの黄金解を使用して基準を設定し（100％合格）、未変更のベースラインアプリケーションを用いています（0％合格）。READMEの成績表は11月2日から2日ごとに更新され、3つのエージェントそれぞれのガイド別詳細が公開のEval Dashboardに掲載されています。これらは公式の情報であり、第三者の確認を受けていませんが、「未指導のベースラインも一緒に報告する」という姿勢は、単に高得点を報告するよりも正直です。

遥測は真実を明らかにしています：匿名でインストール数、エージェント名、ガイドID、検索キーワードを収集しており、元のpromptは含まれていません。コードの位置はREADMEに記載されています。HNには側面証拠が提供されています：数ヶ月前にインストールされており、Claude Doctorがそれを削除していないことから、効果があることがわかります。

論争とリスク：「現代」を定義する資格があるのは誰か

HNの熱評区には正反両方の意見があります。需要側の共感は非常に直接的です：早く欲しかったと言う人もいれば、多くの「2行で現代の特性を表現できるはずなのに一つの文章で書かれている」PRをレビューしてきた人もいますし、自分自身も半製品のツールを作成したことがあります。批判の要点は3つです。1つ目は、「AI時代においてベストプラクティスはすでに死んでおり、誰もAI生成のコードを読むことはないだろう」という点です；paulirishの反応では、保守性が次のフロンティアになると述べています。1行のCSSスキームの方が、60行のResizeObserverとsetTimeoutを使ったビジネスコードよりも優れていると。別の人はさらに一言付け加えました：ユーザー体験を改善するベストプラクティスは死んでいないが、焦点が開発者の効率性から移っているだけだということです。2つ目は、「現代のWebプロトコル」が必ずしもベストプラクティスとは限らないという点です。ブラウザの実装の違いは10年かけて解消される必要があり、異なるデバイスやブラウザ間での手動テストは避けられません。また、ある人はエージェントを単なるランダムなマシンと見なし、ガイドラインに従って全体をチェックし、平均値を取っても役に立たないと考えています。3つ目が最も重要な点です：ガバナンスです。Chromeは標準化の世界で過度に権力を持っており、すべてのLLMがChromeチームの指導に従うようにすることは、「このブラウザを使ってこのサイトにアクセスしてください」という状況につながります；反応する人々は、FirefoxやEdgeも貢献者であり、Baselineをサポートする実践のみを推奨していると指摘しています。また、中立的なリポジトリで発表する方が良いというコメントもあります。この懸念は古くからあります：2026年5月のプロジェクトの初期段階では、Adrian Roselliが「Maybe Don’t Rely on Google’s Modern Web Guidance」と批判しました。v1.0では3社が共同でメンテナンスを行い、Baselineに合わせています。これは今回の批判への反応と読み取れます。しかし、Mozilla/Edgeの実際の貢献度は、今回は独立して確認されていません。

リスクには2つあります。evalは公式が自ら問題を出し、自ら評価を行います。opportunity/upliftの方針は透明ですが、タスクセットはネイティブなソリューションがあるケースに偏っています。upliftが高いのは当然であり、選択の偏りを心の中で減らす必要があります。配布に関しては、simonwがHNでシンプルな提案をしました：npmパッケージ以外は、GitHub Pagesを使ってmarkdown索引ページを公開する（現在は404エラー表示）とし、すべてのドキュメントの純粋なmdバージョンをリンクし、grep検索用に設計することです。何もインストールする必要はありません；Chromeチームの反応では、developer.chrome.comのguidesページを指摘しています。言い換えれば、エージェントがnpxで実行されるのを望まない人々には、現在、公式の平易な方法が欠けています。

結論と展望

modern-web-guidanceの価値は、209件のドキュメントそのものにあるのではなく、「エージェント知識供給」に模範を示した点にある。知識を重みに詰め込まず、必要に応じて検索できるエクステンションとして構築し、内容ではなくポインタを保存し、バージョンが固定され、実験特性が制御され、使用法が強制的に公開される。ある人はこれこそがエージェントの聖杯形態だと言っている：内蔵知識を最小限にし、その他はリアルタイム検索とキャッシュを加える。私もその方向に同意する。以下の3点が注目すべき点だ：Mozilla/Edgeの貢献が署名によるものか実質的なものかは、-srcリポジトリのコミット分布を見ればわかる；evalが第三者によって再現される可能性があるかどうか；公式の純粋なmdインデックスページが補完されるかどうか。開発者にとっては、フロントエンドプロジェクトは今すぐインストール可能で、コストも低い（npxコマンド1つで済む）。最悪の場合でも、エージェントが何度もドキュメントを検索するだけだ。エージェント基盤を構築する人にとっては、SKILL.mdのトリガー条件の書き方、opportunity/upliftの内容の編集方法、9.5KBのファイル保存時の切り捨て防止が、自分のスキルシステムに直接取り入れられる。ブラウザメーカーが「時代のコードを書かない」ことを機械が実行可能な規範にするという事実は、3000の星ほどではないかもしれないが、より大きな意味を持つ。

情報源

• リポジトリ：github.com/GoogleChrome/modern-web-guidance（Apache-2.0；11月11日時点で3,000以上の★、スナップショット3,109；v1.0.0は11月10日にリリース、git log形式；ソースコードはGoogleChrome/modern-web-guidance-srcにあり）
• 11月11日のローカルクローン統計（/tmp/mwg-1111）：265ファイル（.gitを除く）、236個のmarkdownファイル；guidesは209篇、17のカテゴリディレクトリ；SKILL.mdは90行、README.mdは636行；plugin.json/gemini-extension.json/kimi.plugin.jsonの3つの配布リスト；policies/modern-web-guidance.toml
• README.md（4チームが共同で公式説明を維持；250の機能とBaselineのリンク；オフラインエンバインド+BM25、—skill-version 2026_11_09-5bcc021b、Origin Trial/変動する機能ゲートキーピング、8種類のインストール方法、7つのCLIサブコマンド、Node≥22、テレメトリーデータはすべてREADME形式；evalテーブルはNov 8の3行+36/+31/+28ppがREADME説明で、第三者のレビューを受けていない；skillパッケージのトークンポイントは約205/約175と説明）
• SKILL.md（MANDATORYのトリガーテキスト、4ステップワークフロー、9.5KBのファイルサイズ、披露セクションのフォーマット、legacy-scanは約20％カバー）；guides/ui-components/navigation-drawer.md（引き出し型の実装例）
• HN story 50443812（209▲/58💬、Algolia検索）：paulirishのトップレベルと応答、halflife、phyzix5761、sublinear、advisedwang、philipwalton、0o777、simonwとkinlan、nico、fumar、cyanydeez；正反両方の意見が述べられているが、一致した高評価ではない
• adrianroselli.com 2026/05「Maybe Don’t Rely on Google’s ‘Modern Web Guidance’」（HN12▲）；Mozilla/Edgeの実際の貢献度は独立して確認されていない

署名：永亮