performance-optimization

パフォーマンス最適化

「どの成果物を信頼し、実際のボトルネックはどこにあり、最初に試す価値がある最小限の調整は何か？」が主な問いである場合に、このスキルを使用します。

一般的な React、SQL、キャッシュ、ゲームパフォーマンスのヒントを羅列することが目的ではありません。 目的は、問題を分類し、現在の成果物を一つの調整ブリーフにまとめ、主要なモードを一つ選び、ボトルネックを一つ特定し、効果の高い変更を一つか二つ提案したうえで、変更前後の影響を検証し、残りの作業を適切な担当へ引き継ぐことです。

見慣れない成果物のパケットを扱う前に、references/intake-packets-and-escalations.md を読んでください。 見慣れないパフォーマンスの問題を扱う前に、references/tuning-modes.md を読んでください。 performance-optimization、monitoring-observability、debugging、testing-strategies、code-refactoring、game-performance-profiler のどれが次の作業を担当するか判断する際は、references/handoff-boundaries.md を読んでください。 ベンチマークまたはプロファイリングの計画を書く前に、references/measurement-checklist.md を読んでください。

このスキルを使う場合

• ボトルネックがまだ特定されていない、操作の遅さ、ページ読み込み、ルート遷移、API のホットパス、クエリプラン、メモリ増加、バンドルのリグレッション、フレーム予算に関する問題
• トレース、Lighthouse/CWV レポート、フレームグラフ、クエリプラン、負荷テストの差分、プロファイラーのスクリーンショット、ベンチマークのメモ、ステークホルダー向けダッシュボードとして届くパフォーマンス情報
• CLI／開発ワークフロー、Web／フルスタック、プロダクト／運用、マーケティング／コンテンツのパフォーマンス、またはゲーム関連の振り分けにまたがり、次の担当がまだ不明なパフォーマンスの依頼
• 一般的なパフォーマンスのヒントの羅列ではなく、範囲を限定した調整ブリーフが必要な状況

このスキルを使わない場合

• 主な作業がダッシュボード、アラート、メトリクス、トレース、ログパイプラインの導入である → monitoring-observability を使用します
• 主な作業が、正確性に関するバグの再現、リグレッションの切り分け、または動作が間違っている理由の解明である → debugging を使用します
• 主な作業が、パフォーマンスの根拠なしに行う安全な構造整理、分割、またはコードモッドの計画である → code-refactoring を使用します
• 主な作業が、組織全体のテストレイヤー、マージ／リリースのゲート、またはベンチマークの方針の選定である → testing-strategies を使用します
• ボトルネックが Unity／Unreal／Godot のキャプチャ内に明確に存在し、エンジン固有の解釈が主な作業である → game-performance-profiler を使用します
• ボトルネックがすでに特定されており、次の作業がスタック固有の実装詳細である場合は、調整ブリーフを作成したうえで、実装スキルに引き継ぎます

手順

ステップ 1：問題を整理する

修正を提案する前に、問題を把握するための必要最小限の説明をまとめます。

以下を記録します。

• 対象領域：CLI／開発 | フロントエンド／ページ読み込み | API／サービス | データベース | 非同期処理／容量 | レポート／ダッシュボード | ランタイム／ゲーム | 不明
• 症状：高レイテンシー | 低スループット | メモリ増加 | CPU 飽和 | クエリの遅さ | 大きなバンドル | 低い CWV | フレームの急増 | 不明
• 判断基準：p50／p95／p99 レイテンシー、スループット、バンドルサイズ、メモリ上限、フレーム予算、CWV 指標、またはベンチマークの実行時間
• 環境：ローカル | CI ベンチマーク | ステージング | 本番 | 対象デバイス／ハードウェア | 混在／不明
• リグレッション、慢性的なホットスポット、または漠然とした問題のいずれか

簡単な整理：

Surface: API + database
Symptom: p95 latency jumped from 180ms to 850ms on order search
Decision target: restore p95 < 250ms
Environment: production-like staging
Regression: yes, after filter expansion

Step 2: インテークパケットから始める

references/intake-packets-and-escalations.mdを使用します。

ユーザーが今持っているパケットを選びます。

• ブラウザートレース／DevTools の記録
• Lighthouse、WebPageTest、または CWV のレポート
• APM トレース、フレームグラフ、プロファイラーの出力、またはベンチマークの差分
• EXPLAIN／クエリプラン／スロークエリーの成果物
• プロファイラーのスクリーンショット／統計オーバーレイ／エンジンのキャプチャ
• スプレッドシート、ダッシュボード、レポートの概要、またはまだ使用可能な成果物がない状態

このステップの出力形式：

## Intake Packet
- Current artifact:
- Why it is enough (or not enough):
- Missing context to collect next:

ルール：現在の成果物ですでに次の判断を絞り込める場合は、理想的な測定手順をユーザーに強制しないでください。

Step 3: 主なチューニングモードを1つ選ぶ

references/tuning-modes.mdから主なモードを1つ選びます。

主なモード：

• interaction-and-rendering
• page-load-and-bundle
• api-latency-and-hot-paths
• database-plan-and-data-access
• throughput-and-capacity
• memory-and-allocation
• runtime-frame-budget
• unknown-needs-better-measurement

ルール：主なモードは1つとし、必要であれば副次的なモードを追加します。 考えられる最適化の軸をすべて1つの回答に詰め込まないでください。

Step 4: 修正案を提示する前にボトルネックを明示する

根拠を、ボトルネックを示す1つの文にまとめます。

良いボトルネックの説明：

• 「DB の処理が完了した後、エンドポイントは JSON のシリアライズ処理で CPU バウンドになっています。」
• 「複合インデックスが述語と一致しないため、検索クエリプランで広範なソートとフィルタリングが行われています。」
• 「インタラクションの遅延は、結果パネルで発生する1つの長いタスクとレイアウトスラッシングが主な原因です。」
• 「対象ハードウェアでは、フレームの急増がアセットのストリーミングバーストと一致しています。」
• 「CWV レポートによると、LCP の主な原因は画像ペイロードとレンダリングをブロックするスクリプトのコストであり、サーバーのレイテンシではありません。」

「全体的にパフォーマンスが悪いです」のような曖昧な説明は避けてください。

Step 5: 効果の大きい変更を1つまたは2つ推奨する

明示したボトルネックに直接対処する、信頼できる最小限の変更を優先します。

モード別の候補となる変更：

• interaction-and-rendering：再レンダリングの範囲を縮小する、重要でない処理を後回しにする、レイアウトスラッシングを避ける、負荷の高いリストを仮想化する、メインスレッドの同期処理を削減する
• page-load-and-bundle：ルート／モジュールを分割する、JS を削減する、アセット配信を最適化する、画像を圧縮／リサイズする、サードパーティーのコストを削減する、積極的にキャッシュする
• api-latency-and-hot-paths：ブロッキング処理をなくす、コストの高いレスポンスをキャッシュする、シリアライズのコストを削減する、安全な下流呼び出しを並列化する、負荷の高い変換を事前計算する
• database-plan-and-data-access：クエリの形を修正する、インデックスを追加／調整する、N+1 アクセスをなくす、より早い段階でフィルターを適用する、ページネーション方式を変更する、行の幅を縮小する
• throughput-and-capacity：同時実行数の上限、キュー構成、ワーカープールのサイズ、コネクションプールのサイズ、バッチサイズ、またはキャッシュヒット経路を調整する
• memory-and-allocation：メモリの頻繁な確保と解放を減らす、キャッシュのサイズに上限を設ける、適切な場合はバッファー／オブジェクトを再利用する、バッファーにためずにストリーミングする、ペイロードを縮小する
• runtime-frame-budget：フレームごとの処理を減らす、コストの高いタスクを分散する、描画／オーバードローの負荷を下げる、ストリーミングバーストを後回しにする、コストの高いエフェクトを簡素化する
• unknown-needs-better-measurement：推測せず、考えられる原因を切り分けられる、最も手間のかからない成果物を依頼する

目安：次の一手がより良い根拠の収集である場合を除き、候補となる変更は最大2つまで推奨します。

ステップ 6：トレードオフと適切な案内先を示す

チューニングの提案には、悪化する可能性のある点も必ず含めてください。

例：

• キャッシュによりレイテンシが改善する一方、データの陳腐化やメモリ負荷が増加する可能性があります
• バッチ処理によりスループットが向上する一方、テールレイテンシが悪化する可能性があります
• ページネーションやインデックスの変更により特定のクエリは高速化する一方、書き込みが複雑になる可能性があります
• 遅延読み込みや分割により初期読み込みは改善する一方、その後の操作のレイテンシが増加する可能性があります
• 画像の圧縮やアセットの簡素化により品質が低下したり、コンテンツやデザインの承認が必要になったりする可能性があります

必要に応じて実装を適切な案内先へつないでください：

• コンポーネントや状態管理のアーキテクチャ整理 → react-best-practices、state-management、または design-system
• スキーマ、インデックス、データモデルの再設計 → database-schema-design
• テレメトリーの導入や継続的なアラート設定 → monitoring-observability
• ベンチマークゲートのポリシー → testing-strategies
• エンジン固有のプロファイラーの読み取り → game-performance-profiler
• 正確性を優先した再現や環境の差異 → debugging

ステップ 7：変更前後の影響を検証する

references/measurement-checklist.md を使用してください。

検証パケットには以下を含めてください：

• ベースラインの指標と環境
• 変更した変数
• 比較可能な条件での変更後の指標
• 主なボトルネックが移動したか、解消したか
• 残存するリスク／追加測定

適切な検証概要：

Baseline: p95 search latency 850ms on staging replay dataset
Change: added `(team_id, status, created_at)` index and removed N+1 author lookup
After: p95 230ms, DB time down 68%, CPU flat
Residual risk: cache-miss path still spikes at 400ms for very wide date ranges
Next if needed: cap date window or async export path

出力形式

## Performance Brief
- Surface:
- Symptom:
- Decision target:
- Primary mode:
- Current artifact:

## Bottleneck Hypothesis
- Primary bottleneck:
- Confidence:
- Why:

## Highest-Leverage Changes
1. ...
2. ...

## Tradeoffs / Risks
- ...

## Verification Plan
- Baseline:
- After:
- Guardrail:

## Route-outs
- ...

例

例 1：API と DB のレイテンシ回帰

入力：「フィルターを追加してから、注文検索エンドポイントが急に遅くなりました。EXPLAIN ANALYZE の出力とスロークエリログがあります。」

期待される形式：database-plan-and-data-access として分類し、API を二次的なモードとして扱います。まず一般的なテレメトリーを求めるのではなく、現在あるアーティファクトを使用し、最も負荷の高いクエリまたはシリアライゼーション層を特定します。的を絞った変更を 1〜2 件提案し、変更前後の検証方法を定義します。

例 2：マーケティング／コンテンツのパフォーマンスレポート

入力：「ランディングページの CWV レポートで、LCP と INP のスコアが低いと示されています。Lighthouse のデータとフィールドデータはありますが、プロファイラーのトレースはまだありません。」

期待される形式：page-load-and-bundle として分類し、レポートを実際の受け付け資料として扱います。テレメトリーの不足と、アセットやレンダリングをブロックする要因の可能性を切り分け、次に取るべき範囲を限定した対応を 1〜2 件提案し、追加のトレース収集が有益となる状況を説明します。

例 3：オブザーバビリティ設定への案内

入力：「ユーザーから苦情が出る前に遅いエンドポイントを検知できるよう、ダッシュボード、トレース、アラートが必要です。」

**期待される形式：**主なタスクがすでに最適化であるかのように扱わず、monitoring-observability へ案内します。

例 4：ゲームエンジンのプロファイラースキルへの案内

入力：「Unreal が Steam Deck でカクついており、Insights のキャプチャがあります。解釈を手伝ってもらえますか？」

**期待される形式：**パフォーマンス全般の状況に触れつつ、エンジン固有のキャプチャの解釈は game-performance-profiler へ案内します。

ベストプラクティス

1. ユーザーがすでに持っているアーティファクトを起点にし、それを捨てるのではなくチューニング概要に整理します。
2. まず測定し、その後にチューニングします。
3. 変更を提案する前に、主要なボトルネックを 1 つ特定します。
4. 提案の範囲を限定します。膨大なチェックリストより、効果の大きい対応を 1〜2 件行うほうが有効です。
5. 影響を検証する際は、条件をそろえた環境同士を比較します。
6. 特にキャッシュ、一貫性、メモリ、コンテンツ品質への影響について、トレードオフを明確にします。
7. テレメトリーの設定、デバッグ、リファクタリング、エンジン固有のプロファイラーの読み取りは、すべてを引き受けず、隣接するスキルへ案内します。

References

• Chrome DevTools Performance
• Lighthouse overview
• Core Web Vitals
• PostgreSQL EXPLAIN
• pg_stat_statements
• Flame Graphs
• Unity Profiler
• Unreal Insights
• Godot Profiler