やってみた 2026年11月15日

modern-web-guidance をネットを切ったコンテナで試した。検索は手元で完結、でも npx 経由は1回70秒待ち、検索語は既定で送信

XECIN TypeScript開発支援テレメトリWeb標準

GitHubのトレンドを眺めていたら、2位に GoogleChrome/modern-web-guidance-src が入っていました。説明は「Keep your coding agent up to date with the latest web best practices」。コーディングエージェントに、いまの Web 標準での書き方を教えるための CLI とガイド集です。スターは6,553で、この日だけで1,220増えていました。言語は TypeScript です。

私が引っかかったのは README の2か所です。仕組みの節には「offline, zero-dependency embedding model and BM25 search engine (no network calls, no API keys)」とあり、少し下の Telemetry & Privacy の節には、エージェントが生成した検索語などを匿名で集めると書かれています。どちらも嘘ではないはずです。ただ、運用を考えると「何が、どこへ、いつ出ていくのか」と「ネットが無い環境でどう振る舞うのか」は、チームに入れる前に自分の手で確かめておきたいところです。社内の閉じたネットワークや、外向きの通信を絞った CI で使う場面を想定して試しました。

試した環境

使い捨ての Docker コンテナ(node:22-bookworm、メモリ4GB・CPU2)の中だけで動かし、終わったら破棄しています。

  • OS: Debian 12.14(x86_64)
  • Node.js v22.23.1 / npm 10.9.8
  • 対象: modern-web-guidance-src の main 5e5cd33(2026-11-13 のコミット)と、npm の modern-web-guidance 1.0.0(2026-11-10 公開)

npm の公開履歴を見ると、2026-04-30 の 0.0.55 から数えて121版あり、11月に入ってからだけで11版出ていました。README が npx modern-web-guidance@latest ... で毎回呼ぶ形を勧めているのは「中身を古くしないため」だと書かれていて、この更新の速さなら理屈は分かります。パッケージ自体は依存0・280ファイル・展開後約16.5MBでした。

まず README の Try it out をそのまま

# npx の初回(npm のキャッシュが空の状態)
$ npx -y modern-web-guidance@latest search "animate a dialog modal backdrop"
[{"id":"animate-to-from-top-layer","description":"Animate elements such as dialogs, popovers, and tooltips as they're entering/exiting the top layer."},
{"id":"light-dismiss-a-dialog","description":"Create a modal dialog that can be closed via light dismiss (i.e. clicking or tapping outside of the dialog)"},
{"id":"prevent-page-scroll-under-modal-dialog","description":"Prevent the underlying page from scrolling while a modal dialog is open."},
...(全10件・1,994バイト)
# rc=0 / 1.13秒。2回目は0.39秒で、出力は1バイトも変わらず

# 1位のガイドを取り出す
$ modern-web-guidance retrieve animate-to-from-top-layer
--- Guide for animate-to-from-top-layer ---
# Animate Elements To and From Top Layer
...(10,988バイト)

1位の animate-to-from-top-layer は、@starting-style、transition-behavior: allow-discrete、overlay を使ってダイアログの出入りを動かす話で、モーダルの背景を動かしたいという質問への答えとしては的を射ています。

コストの目安として大きさも比べておきます。検索の結果は約2KB、ガイド1本は約11KBで、取り出すと文脈に入る量は5倍強になります。エージェントに「まず検索、必要なものだけ取り出す」と使わせる設計になっているのは、この差を見ると納得できます。

送られる中身を、送らずに見る

テレメトリの仕組みは、パッケージの中を読むとすぐに分かりました。CLI はコマンドを実行するたびに watchdog/main.js という子プロセスを detached: true で起こし、標準入力にイベントを1行書いて、自分はすぐ終わります。子プロセスは親がいなくなったことを標準入力の終わりで知り、https://play.googleapis.com/log?format=json_proto へまとめて POST してから終了する作りです(送信の打ち切りは5秒、要求のタイムアウトは10秒)。

実際に送ってしまうと中身は見えないので、子プロセスの fetch だけを差し替えました。子プロセスは親の環境変数を引き継ぐので、NODE_OPTIONS に --require を入れておけば両方に効きます。要点だけ抜き出すとこうです。

// hook.cjs(NODE_OPTIONS="--require /work/hook.cjs" で読み込ませる)
const fs = require('fs');
const isWd = process.argv.some((a) => a.includes('watchdog/main.js'));
if (isWd) {
  globalThis.fetch = async (url, init = {}) => {
    // 送るはずだった URL と本文をファイルに残し、外へは出さずに 200 を返す
    fs.appendFileSync(process.env.TELE_LOG, JSON.stringify({ url: String(url), body: init.body }) + '\n');
    return new Response('{}', { status: 200 });
  };
}

1ケース1プロセスで回して、記録された本文を取り出した結果がこちらです。

# search "animate a dialog modal backdrop"(本文 960 バイト)
POST https://play.googleapis.com/log?format=json_proto   log_source=2921
{"search_result":{"query":"animate a dialog modal backdrop",
  "search_items":[{"guide_id":"animate-to-from-top-layer","similarity":0.8399},
                  {"guide_id":"light-dismiss-a-dialog","similarity":0.8389}, ...全10件]},
 "os":3,"version":"1.0.0","latency_ms":250,"success":true}

# CLAUDECODE=1 を付けると "agent":"claude" が増える(981 バイト)
# retrieve     → {"retrieve_result":{"guide_id":"animate-to-from-top-layer"}, ...}(292 バイト)
# legacy-scan  → {"tool_command":{"command_type":6}, ...}(266 バイト)

# 止め方の確認
en_default                          watchdog_starts=1 fetches=1
en_disable      DISABLE_TELEMETRY=1    watchdog_starts=0 fetches=0
en_disable_yes  DISABLE_TELEMETRY=yes  watchdog_starts=1 fetches=1

コマンドごとに整理するとこうなります。

コマンド送られるもの本文の大きさ
search検索語そのまま、結果10件の guide_id と similarity、OS、版、待ち時間の区分960 バイト
search(CLAUDECODE=1)上に加えて呼び出し元のエージェント名 claude981 バイト
retrieve取り出したガイドの ID292 バイト
legacy-scanコマンドの種別だけ(スキャンしたパスやファイル名は載らない)266 バイト
どれでも DISABLE_TELEMETRY=1子プロセス自体が起動しないなし

README に書かれている項目(インストール数・呼び出し元のエージェント名・取り出したガイドの ID・検索語)とおおむね一致していて、隠れた項目は見当たりませんでした。README に無かったのは、結果10件の ID と similarity、OS、版、待ち時間の区分(latency_ms は 250 のような段階に丸められる)くらいです。legacy-scan がパスを送らないのは丁寧だと感じました。ちなみに similarity は並び順と一致していません(4位が0.8197、5位が0.8265)。BM25 と組み合わせた順位なのだと思いますが、そこは確かめていません。

想定外だったのは止め方のほうです。

最初、私は社内の設定でよく見る書き方で DISABLE_TELEMETRY=yes を付けました。ところが子プロセスはいつもどおり起動し、本文も1件記録されました。コードを読むと、値を小文字にして "1" か "true" のときだけ止める作りです。README の例も DISABLE_TELEMETRY=1 なので仕様どおりではあるのですが、チームの標準設定に =yes と書く人は普通にいそうなんですよね。止めるつもりなら値は 1 にする、と手順書に書いておくのが安全です。

もう1つ。日本語で検索すると何も返りません。search "ダイアログの背景をアニメーションさせたい" も search "モーダル" も結果は [](3バイト)でした。それでも本文344バイトの記録は残り、検索語は日本語のまま載っています。search "dialog の背景をアニメーション" のように英単語が1つ混ざると10件返るので、英語の語で引く前提の作りだと考えています。エージェントが英語で検索語を作るぶんには困りませんが、人が直接叩くなら英語で、ということになります。

ネットを切ると、npx だけが待つ

次に、ホスト側で docker network disconnect bridge してコンテナをネットから切りました。curl https://registry.npmjs.org/ が Could not resolve host で失敗するのを確かめてから、同じ検索を呼び方を変えて回しています。

呼び方(ネットなし)終わるまで出力
インストール済みの modern-web-guidance search144ms1,994 バイト(ネットありの時と同一)
同上に DISABLE_TELEMETRY=1144ms同じ
インストール済みの retrieve35ms10,988 バイト
npx -y modern-web-guidance@latest search70,675ms1,994 バイト
npx -y modern-web-guidance@1.0.0 search70,640ms1,994 バイト
npx -y —offline modern-web-guidance@latest search354ms1,994 バイト
npx -y —fetch-retries=0 modern-web-guidance@latest search445ms1,994 バイト

検索そのものは本当に手元で完結していて、ネットを切っても結果は1バイトも変わりませんでした。テレメトリの子プロセスは、ネットが無いと CLI が終わってから約0.1秒で消えていました(送信に失敗してすぐ終わったものと見ています)。テレメトリを止めても止めなくても CLI 本体は144msで、待たされることはありません。

正直なところ、70秒は予想していませんでした。終了コードは0で結果も正しいので、エラーとしては表に出ません。理由は npm のログにそのまま残っていました。

# npx -y modern-web-guidance@latest search ...(ネットなし・rc=0・70,675ms)の npm のログ
http fetch GET https://registry.npmjs.org/modern-web-guidance attempt 1 failed with EAI_AGAIN
http fetch GET https://registry.npmjs.org/modern-web-guidance attempt 2 failed with EAI_AGAIN
http fetch GET https://registry.npmjs.org/modern-web-guidance attempt 3 failed with EAI_AGAIN
http fetch GET 200 https://registry.npmjs.org/modern-web-guidance 70090ms (cache stale)

$ npm config get fetch-retries fetch-retry-mintimeout fetch-retry-maxtimeout fetch-timeout
fetch-retries=2
fetch-retry-mintimeout=10000
fetch-retry-maxtimeout=60000
fetch-timeout=300000

# ここは使い方次第: --offline を付けるか、版を決めてインストールして直接呼べば待たない

npx は @latest を解決するために registry へ3回問い合わせ、3回とも名前解決に失敗してから古いキャッシュで動いていました。70,090ms は再試行の待ち(10秒と60秒)を足した長さにほぼ一致していて、npm の既定の再試行がそのまま乗っていると考えています。版を @1.0.0 と決めても npx は registry を見に行き、同じく約70秒かかりました。

コストに直すとこうです。インストール済みなら1回0.144秒、npx 経由なら70.7秒で、約490倍。エージェントが1つの作業で search と retrieve を1回ずつ npx 経由で呼ぶとすると、ネットの無い環境では待ちだけで約141秒になる計算です(npx 経由で測ったのは search だけで、retrieve も同じだけ待つと仮定した掛け算です)。名前解決は失敗せず、通信だけが遮断で落とされる環境では、また違う待ち方になるかもしれません。そこは確かめていません。

毎回 npx で最新を取るのは、鮮度の管理を配布元に任せるやり方です。版を決めてインストールするのは、鮮度の管理を自分で持つやり方です。どちらが正しいというより、ネットの事情で選ぶものだと考えています。

legacy-scan に古いページを読ませる

最後に、README の3つ目のコマンド legacy-scan です。10年もののお問い合わせページを想定した見本(HTML・JS・CSS の3ファイル)を作り、古い書き方を9種類仕込んで読ませました。

$ modern-web-guidance legacy-scan /work/sample
Modern Web Guidance Analyzer — /work/sample
Found 1 modernization opportunity across 1 guide (scanned 33 guides with deterministic rules; ~20% of the guidance corpus):
Note: Static analysis results are provisional — verify against the Keep/Drop criteria below.

* secure-external-subresources (1 finding)
  ...(Keep when / Drop when の説明は省略)
  - index.html:7
    <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>

# ガイド自体は search で出てくるのに、静的解析の規則は無い
$ modern-web-guidance legacy-scan /work/sample --guide copy-button
Error: Unknown or unsupported analyzer guide ID: copy-button
# performance と full-session-analytics も同じエラー
仕込んだ古い書き方場所legacy-scan
CDN の jQuery を integrity なしで読むindex.html 7行目検出(secure-external-subresources)
div と jQuery の fadeIn / fadeOut で作ったモーダルindex.html / app.js検出なし
モーダル表示中に body の overflow を hidden にするapp.js検出なし
document.execCommand(‘copy’)app.js検出なし
scroll イベントと getBoundingClientRect の自前の遅延読み込みapp.js検出なし
unload での sendBeaconapp.js検出なし
XMLHttpRequestapp.js検出なし
float と clearfix のレイアウトstyle.css検出なし
-webkit- 付きの transform / box-shadow と @importstyle.css検出なし

拾われたのは1件だけでした。とはいえ、これはツールの説明どおりです。出力自身が「33ガイド分の決まった規則でしか見ていない」「結果は暫定」と書いていて、該当しない話題は search で引くよう案内しています。実際、search "copy text to clipboard" で引くと1位に copy-button が、search "send analytics when the user leaves the page" なら full-session-analytics が出てきます。ガイドはあるが、静的解析の規則はまだ無い、という状態です。

数字の細かい話を1つ。list が返すガイドは208件で、33件は約16%です。出力の ~20% はソースに固定で書かれた文言でした。

試してみての所感

検索と取得がネット無しで同じ結果を返すのは本当で、ここは README の言うとおりでした。一方で、README どおりの npx ...@latest は、名前解決ができない環境では1回70秒待ちます。終了コードは0なので、CI のログを見ても「なんだか遅い」としか分からないはずです。

今思えば、テレメトリの中身よりも、この待ち時間のほうが現場では効いてくる気がします。

チームで入れるなら、私は次の3つから始めると考えています。

  • 版を決めてインストールし(npx で一度取得したあとの npm i -g modern-web-guidance@1.0.0 は 650ms でした)、npx ではなく直接呼ぶ。更新が速いツールなので、版を上げる日を決めて回す
  • テレメトリを止めたい環境では DISABLE_TELEMETRY=1 を置く。yes では止まらない
  • 人が直接検索するときは英語の語で引く

legacy-scan は、古いページの棚卸しの網としてはまだ粗いので様子見です。規則が増えてきたら、同じ見本をもう一度読ませてみるつもりです。