perf-workflow

パフォーマンス問題分析ワークフロー

強い依存関係：clarifying-question-discipline（厳格な質問規律）とknown-issue-research（既知のパフォーマンスパターンの迅速な検索、§2.1）です。どちらかが見つからない場合は中止し、インストールコマンド（npx skills add FuDesign2008/open-skills -g --skill '*' --yes）を出力してください。

対象範囲

このワークフローでは、パフォーマンスのボトルネックの根本原因を特定します。つまり、誰が、どのような条件下で、どの高コストな処理を発生させたのかを明らかにします。根本原因の確認後は、修正の設計、コードや設定の最適化の実装、および結果の検証に活用できます。 修正のリリース、ロールアウト、または出荷方法は対象外です。それらはプロジェクト自体が決定します。

トリガーの認識

すべてのトリガーは**「性能」から始まるため、簡単に認識して覚えられます。トリガーワード単独で入力するか、「トリガー + コロン + スペース + 説明」**の形式で入力すると、このワークフローまたは対応するステージが開始されます。コロンを使う場合、コロンとスペースは言語に依存せず、中国語または英語の句読点のどちらでも使えます。

• 「性能分析」または「性能分析: xxx」 → ステージ 1（証拠の収集）からこのワークフローを開始
• 「性能证据」または「性能证据: xxx」 → ステージ 1：証拠の収集
• 「性能定位」または「性能定位: xxx」 → ステージ 2：ボトルネックの特定
• 「性能假设」または「性能假设: xxx」 → ステージ 3：根本原因の仮説立て
• 「性能监控」または「性能监控: xxx」 → ステージ 4：監視の構築
• 「性能优化」または「性能优化: xxx」 → ステージ 5：最適化の実装
• 「性能验证」または「性能验证: xxx」 → ステージ 6：検証
• 「性能深入」または「性能深入: xxx」 → ステージ 2（ボトルネックの特定）で分析を続行、または深掘り

ユーザーが「性能问题」（パフォーマンスの問題）、「卡顿」（カクつき／ジャンク）、「很慢」（遅い）などと言った場合も、ステージ 1（証拠の収集）からワークフローを開始できます。 ユーザーがパフォーマンス関連のログやプロファイルを提示し、分析を求めている場合は、ステージ 1（証拠の収集）またはステージ 2（ボトルネックの特定）からワークフローを開始してください。

---

基本原则

「まず問題を特定して処理経路を分解し、次にデータを収集してボトルネックを絞り込み、掘り下げて仮説を導き出し、変数を制御して根本原因を検証し、最適化を定着させてクローズドループを形成します。」（まず問題を特定して処理経路を分解します。次にデータを収集してボトルネックを絞り込み、掘り下げて仮説を導き出し、変数を制御して根本原因を検証し、最適化をクローズドループに定着させます。）

1. データ駆動：結論を出す前にデータを取得してください。先に問題を仮定してから、それを裏付ける証拠を探してはいけません。再現手順や分析可能なデータがない場合は、まずユーザーのデータ収集を支援してください（再現手順、ログ、プロファイル、画面録画など）。
2. トップダウン：ユーザーが認識している全体の処理経路から始め、ミクロな分析より先にマクロな分析を行います。まず、どこが遅いのか（所要時間／ブロック／描画量など）を特定し、その後、誰がどのような条件でそれを引き起こしたのかを追跡します。
3. 単一変数で再現可能：根本原因の仮説は、既存のデータまたは少量の対象を絞った計測で、はい／いいえの判定ができるものでなければなりません。検証時は、一度に変更する変数を1つだけにしてください。結果は再現可能かつ反証可能でなければならず、相関関係を因果関係と見なしてはいけません。
4. 処理経路全体を網羅：局所的なデータだけでなく、問題の発生から終了までの実行経路全体を分析してください。群盲象を評すような落とし穴を避けます。
5. 切り替え可能で本番運用に耐えるモニタリング：パフォーマンスの可観測性は、コードベースに恒久的に組み込まれる適切で本番運用に耐えるモニタリング機能として設計し、切り替え機能（環境変数、設定項目、機能フラグなど）で制御してください。オフの場合は、データを出力もサンプリングもせず、稼働中の製品に影響を与えません。分析が必要になったら切り替えてデータを収集できます。一時的な計測を後付けして、後から削除する必要はありません。
6. 時期尚早な最適化をしない：最適化するのは、データに裏付けられ、ユーザー体験に影響し、しきい値を超えるパフォーマンス上の問題だけです。測定データに基づかず、「いつか起きるかもしれないパフォーマンス問題」に備えた予防的な最適化を行わないでください。不要なコードの複雑さと保守コストが増えるだけです。

• ⚠️ 積極的に質問する：clarifying-question-discipline に従います（1ターンにつき質問は1つ。明確になるまで複数回に分けて確認し、急いで回答せず、まず不明点を明らかにします。依存度が高いため、情報が不足している場合は中止します）。
• 🚩 レッドフラグ：ユーザーに複数の質問や未解決点を一度に提示し、順番に回答させること（厳格なルール違反です）。毎回、最も重要な質問を1つだけ尋ね、回答を得てから次の質問をしてください。

---

ステージの流れ

基本の流れ：証拠 → 特定 → 仮説立案 → モニタリング → 最適化 → 検証。

よくある分岐：

• ステージ1でデータ不足が判明し、モニタリングの構築が必要な場合 → ステージ4（モニタリングの構築）に直接進んで追加し、その後ステージ2に戻ります。
• ステージ2で十分なデータがあり、ボトルネックが明確な場合 → ステージ3を省略し、ステージ4または5に直接進みます。
• ステージ6で仮説が否定された場合 → ステージ2または3に戻って再分析します。
• ステージ6で最適化の効果が不十分と判明した場合 → ステージ3に戻って仮説を立て直すか、ステージ5に戻って最適化を調整します。
• 断続的な問題でステージ1のデータ収集が難しい場合 → 長期モニタリングの構築を優先するため、ステージ4に進みます。問題を再現できたらステージ2に戻ります。

---

ステージ1：証拠を収集する（パフォーマンスの証拠）

目標

説明だけから推測するのではなく、再現可能で分析可能なパフォーマンスデータを取得します。漠然とした「カクつく／遅い」という状態を、定量化された指標とパフォーマンスのベースラインに変え、明確な最適化目標と厳格な上限を定めます。

明確にする情報

• 症状：どの操作が遅延を引き起こしますか（クリック、スクロール、入力、ドラッグ、API リクエストなど）？「遅い」とはどのような状態ですか（カクつき、画面が真っ白になる、スピナーが表示される、応答しなくなるなど）？可能な限り定量化してください（例：特定のエンドポイントの P99 をミリ秒で示す、操作のフレームレートやレイテンシを示す）。また、スコープが際限なく広がらないよう、分析範囲（問題の開始点と終了点）を明確にしてください。
• 利用可能なデータ：既存のログ、パフォーマンス／CPU プロファイル、ネットワークキャプチャ、カスタム計測はありますか？ない場合は、まずデータを「どの環境で、どの方法で」取得できるかを確認してください。
• 再現条件：常に再現しますか、それとも断続的に発生しますか？データ量、同時実行数、デバイスに関する条件はありますか？

一般的なデータソース（シナリオに応じて選択）

シナリオ	候補となるデータソース
フロントエンドのカクつき／メインスレッドのブロッキング	コンソールログ、Chrome のパフォーマンス記録、Long Task／カスタムパフォーマンスモニタリング
過剰なレンダリング／コストの高い再描画	フレームワークのレンダリング統計、React DevTools Profiler、カスタムのコミット／レンダリング計測
API／バックエンドの遅延	ネットワークパネル、サーバー側ログ、APM、トレース
メモリ／リーク	ヒープスナップショット、メモリ推移グラフ

特定の技術スタックに限定せず、プロジェクトで実際に使われている監視機能やツールに応じて選択してください。

出力

• すでに利用可能なデータと、不足しているデータを明確に示してください。
• データが不足している場合：ユーザーに必要な操作と、取得すべきものを指定してください（例：再現手順を示し、指定の切り替え項目をオンにし、問題を再現して、コンソール／プロファイルの出力をエクスポートする）。
• 推奨される出力項目：症状（定量化した指標を含む）、再現条件、分析範囲、現在のパフォーマンスのベースライン、目標値または許容限界です。後で比較できるよう、構造化された「パフォーマンス問題定義シート」にまとめてもかまいません。

---

ステージ 2：ボトルネックの特定（性能定位）

目標

生データから異常（どの処理が、いつ、どれだけの時間やリソースを消費したか）を見つけ、トリガーの連鎖（イベント／コールスタック／データフロー）をたどります。開始点から終了点までの全経路のトポロジーを構築し、時間とリソースの 2 つのデータ軸を使ってボトルネックを初期スクリーニングし、分析範囲を主要なセグメント 1～2 件に絞り込みます。

分析アプローチ（一般）

• 全体チェーンのトポロジー：ユーザー操作から問題の終点までの各セグメントを、実行順（コード実行、システムコール、ネットワーク／ストレージなど）に沿って分解し、抜けや重複のないトポロジーを構成します。各セグメントは、入力と出力が明確で、個別に計測できるようにします。
• 2つの軸での計測：時間軸（各セグメントの所要時間、チェーン全体に占める割合）とリソース軸（CPU／メモリ／I/O／ネットワークなど）の両方を計測します。どちらも省略できません。
• 初期ボトルネックのスクリーニング：時間の割合でセグメントをランク付けし、コストの高いもの（例：割合が20％超）を特定します。リソースの異常（飽和、持続的な上昇、エラー率）からも異常なセグメントを特定します。コストが低く、リソースも正常なセグメントは除外します。リソース使用率70％超は一般的な警告ラインです。このしきい値を超えると、絶対値がそれほど大きく見えなくても、応答時間が非線形に増加する傾向があるため、優先的に調査します。

1. 異常を見つける タイムラインまたは集計統計で、目立つメトリクスを探します。例：

   • しきい値を超える単一のタスク／リクエスト（例：メインスレッドのタスクが50ms超、200ms超）。
   • 単一操作の量が異常に多い（例：1回の更新で膨大な数のノードに触れる、1つのリクエストが膨大なペイロードを返す）。
   • 発生頻度が異常に高い（例：イベントが想定よりはるかに頻繁に発火する）。

2. 場所を特定する 各異常について、以下を特定します。

   • 発生しているレイヤー（フロントエンド／バックエンド／ネットワーク／ストレージ）。
   • 対応するコードまたはモジュール（ファイル、関数、コンポーネント、エンドポイント）。
   • コールスタックまたはイベントチェーン（ユーザー操作やエントリーポイントから、時間またはリソースを消費している箇所まで）。

3. 因果関係のチェーンを構築する 「ユーザー操作 → イベント／リクエスト → ハンドラー関数 → コストの高い操作 → 観測されたメトリクス」のようにつなげ、トリガー条件を特定せずに症状だけを見ることにならないようにします。

作業方法

• テキストログの場合：キーワード、所要時間、エラーコードなどで検索（grep／ripgrepなど）して絞り込み、関連する抜粋やコールスタックを読みます。
• プロファイルの場合：まずタイムラインやフレームグラフ上の「幅の広いバー」または「割合の高い」領域を確認し、次に特定の関数／コンポーネントまで掘り下げます。
• コードの場合：コードを読み、呼び出し関係を検索します。ログのスタック情報と照合し、「どの条件で、誰が誰を呼び出したか」を把握します。

出力

• 異常の概要：遅いもの／量が多いもの／頻度が高いものと、おおよその発生箇所。
• 因果関係のチェーン：「操作 → … → ボトルネック」を1、2文または簡単な図で説明します。
• 検証する仮説（初期の方向性）：考えられる根本原因の方向性を1～3個挙げ、それぞれについて、どの証拠があれば裏付けまたは反証できるかを示します。仮説の精緻化と分類はステージ3（根本原因の仮説）で行います。
• 主要なボトルネックセグメントのリスト：1～2個のセグメントを挙げ、時間の割合またはリソース異常の概要を添えます。

既知のパフォーマンスパターンのクイック検索（任意、停止箇所の特定時に使用）

known-issue-research §2.1 のトリガー条件を満たす場合は、そのスキルを読み込み、§2.1（パフォーマンスパターンのバリエーション）に従います。このワークフロー独自のパターン表とステージのオーケストレーションは、このファイルに記載されたままです。

---

ステージ3：根本原因の仮説（性能に関する仮説）

目標

異常とトリガーチェーンを、検証可能な根本原因の仮説にまとめ、一般的なパフォーマンス問題のパターンに照らして分類し、後続の計測と修正の指針とします。仮説は検証可能かつ反証可能でなければなりません。曖昧な推測は避け、分類には業界の手法も活用できます（以下を参照）。

根本原因の推論に関する参考情報

• USE メソッド（リソース型のボトルネック）：リソースの飽和状態（CPU／メモリ／I/O／ネットワーク）を、使用率、飽和度、エラーの3つの観点で判断します。
• RED メソッド（実行／リクエスト型のボトルネック）：実行ロジックや呼び出しチェーンの問題を、レート、エラー、継続時間の3つの観点で判断します。

以下の「一般的なパターン」表と併せて使用してください。具体的な手順については、ここでは詳述しません。

一般的なパターン（技術に依存しない説明）

パターン	特徴	典型的な誘因
更新範囲が広すぎる	局所的であるべき更新によって、全体または広範囲の再計算／再レンダリングが発生します	粗粒度のイベント（例：「あらゆる変更」）によって広範囲の更新が発生する。細粒度の購読や差分計算が不足している
更新がバッチ処理／集約されていない	1つの操作によって複数の独立した再計算または再レンダリングが発生します	連続する複数の状態更新がバッチ処理されていない。非同期コールバックがそれぞれ独自に更新を発生させる
高頻度のトリガー	高頻度のイベントが発生するたびに、高コストのロジックが実行されます	scroll／resize／mousemove などがスロットリング／デバウンスされていない。フレームやイベントのたびに高負荷な再計算が発生する
バックログが一斉に実行される	メインスレッドがビジー状態になったり、キューが滞留したりすると、遅延した多数のタスクが一斉に実行されます	複数のスロットリング／デバウンスタイマーが同時に発火する。タイマー／マイクロタスクが蓄積する
リソースリーク	メモリ／接続／ハンドルが増え続け、解放されません	接続の閉じ忘れ、キャッシュ／タイマーのクリア漏れ、リスナーの削除漏れ
同期処理によるブロッキング	同期操作によって、メインスレッドまたはクリティカルパスが長時間占有されます	同期 I/O、ロック競合、長時間のトランザクション、高負荷な同期計算
計算の反復／重複	同じ結果がキャッシュされずに繰り返し計算されます	メモ化／キャッシュの不足、N+1 クエリ、シリアライズ／デシリアライズの繰り返し

特定のプロジェクトでは、これは「あるフレームワークの setState」「あるイベントバスの emit」「ある RPC 呼び出し」などとして現れる場合がありますが、抽象的なレベルでは、いずれも上記のカテゴリに分類されます。

出力

• 現時点で最も可能性の高い根本原因の仮説を1～2件提示します。各仮説は検証可能かつ反証可能でなければなりません（例：「全表スキャンかどうか」「この変数の値は何か」を確認して、はい／いいえで判定できること）。「SQL の書き方が悪いためクエリが遅い」のような、検証不可能な記述は避けてください。
• 仮説が複数ある場合は、「ユーザーが体感する影響が最も大きい」かつ「検証コストが最も低い」ものから順位付けし、最上位の仮説を先に検証してください。
• 各仮説の検証方法を提示します。既存のログで確認できるでしょうか。できない場合は、どのパス上のどの箇所に切り替え可能なモニタリングを追加する必要があるでしょうか（ステージ4「モニタリングの構築」を参照）。根本原因が確認できたら、ステージ5「最適化の実装」に進んで変更を加え、ステージ6「検証」で仮説と最適化の効果を確認します。

---

ステージ4：モニタリングの構築（性能監視）

目標

既存のデータで仮説を検証できない場合は、クリティカルパスに切り替え可能で、本番環境で利用できるパフォーマンスの可観測性を追加します。モニタリングのロジックは実際のコードとして組み込み、トグルで有効／無効を切り替えます。オフの場合は稼働中の製品に影響を与えず、オンにすると分析用のパフォーマンスモニタリングが有効になります。

追加のモニタリングが必要な場合

• 既存のログ／プロファイルでは、「何がトリガーしたのか」「どのような条件でトリガーされたのか」「その時点で特定の変数がどのような値だったのか」がわからない。
• 「仮説が正しい場合」と「仮説が正しくない場合」の動作を比較する必要がある（例：あるフラグが true の場合と false の場合の動作）。
• このパスに切り替え可能なパフォーマンスモニタリングがまだなく、設計して組み込む必要がある。

モニタリング設計の原則（一般）

1. トグルで制御する ランタイムトグル（環境変数、設定センター、フィーチャーフラグ、ローカルのデバッグスイッチなど）を使って、有効にするかどうかを制御します。本番環境ではデフォルトでオフにするか、特定のユーザー／セッションに限って有効にします。通常のユーザーに負荷やノイズが発生しないよう、問題を調査するときにオンにします。

2. 一時的ではなく、恒久的にする モニタリングコードは恒久的な機能であり、「検証のために追加して、終わったら削除する」ものではありません。ロジックは長期的に維持し、動作は完全にトグルで制御します。オフの場合は、出力もサンプリングも追加のオーバーヘッドも発生しない（または無視できる程度に抑える）ようにし、オンの場合は、既存のログ／プロファイルと整合する、合意済みの形式で出力またはレポートを生成します。

3. 照合可能にする 安定したタイムスタンプ（例：performance.now() またはサーバー側のナノ秒単位の時刻）と位置を示す識別子を出力し、同じタイムライン上の既存のログ／プロファイルと照合して、因果関係や順序を分析できるようにします。

4. 必要十分な情報にする 各記録には少なくとも、位置を示す識別子、タイムスタンプ、仮説の確認または否定に必要な少数の主要変数（例：実行された分岐、ID、件数、エラーコード）を含めます。可能であれば、分析の一貫性を保つため、プロジェクトで既に使われているパフォーマンスログの形式を再利用します。

モニタリングポイントの選定

• 優先：疑わしい直接のトリガーポイント（例：状態を更新する呼び出し、リクエストを発行する呼び出し、再計算を行う関数のエントリーポイント）。
• 次点：トリガーチェーン上の中間ノード（例：イベントハンドラーやコールバックのエントリーポイント）。呼び出し順序と頻度を確認します。
• その次：コストの高い計算の開始点／終了点。呼び出しごとの所要時間と呼び出し回数を確認します。

出力

• モニタリングポイントの一覧（ファイル名：行番号、または関数／エンドポイント名）、それぞれの目的と推奨するトグル名。
• ユーザーが行う必要のある操作：トグルを有効にする方法、問題を再現する方法、新しいログ／プロファイルを取得して提供する方法。
• 根本原因がすでに確認されている場合、またはステージ6で検証する場合は、ステージ5（最適化の実装）に進み、変更を加えます。

---

ステージ5：最適化の実装（性能最適化）

目標

ステージ3での根本原因の結論（およびステージ4でのモニタリング。仮説をステージ6ですでに検証済みの場合は、その結果も参考にできます）に基づき、ボトルネックを解消または軽減する、コードまたは設定レベルの最適化を実装します。このステージで作成するのは「根本原因を対象とする変更」と変更一覧のみです。複数案の評価や詳細なタスク分解は対象外です。

原則

• 症状ではなく根本原因を修正する：変更は、ステージ3で特定した根本原因のパターン（例：レスポンス範囲の縮小、更新の一括処理、スロットリング／デバウンス）に対応させ、汎用的な最適化にしないでください。
• 比較にはモニタリングを使う：変更が実際に効果を発揮したことを確認するため、ステージ4で用意した切り替え可能なモニタリングを使い、ステージ6で同じ再現シナリオを用いて変更前後を比較することを優先します。
• 制御変数による検証：変更を加える前に、単一変数の実験で根本原因を検証します。各最適化で一度に変更する根本原因のポイントは1つだけにし、ステージ6で効果を単一の変更に帰属できるようにします。
• レイヤーと費用対効果：上位から下位のレイヤー（ビジネスロジック → アプリケーションコード → フレームワーク／依存関係 → システム／ハードウェア）を検討し、上位レイヤーを優先します。「変更コストが低く、効果が大きい」解決策（例：ロジックの簡素化、キャッシュの再利用）を優先します。
• 時間占有率に基づいて優先順位を付ける：時間占有率が最も高い処理区間から最適化します。時間占有率が10％未満の区間は、100倍に高速化しても全体の数値への影響はわずかなので、最適化せず、実際の主要なボトルネックに集中します。
• 安定性：ビジネス上の意味を変えず、機能上のバグを導入せず、新たなパフォーマンス上の副作用を招かないようにします。

出力

• 変更一覧：ファイル、場所（関数／モジュール）、変更の概要。
• 推奨する検証方法：使用する再現シナリオと、監視する指標（Stage 4 のモニタリングに沿ったもの）。これにより、Stage 6 で最適化の効果を検証できます。

---

Stage 6：検証（性能検証）

目標

1. 新しいデータを使って、Stage 3（根本原因の仮説を立てる）で立てた仮説に対するはい／いいえの判定を示します。必要に応じて仮説を修正するか、Stage 2（ボトルネックを特定する）に戻ります。
2. Stage 5（最適化を実装する）が完了している場合は、同じ再現シナリオと Stage 4 のモニタリングデータを使って最適化前後を比較し、最適化が機能したか、指標が目標に達したかを確認します。

検証方法

• 各仮説について、「仮説が正しい場合にログ／プロファイルに何が現れるか」と「誤っている場合に何が現れるか」を明確にします。
• 新しいログで該当するパターンを検索し、「正しい場合」の想定と一致するか確認します。
• タイムスタンプを利用できる場合は、異なるモジュール／レイヤーの計測ポイントを同じタイムライン上に並べ、順序と、同じタスク／リクエスト内で発生したかどうかを確認します。
• 最適化後、同じ再現経路における主要な指標（所要時間、呼び出し回数、レンダリング量など）を最適化前後で比較し、合格基準を示します。
• 効果の検証（Stage 5 が完了している場合）：
  • ベースラインの再テスト：最適化前と同じ再現条件および環境で、全次元の指標を比較します。
  • 機能のリグレッション：通常、エッジケース、ピーク負荷の各シナリオで引き続き正常に動作することを確認します。
  • 副作用の確認：二次的なパフォーマンス問題が発生していないことを確認します（例：キャッシュによって応答時間を最適化した結果、メモリ使用量が増加する）。
  • 可能であれば：実トラフィックを使用した本番環境／カナリアリリースの検証を行い、効果を確認します。

出力

• 各仮説の判定：確認済み／否定／依然として不確か。
• 依然として不確かな場合：不足している情報と、次のステップが、さらにデータを収集するための切り替え可能なモニタリングの追加なのか、別の観点からの再分析なのかを示します。
• 確認済みの場合：誰が、どのような条件下で、何を引き起こしたのかを、1～2 文で根本原因として要約します。これは修正の設計と実装に使います。
• Stage 5（最適化を実装する）が完了している場合：最適化前後の比較結果と、目標を達成したかどうかを報告します。
• フィードバックループを閉じる（任意のフォローアップ）：検証に合格したら、主要な指標を継続的なモニタリングとアラートに組み込むことを検討します。CI/CD がある場合は、リグレッションを防ぐため、パイプラインにパフォーマンスのベースラインまたはゲートを追加することを検討します。また、今回の最適化で得られた指標とベストプラクティスをチームの規約に反映し、継続的な改善につなげます。
• 終了条件：すべての仮説が検証され、主要な指標が目標に達した場合、または残るボトルネックの最適化が費用対効果に見合わない場合（変更コストが効果を大幅に上回る場合）、この最適化ラウンドを終了できます。

---

出力の詳細度（状況に応じて調整）

• 問題が単純でデータが十分な場合：「異常＋因果関係＋根本原因の結論」に要約できます。
• 問題が複雑でモジュールが多数ある場合：必要に応じて主要なログの抜粋やコールスタックの抜粋を添え、各ステージについて簡潔に出力します（収集した内容、主な異常、仮説、モニタリングポイントの一覧、最適化の要点、検証結果と効果に関する結論）。
• 特定の技術スタックを使用する場合は、そのセッション内で自然に取り入れます。この SKILL ファイルに特定のタグやコマンドを固定で記述しないでください。