webperf-core-web-vitals

WebPerf：Core Web Vitals

Chrome DevTools でウェブパフォーマンスを測定する JavaScript スニペットです。

スクリプトの実行

1. mcp__chrome-devtools__evaluate_script でスクリプトを実行し、返されたオブジェクトを読み取ります。スクリプトはコンソールに出力しないため、返されたオブジェクトが結果です。結果には、references/schema.md で説明されている script、status、メトリクスデータ（value、rating、details、items、issues）が含まれます。
2. status が "tracking" の場合、スクリプトはページの監視を続けます。操作後、別の mcp__chrome-devtools__evaluate_script 呼び出しで getDataFn に指定された関数を呼び出します。たとえば、getINP() を呼び出し、返されたオブジェクトを読み取ります。
3. status が "error" または "unsupported" の場合は、error を読み取ります。ページがまだ読み込まれていないか、ブラウザーが API に対応していない可能性があります。

Chrome DevTools MCP を使わない場合は、同じスニペットを webperf-snippets CLI で実行します。この CLI はヘッドレス Chromium でページを読み込み、同じ結果オブジェクトを出力します。コマンドは npx webperf-snippets <url> --snippet <Name> --json です。<Name> は .js を除いたスクリプト名です。Playwright と Chromium が必要です（npm install --save-dev webperf-snippets playwright を実行した後、npx playwright install chromium を実行してください）。トラッキング用スニペットでは、操作を実行するために --interact-script <file> を指定します。

スクリプト

• scripts/CLS.js — 累積レイアウトシフト（CLS）
• scripts/INP.js — 次の描画までのインタラクション（INP）
• scripts/LCP-Image-Entropy.js — LCP 画像のエントロピー
• scripts/LCP-Subparts.js — LCP の内訳
• scripts/LCP-Trail.js — LCP の推移
• scripts/LCP-Video-Candidate.js — LCP の動画候補
• scripts/LCP.js — 最大コンテンツ描画（LCP）

よくあるワークフロー

Core Web Vitals の包括的な監査

ユーザーが Core Web Vitals の包括的な分析または「CWV の監査」を求めた場合：

1. LCP.js - 最大コンテンツ描画を測定します
2. CLS.js - 累積レイアウトシフトを測定します
3. INP.js - 次の描画までのインタラクションを測定します
4. LCP-Subparts.js - LCP のタイミングフェーズを分析します
5. LCP-Trail.js - LCP 候補の推移を追跡します

LCP の詳細調査

LCP が遅い場合、またはユーザーが「LCP をデバッグ」あるいは「LCP が遅い理由」を尋ねた場合：

1. LCP.js - LCP の基準値を測定します
2. LCP-Subparts.js - TTFB、リソースの読み込み、描画遅延に分解します
3. LCP-Trail.js - すべての LCP 候補とその変化を特定します
4. LCP-Image-Entropy.js - LCP 画像に視覚的な複雑さの問題があるか確認します
5. LCP-Video-Candidate.js - LCP が動画（ポスターまたは動画要素）かどうかを検出します

CLS の調査

レイアウトシフトが検出された場合、またはユーザーが「CLS をデバッグ」あるいは「レイアウトシフトの問題」を尋ねた場合：

1. CLS.js - CLS の全体スコアを測定します
2. Layout-Shift-Loading-and-Interaction.js (保留中 — webperf-interaction スキルで利用可能)
3. webperf-loading スキルと照合します：
   • Find-Above-The-Fold-Lazy-Loaded-Images.js（レイアウトシフトの原因となる遅延読み込み画像）
   • Fonts-Preloaded-Loaded-and-used-above-the-fold.js（レイアウトシフトの原因となるフォントの切り替え）

INP のデバッグ

操作の反応が遅い場合、またはユーザーが「INP をデバッグ」あるいは「操作が遅い」と尋ねた場合：

1. INP.js - INP の全体値を測定します。操作後に getINP() を呼び出し、最も遅い 15 件の操作については getINPDetails() を呼び出します
2. Interactions.js (保留中 — webperf-interaction スキルで利用可能)
3. Input-Latency-Breakdown.js (保留中 — webperf-interaction スキルで利用可能)
4. Long-Animation-Frames.js (保留中 — webperf-interaction スキルで利用可能)
5. Long-Animation-Frames-Script-Attribution.js (保留中 — webperf-interaction スキルで利用可能)

動画がLCPの場合の調査

LCP が動画要素の場合（LCP-Video-Candidate.js で検出）：

1. LCP-Video-Candidate.js - 動画を LCP 候補として特定します
2. Video-Element-Audit.js（Media スキル） - 動画の読み込み戦略を監査します
3. LCP-Subparts.js - 動画の読み込みフェーズを分析します
4. webperf-loading スキルと照合します：
   • Resource-Hints-Validation.js（動画のプリロードを確認）
   • Priority-Hints-Audit.js（動画の fetchpriority を確認）

画像がLCPの場合の調査

LCP が画像の場合（最も一般的なケース）：

1. LCP.js - LCP のタイミングを測定します
2. LCP-Subparts.js - タイミングの各フェーズを分析します
3. LCP-Image-Entropy.js - 画像の複雑さを分析します
4. webperf-media スキルと照合します：
   • Image-Element-Audit.js（形式、サイズ、遅延読み込みを確認）
5. webperf-loading スキルと照合します：
   • Find-Above-The-Fold-Lazy-Loaded-Images.js（誤って遅延読み込みされているか確認）
   • Priority-Hints-Audit.js（fetchpriority="high" を確認）
   • Resource-Hints-Validation.js（プリロードを確認）

判断ツリー

結果に基づいて後続のスニペットを自動的に実行するには、この判断ツリーを使用します。

LCP.js の実行後

• LCP > 2.5s の場合 → LCP-Subparts.js を実行し、どのフェーズが遅いか診断します
• LCP > 4.0s（不良）の場合 → LCP の詳細調査ワークフロー全体（5 つのスニペット）を実行します
• LCP 候補が画像の場合 → LCP-Image-Entropy.js と webperf-media:Image-Element-Audit.js を実行します
• LCP 候補が動画の場合 → LCP-Video-Candidate.js と webperf-media:Video-Element-Audit.js を実行します
• 常に実行 → 候補の変化を把握するため、LCP-Trail.js を実行します

LCP-Subparts.js の実行後

• TTFB フェーズ > 600ms の場合 → webperf-loading スキルに切り替え、TTFB-Sub-Parts.js を実行します
• リソース読み込み時間 > 1500ms の場合 → 以下を実行します：
  1. webperf-loading:Resource-Hints-Validation.js（プリロード／プリコネクトを確認）
  2. webperf-loading:Priority-Hints-Audit.js（fetchpriority を確認）
  3. webperf-loading:Find-render-blocking-resources.js（競合するリソースを確認）
• レンダー遅延 > 200ms の場合 → 以下を実行します：
  1. webperf-loading:Find-render-blocking-resources.js（レンダリングをブロックする CSS／JS）
  2. webperf-loading:Script-Loading.js（パーサーをブロックするスクリプト）
  3. webperf-interaction:Long-Animation-Frames.js（メインスレッドのブロック）

LCP-Trail.js の実行後

• LCP 候補の変化が多い（>3）場合 → これは視覚的な不安定さの原因になります。以下を調査します：
  1. webperf-loading:Find-Above-The-Fold-Lazy-Loaded-Images.js（読み込みが遅い画像）
  2. webperf-loading:Fonts-Preloaded-Loaded-and-used-above-the-fold.js（フォントの切り替わり）
  3. CLS.js（LCP の変化につながるレイアウトシフト）
• 最終的な LCP 候補が遅れて表示される場合 → webperf-loading:Resource-Hints-Validation.js を実行します
• 初期の候補が置き換えられた場合 → 初期コンテンツが下に押し下げられた理由（おそらく CLS の問題）を確認します

LCP-Image-Entropy.js の実行後

• エントロピーが非常に高い場合 → 画像は視覚的に複雑です。以下を推奨します：
  • 最新の形式（WebP、AVIF）
  • 適切な圧縮
  • プレースホルダー戦略の検討
• エントロピーが低い場合 → 画像が過剰に最適化されているか、プレースホルダーのように見える可能性があります
• ファイルサイズが大きいと検出された場合 → 形式とサイズを分析するため、webperf-media:Image-Element-Audit.js を実行します

LCP-Video-Candidate.js の実行後

• 動画が LCP の場合 → 以下を実行します：
  1. webperf-media:Video-Element-Audit.js（ポスター、プリロード、形式を確認）
  2. webperf-loading:Priority-Hints-Audit.js（ポスターの fetchpriority を確認）
  3. LCP-Subparts.js（動画の読み込みフェーズを分析）
• ポスター画像が LCP の場合 → 画像の LCP として扱います（画像のワークフローを実行）

CLS の後

• CLS > 0.1 の場合 → webperf-interaction:Layout-Shift-Loading-and-Interaction.js を実行します（保留中 — webperf-interaction スキルで利用可能です）
• CLS > 0.25（不良）の場合 → 包括的なレイアウトシフト調査を実行します：
  1. webperf-loading:Find-Above-The-Fold-Lazy-Loaded-Images.js（寸法が指定されていない画像）
  2. webperf-loading:Fonts-Preloaded-Loaded-and-used-above-the-fold.js（フォントの読み込み戦略）
  3. webperf-loading:Critical-CSS-Detection.js（遅れて読み込まれるスタイル）
  4. webperf-media:Image-Element-Audit.js（width/height の指定漏れ）
• CLS = 0 の場合 → 複数回ページを読み込んで確認します（タイミングに依存している可能性があります）

INP.js の後

• INP > 200ms の場合 → 遅いインタラクションを特定するために webperf-interaction:Interactions.js を実行します
• INP > 500ms（不良）の場合 → INP の完全なデバッグワークフローを実行します：
  1. webperf-interaction:Interactions.js（すべてのインタラクションを一覧表示）
  2. webperf-interaction:Input-Latency-Breakdown.js（フェーズごとの内訳）
  3. webperf-interaction:Long-Animation-Frames.js（処理をブロックしているフレーム）
  4. webperf-interaction:Long-Animation-Frames-Script-Attribution.js（原因となるスクリプト）
• 特定の種類のインタラクション（例：キーボード）が遅い場合 → その種類のインタラクションに絞って分析します
• INP データの収集後 → 最も遅いものから順に、遅いインタラクションの上位 15 件について getINPDetails() を呼び出します（複数の遅いインタラクションに共通するパターンの特定に役立ちます）

エラーからの復旧

• いずれかのスクリプトが status: "error" を返した場合 → ページの読み込みが完了しているか確認します：
  • 読み込みの初期段階の場合：待ってからスクリプトを再実行します
  • ページが SPA の場合：ユーザーが最初に対象のルートへ移動する必要がある場合があります
• LCP.js / LCP-Subparts.js が status: "error" を返した場合 → ユーザーに次のように伝えます：「LCP データはまだ利用できません。ページが完全に読み込まれていることを確認してから、分析を再実行してください。」
• INP.js の getINP() が status: "error" を返した場合 → getDataFn: "getINP" フィールドは、ユーザーの操作後にエージェントが再試行できることを示します。クリック、入力、またはスクロールするようユーザーに促してから、再度 getINP() を呼び出します。

スキル間のトリガー

コンテキストフォークに関する注意： このスキルは context: fork で実行されます。以下のスキル間トリガーは、親エージェントへの報告を推奨するものであり、このサブエージェントが直接実行できる呼び出しではありません。スキル間トリガーが発生した場合は、次に実行するスキルとスクリプトをユーザーに伝えてください。(保留中) と記されたスクリプトはまだ利用できないため、スキップして制約について伝えてください。

以下のトリガーでは、他のスキルのスニペットの使用を推奨しています：

LCP から Loading スキルへ

• LCP > 2.5s で、TTFB フェーズが支配的な場合 → webperf-loading スキルを使用します：

  • TTFB.js、TTFB-Sub-Parts.js、Service-Worker-Analysis.js

• LCP の画像が遅延読み込みされている場合 → webperf-loading スキルを使用します：

  • Find-Above-The-Fold-Lazy-Loaded-Images.js

• LCP に fetchpriority が設定されていない場合 → webperf-loading スキルを使用します：

  • Priority-Hints-Audit.js

CLS から Loading スキルへ

• CLS の原因がフォントの場合 → webperf-loading スキルを使用します：

  • Fonts-Preloaded-Loaded-and-used-above-the-fold.js
  • Resource-Hints-Validation.js（フォントのプリロード用）

• CLS の原因が画像の場合 → webperf-media スキルを使用します：

  • Image-Element-Audit.js（width/height 属性を確認）

INP から Interaction スキルへ

• INP > 200ms の場合 → 完全なデバッグを行うために webperf-interaction スキルを使用します：
  • Interactions.js、Input-Latency-Breakdown.js
  • Long-Animation-Frames.js、Long-Animation-Frames-Script-Attribution.js
  • LongTask.js（インタラクション前のブロックが疑われる場合）

LCP/INP から Interaction スキルへ

• レンダリング遅延またはインタラクション遅延が大きい場合 → webperf-interaction スキルを使用します：
  • Long-Animation-Frames.js（メインスレッドのブロック）
  • LongTask.js（レンダリングを遅らせる長時間タスク）

複数指標の相関

複数の CWV 指標が不良な場合は、調査の優先順位を付けます。

• LCP > 2.5s AND CLS > 0.1 の場合 → 共通の根本原因が考えられます。

  1. LCP 要素を押し下げる、遅れて読み込まれるコンテンツがないか確認します
  2. LCP-Trail.js を実行し、LCP 候補の変化を確認します
  3. Layout-Shift-Loading-and-Interaction.js を実行し、タイミングの相関を確認します

• LCP > 2.5s AND INP > 200ms の場合 → メインスレッドの混雑が考えられます。

  1. Long-Animation-Frames.js を実行します
  2. webperf-loading:Script-Loading.js を実行します
  3. webperf-loading:JS-Execution-Time-Breakdown.js を実行します

• CLS > 0.1 AND INP > 200ms の場合 → レイアウトスラッシング、またはインタラクションによって引き起こされるシフトが考えられます。

  1. Layout-Shift-Loading-and-Interaction.js を実行します
  2. Interactions.js を実行します
  3. インタラクション中またはその後にシフトが発生していないか確認します

参考資料

• references/snippets.md — 各スクリプトの説明としきい値
• references/schema.md — スクリプト出力の解釈に使用する戻り値のスキーマ