nimajafari/lighthouse-skill

Lighthouse

Google Lighthouse を実行して、ウェブ品質を測定し、修正が実際に数値を改善したかを検証します。Lighthouse はURLをパフォーマンス、アクセシビリティ、SEO、ベストプラクティスの観点から監査し、カテゴリごとに0〜100点のスコアと、改善が必要な監査項目と具体的なガイダンスを返します。

このスキルを使うタイミング

このスキルは測定を行います。関連する品質修正スキルは修正を行います。ワークフローは以下のループです:

測定 (このスキル)  →  修正 (パフォーマンス / アクセシビリティ / SEO / ベストプラクティス)  →  再測定

このスキルが必要な場面: ベースラインスコアの取得、改善が必要な具体的な監査項目の発見、パフォーマンス予算の設定、CIでのビルドゲート、変更がメトリクスを改善（または悪化）させたことの証明。改善を推測せずに、測定し、一つずつ変更し、再度測定しましょう。

仕組み

1. 対象URLを選択 — デプロイ済みURL、またはローカルの開発/プレビューサーバー (http://localhost:3000)。
2. Lighthouse を実行 — scripts/run-lighthouse.sh <url> を推奨。複数回実行し、中央値を採用し、コンパクトなJSONを出力します（完全なレポートは巨大でコンテキストを浪費します）。
3. カテゴリスコアと失敗監査項目を読み取る — JSONから取得。
4. 各失敗監査項目を、関連する品質修正スキルを使って修正にマッピング。
5. 再実行し、改善前/後の差分を報告。

インストールと実行 (CLI)

Lighthouse のREADMEに従いグローバルインストールします（Node 22 LTS+が必要）。また、ローカルにインストールされた Chrome/Chromium が必要です:

npm install -g lighthouse
# または: yarn global add lighthouse

lighthouse https://example.com --view    # 基本実行; --view でHTMLレポートを開く

Lighthouse はインストール済みのChromeを自動検出します。特定のバイナリを指定するには CHROME_PATH 環境変数を使用します。

グローバルインストールせずに手軽に試す場合は、npx lighthouse <url> も利用できます（公開CLIバイナリは対応していますが、公式ドキュメントはグローバルインストールのみをカバーしています）。

エージェント用の機械可読実行 (JSONファイル出力、静粛モード、ヘッドレス):

npx lighthouse https://example.com \
  --quiet \
  --chrome-flags="--headless=new" \
  --only-categories=performance,accessibility,seo,best-practices \
  --output=json --output-path=./lh.json

ラッパースクリプト（推奨）

scripts/run-lighthouse.sh はCLIをラップし、N回実行して中央値の実行結果を採用（Lighthouse公式のバリアンス低減ガイダンスに準拠）、カテゴリスコアと失敗監査項目のみのコンパクトなJSONを標準出力に出力します。人間向けのログは標準エラー出力に出力されます。

# 使用方法: run-lighthouse.sh <url> [runs] [categories]
skills/lighthouse/scripts/run-lighthouse.sh https://example.com 3
skills/lighthouse/scripts/run-lighthouse.sh http://localhost:3000 5 performance,accessibility

出力例:

{
  "success": true,
  "url": "https://example.com",
  "runs": 3,
  "lighthouseVersion": "13.x",
  "scores": { "performance": 78, "accessibility": 95, "seo": 92, "best-practices": 96 },
  "failingAudits": [
    { "id": "largest-contentful-paint", "score": 0.4, "displayValue": "4.2 s" },
    { "id": "unused-javascript", "score": 0.3, "displayValue": "Potential savings of 180 KiB" }
  ]
}

主要フラグ

フラグ	目的
`--output=json	html
--output-path=<path>	レポートの出力先
--only-categories=…	performance,accessibility,seo,best-practices に限定
--preset=desktop	デスクトップ設定（デフォルトはモバイル: エミュレートされたミッドレンジ端末 + 低速4G）
--chrome-flags="--headless=new"	ヘッドレス実行（CI/サーバー）
--budget-path=budget.json	パフォーマンス予算（LightWallet）の適用
`--throttling-method=simulate	devtools
--quiet	進捗ログを抑制
--view	実行後にHTMLレポートを開く

JSONの読み取り方

スコアは categories の下で 0–1 の浮動小数点値、監査の詳細は audits の下にあります。

# カテゴリスコア (0–1) → 100倍するとおなじみのスコア
jq '.categories | to_entries | map({(.key): (.value.score)}) | add' lh.json

# Core Web Vitals ラボ値
jq '.audits | {
  LCP: .["largest-contentful-paint"].displayValue,
  CLS: .["cumulative-layout-shift"].displayValue,
  TBT: .["total-blocking-time"].displayValue
}' lh.json

# 改善すべき失敗/機会監査
jq '[.audits[] | select(.score != null and .score < 0.9)
     | {id, score, displayValue}]' lh.json

パフォーマンス予算 (LightWallet)

アセットやタイミングが閾値を超えた場合に実行を失敗させます。このスキルには編集可能な examples/budget.json が同梱されています。構造は以下の通り:

[
  {
    "path": "/*",
    "timings": [
      { "metric": "largest-contentful-paint", "budget": 2500 },
      { "metric": "interactive", "budget": 3800 }
    ],
    "resourceSizes": [
      { "resourceType": "script", "budget": 300 },
      { "resourceType": "stylesheet", "budget": 100 },
      { "resourceType": "image", "budget": 500 },
      { "resourceType": "total", "budget": 1500 }
    ],
    "resourceCounts": [
      { "resourceType": "third-party", "budget": 10 }
    ]
  }
]

lighthouse https://example.com --budget-path=budget.json --output=json --output-path=./lh.json

サイズは KB、タイミングは ms 単位です。予算の結果はJSON内の performance-budget および timing-budget 監査項目に出力されます。

ラボ vs フィールド — 数値を信頼する前に読んでください

Lighthouse はラボツールです。エミュレートされたハードウェア上で、シミュレートされたスロットリングを使用した1回の合成負荷テストです。再現性が高く、リグレッションの検出に優れていますが、実際のユーザー体験を表すものではありません。

• バリアンスは現実です。 1回の実行で±5〜10ポイント変動することがあります。少なくとも3回実行し、中央値を採用してください（ラッパースクリプトはこれを行います）。
• 実際のユーザーデータが必要な場合は、代わりにフィールドソースを使用してください: CrUX、PageSpeed Insights（ラボ＋フィールド両方を表示）、Search ConsoleのCore Web Vitalsレポート、または web-vitals ライブラリをアナリティクスにレポートする方法など。
• INPは1回のLighthouse読み込みでは測定できません — 実際のインタラクションが必要です。Lighthouseは代わりにTotal Blocking Time (TBT) をラボのプロキシとしてレポートします。フィールドのINPを真実の情報源として扱ってください。

Lighthouse v13に関する注意 (Insight Audits)

v13（2025年10月以降）から、LighthouseはパフォーマンスをInsight Auditsに移行しました。いくつかの従来の機会監査IDは統合または削除されました（例: CLS関連監査→cls-culprits-insight、画像監査→image-delivery-insight）。アドバイス自体は変わりません。監査IDとレポートグループが変更されただけです。古いレポートを解析する場合は、矛盾として扱うのではなく、上位互換として扱ってください。CIでLighthouseのバージョンを固定し、アサートする監査IDが安定するようにしてください。

パフォーマンススコアの構成

パフォーマンススコアはラボメトリクスの加重ブレンドです（重みはバージョン間で変動します）。最近のバージョンでは、主要なメトリクスのおおよその重みは以下の通り:

メトリクス	おおよその重み
Total Blocking Time (TBT)	~30%
Largest Contentful Paint (LCP)	~25%
Cumulative Layout Shift (CLS)	~25%
First Contentful Paint (FCP)	~10%
Speed Index (速度指数)	~10%

TBT/LCP/CLSが支配的であるため、これらを修正することでスコアが最も大きく変わります。Lighthouse Scoring Calculator を使用すると、メトリクスの変化が何ポイントに相当するかを正確に確認できます。

CIとプログラムAPI

詳細はリファレンスを参照:

• 継続的インテグレーション — @lhci/cli、lighthouserc.js アサーション、GitHub Actionsワークフロー: references/CI.md
• プログラム (Node) API — chrome-launcher を使用したカスタムフロー、ユーザーフロー、一括実行: references/PROGRAMMATIC-API.md

監査から修正へのマッピング

Lighthouse カテゴリ	修正に使用するスキル
パフォーマンス / Core Web Vitals	パフォーマンスまたはCore Web Vitalsスキル
アクセシビリティ	アクセシビリティ / WCAGスキル
SEO	SEOスキル
ベストプラクティス	セキュリティ / ベストプラクティススキル

このスキルを addyosmani/web-quality-skills と組み合わせて、ループの修正側を担当させてください。

参考リンク

• Lighthouse リポジトリ
• Lighthouse CLI オプション
• パフォーマンス予算 / LightWallet
• Lighthouse CI
• スコアリング
• CI設定 · プログラムAPI