debug-optimize-lcp について
debug-optimize-lcp は、ウェブページの最大コンテンツ描画(LCP)を分析・改善するスキルです。読み込み性能を調べる開発者向けに、パフォーマンストレースとネットワークリクエストを使って遅延箇所を特定し、変更後に再測定します。
主な機能
- 01ページ読み込みのパフォーマンストレースを記録
- 02LCP の各区間と関連インサイトを分析
- 03LCP 要素の特定とネットワークリクエストの確認
- 04画像・スクリプト・描画の一般的な問題を確認
- 05トレースを再実行し低速な端末やネットワークをエミュレート
活用シーン
- 01画面内の主要コンテンツが遅く表示される原因の特定
- 02遅延がサーバー・リソース読み込み・描画のどこで起きるか判断
- 03最適化後に LCP 各区間の時間を比較
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/ / github.com/ gsmlg-dev/ code-agent --skill debug-optimize-lcpインストール後、Claude Code で/debug-optimize-lcpを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
references/elements-and-size.mdlcp-breakdown.mdlcp-snippets.mdoptimization-strategies.md詳細
LCP とは何か、なぜ重要なのか
Largest Contentful Paint(LCP)は、ページのメインコンテンツが表示されるまでの速さを測定します。ナビゲーションの開始から、ビューポート内に最大の画像またはテキストブロックが描画されるまでの時間です。
- 良好:2.5 秒以下
- 改善が必要:2.5~4.0 秒
- 低速:4.0 秒超
LCP は Core Web Vitals のひとつで、ユーザーエクスペリエンスと検索順位に直接影響します。モバイルページの 73% では、LCP 要素は画像です。
LCP の内訳
各ページの LCP は、間隔や重複のない 4 つの連続したサブパートに分けられます。どのサブパートがボトルネックなのかを理解することが、効果的な最適化の鍵です。
| サブパート | LCP に占める理想的な割合 | 測定対象 |
|---|---|---|
| Time to First Byte(TTFB) | 約 40% | ナビゲーション開始 → 最初の HTML バイトを受信 |
| リソース読み込みの遅延 | 10% 未満 | TTFB → ブラウザーが LCP リソースの読み込みを開始 |
| リソース読み込み時間 | 約 40% | LCP リソースのダウンロードにかかる時間 |
| 要素の描画遅延 | 10% 未満 | LCP リソースのダウンロード完了 → LCP 要素の描画 |
「遅延」に該当するサブパートは、できるだけゼロに近づける必要があります。どちらかの遅延が LCP 全体に対して大きい場合は、まずそこを最適化してください。
よくある落とし穴:ほかのサブパートを確認せずに、ひとつのサブパートだけを最適化すること(たとえば、画像を圧縮して読み込み時間を短縮するなど)。実際のボトルネックが描画遅延であれば、画像を小さくしても効果はありません。短縮した時間が描画遅延に移るだけです。
デバッグのワークフロー
以下の手順を順番に実行してください。各手順は、前の手順を踏まえて進めます。
手順 1:パフォーマンストレースを記録する
ページに移動し、リロードを伴うトレースを記録して、LCP を含むページ全体の読み込みを捕捉します。
navigate_pageで対象の URL に移動します。reload: trueとautoStop: trueを指定してperformance_start_traceを実行します。
トレース結果には、LCP のタイミングと利用可能なインサイトセットが含まれます。出力にあるインサイトセット ID をメモしてください。次の手順で必要になります。
手順 2:LCP のインサイトを分析する
performance_analyze_insight を使って、LCP 固有のインサイトを詳しく調べます。トレース結果から、次のインサイト名を探してください。
- LCPBreakdown — 4 つの LCP サブパートと、それぞれの所要時間を表示します。
- DocumentLatency — TTFB に影響するサーバー応答時間の問題を示します。
- RenderBlocking — LCP 要素の描画を妨げているリソースを示します。
- LCPDiscovery — LCP リソースを早期に発見できたかどうかを示します。
トレース結果にあるインサイトセット ID とインサイト名を指定して、performance_analyze_insight を呼び出します。
手順 3:LCP 要素を特定する
references/lcp-snippets.md にある 「Identify LCP Element」スニペットを指定して evaluate_script を使い、LCP 要素のタグ、リソース URL、生のタイミングデータを確認します。
url フィールドから、ネットワークウォーターフォールで探すリソースがわかります。url が空の場合、LCP 要素はテキストベースです(読み込むリソースはありません)。
手順 4:ネットワークウォーターフォールを確認する
list_network_requests を使って、ほかのリソースに対する LCP リソースの読み込みタイミングを確認します。
resourceTypes: ["Image", "Font"]で絞り込んでlist_network_requestsを呼び出します(手順 3 の結果に応じて調整してください)。- 次に、LCP リソースのリクエスト ID を指定して
get_network_requestを使い、詳細を確認します。
主な確認項目:
- 開始時間:HTML ドキュメントおよび最初のリソースと比較します。LCP リソースの開始が最初のリソースより大幅に遅い場合は、解消すべきリソース読み込みの遅延があります。
- 所要時間:リソースの読み込み時間が長い場合、ファイルが大きすぎるか、サーバーの応答が遅い可能性があります。
手順 5:よくある問題がないか HTML を調べる
references/lcp-snippets.md にある 「Audit Common Issues」スニペットを指定して evaluate_script を使い、ビューポート内の画像が遅延読み込みされていないか、fetchpriority が不足していないか、スクリプトが描画をブロックしていないかを確認します。
最適化戦略
ボトルネックとなっているサブパートを特定したら、優先順位の高い修正を適用します。
1. リソース読み込み遅延を解消する(目標:<10%)
最もよくあるボトルネックです。LCP リソースの読み込みは直ちに開始する必要があります。
- 根本原因:LCP 画像が JS/CSS 経由で読み込まれている、
data-srcを使用している、またはloading="lazy"が設定されている。 - 修正:標準の
<img>とsrcを使用します。LCP 画像を遅延読み込みするのは絶対に避けてください。 - 修正:画像を HTML から検出できない場合は、
<link rel="preload" fetchpriority="high">を追加します。 - 修正:LCP の
<img>タグにfetchpriority="high"を追加します。
2. 要素のレンダリング遅延を解消する(目標:<10%)
読み込み直後に要素がレンダリングされる必要があります。
- 根本原因:大きなスタイルシート、
<head>内の同期スクリプト、またはメインスレッドのブロック。 - 修正:クリティカル CSS をインライン化し、重要度の低い CSS/JS を遅延させます。
- 修正:メインスレッドをブロックする長いタスクを分割します。
- 修正:サーバーサイドレンダリング(SSR)を使用して、初期 HTML に要素が含まれるようにします。
3. リソース読み込み時間を短縮する(目標:約40%)
リソースを小さくするか、より速く配信します。
- 修正:最新のフォーマット(WebP、AVIF)とレスポンシブ画像(
srcset)を使用します。 - 修正:CDN から配信します。
- 修正:
Cache-Controlヘッダーを設定します。 - 修正:ウェブフォントによって LCP のテキスト表示がブロックされている場合は、
font-display: swapを使用します。
4. TTFB を短縮する(目標:約40%)
HTML ドキュメント自体の到着に時間がかかりすぎています。
- 修正:リダイレクトを最小限に抑え、サーバーの応答時間を最適化します。
- 修正:エッジ(CDN)で HTML をキャッシュします。
- 修正:ページが戻る・進むキャッシュ(bfcache)の対象となるようにします。
修正の検証とエミュレーション
- 検証:トレース(
reload: trueを指定したperformance_start_trace)を再実行し、新しいサブパートの内訳を比較します。ボトルネックが縮小しているはずです。 - エミュレーション:ラボでの測定結果は実環境での使用感とは異なります。
emulateを使用して、次の条件下でテストします。networkConditions: "Fast 3G"とcpuThrottlingRate: 4を指定してemulateを実行します。- これにより、低速な接続やデバイスでのみ発生する問題が明らかになります。