performance-profiler

パフォーマンスプロファイラー

分析に基づくパフォーマンスレビューです。すべての推奨事項は証拠に基づいています。 6 モードのパイプライン：Analyze、Profile、Cache、Benchmark、Regression、Leak-Patterns。

対象範囲： パフォーマンス分析と推奨事項のみです。プロファイラーの実行、負荷テストの実施、インフラストラクチャの監視、実際のメモリーリーク検出には対応しません。このスキルが提供するのは、測定ではなく、分析に基づくガイダンスです。

標準用語

すべてのモードで、以下の用語を正確に使用してください。

用語	定義
complexity	関数またはコードパスの Big-O によるアルゴリズム分類
hotspot	リソース（時間またはメモリー）を不釣り合いに消費するコード領域
bottleneck	システム全体のスループットを制限する制約
profiler output	cProfile、py-spy、perf などのツールからのテキストデータで、ユーザーが貼り付けたもの
cache strategy	キャッシュレイヤーの削除ポリシー、書き込みポリシー、無効化方法
benchmark skeleton	適切な手法で関数のパフォーマンスを測定するためのコードテンプレート
regression risk	コード変更によってパフォーマンスが低下する可能性。LOW/MEDIUM/HIGH/CRITICAL で評価
anti-pattern	パフォーマンスに悪影響を及ぼすことが知られているコードパターン（N+1、無制限の割り当てなど）
evidence	具体的な根拠：AST 分析、プロファイラーデータ、コードパターンの一致、または外部資料
recommendation	期待される効果とトレードオフを伴う、実行可能な最適化案
flame graph	コールスタックのサンプリングデータを階層的に可視化したもの
wall time	実際の経過時間（I/O 待機を含む）。CPU time（計算のみ）と対比されます

ディスパッチ

$ARGUMENTS	モード
analyze <file/function>	アルゴリズムの計算量分析、Big-O レビュー
profile <data>	テキスト形式のプロファイラー出力（cProfile、py-spy、perf）を解釈
cache <system>	キャッシュ戦略の設計（LRU/LFU/TTL/write-through/write-back）
benchmark <code>	ベンチマークの設計と手法のレビュー
regression <diff>	コード差分に基づくパフォーマンス退行リスクの評価
leak-patterns	一般的なメモリーリークパターンのスキャン（実際の検出ではありません）
空	各モードの例を含むモードメニューを表示

モード 1：Analyze

ファイルまたは関数のアルゴリズム計算量を分析します。

Analyze Step 1：スキャン

計算量推定スクリプトを実行します。

uv run python skills/performance-profiler/scripts/complexity-estimator.py <path>

JSON 出力を解析します。スクリプトが失敗した場合は、AST レベルで手動分析します。

Analyze Step 2：分類

対象範囲内の各関数について：

1. ループのネストの深さ、再帰パターン、データ構造の操作を特定します
2. references/complexity-patterns.md を使用して Big-O 分類に対応付けます
3. ホットスポットリスクを評価します：ネストの深さ * 呼び出し頻度 * データサイズへの感度
4. ホットパス内に O(n^2) 以上の関数があればフラグを立てます

Analyze Step 3：レポート

調査結果を次の表にまとめます。

Function	Estimated Complexity	Evidence	Hotspot Risk	Recommendation

各推奨事項にはトレードオフ分析を含めてください。

モード 2：Profile

ユーザーが貼り付けたテキスト形式のプロファイラー出力を解釈します。

Profile Step 1：解析

ユーザーが提供したデータに対して、プロファイル解析スクリプトを実行します。

uv run python skills/performance-profiler/scripts/profile-parser.py --input <file>

データがインラインの場合は、先に一時ファイルに保存します。JSON 出力を解析します。

Profile Step 2：ホットスポットの特定

解析したデータから：

1. 累積時間で関数を順位付けします（上位 10 件）
2. 呼び出し回数が多く、呼び出しあたりの時間が短い関数（オーバーヘッド候補）を特定します
3. 呼び出し回数が少なく、呼び出しあたりの時間が長い関数（最適化候補）を特定します
4. I/O 待ちと CPU 処理のどちらが中心かを確認します（wall time と CPU time の比率）

Profile Step 3：推奨

各ホットスポットについて、以下を提示します。

• プロファイラーデータの証拠に基づく根本原因の仮説
• 期待される効果の範囲を含む最適化アプローチ
• 最適化のトレードオフとリスク
• references/anti-patterns.md に記載された関連するアンチパターンへの参照

モード 3：Cache

説明されたシステムのキャッシュ戦略を設計します。

キャッシュステップ 1：アクセスパターンを把握する

コードについて質問するか、コードから推測します。

1. 読み取りと書き込みの比率
2. データの鮮度要件（TTL の許容範囲）
3. キャッシュサイズの制約
4. 整合性要件（結果整合性か強整合性か）
5. エビクションの負荷（ワーキングセットとキャッシュ容量の関係）

キャッシュステップ 2：戦略を設計する

references/caching-strategies.md の決定木を使用します。

要因	LRU	LFU	TTL	ライトスルー	ライトバック
読み取りが多く、ワーキングセットが安定	良好	最適	可	--	--
書き込みが多い	--	--	--	安全	高速
厳格な鮮度要件	--	--	最適	最適	リスクあり
メモリ制約あり	最適	良好	可	--	--

キャッシュステップ 3：仕様を提示する

エビクションポリシー、書き込みポリシー、無効化戦略、ウォームアップ方法、監視に関する推奨事項を提示します。容量計画の計算式も含めます。

モード 4：ベンチマーク

ベンチマークとレビューの方法論を設計します。

ベンチマークステップ 1：スケルトンを生成する

ベンチマーク設計スクリプトを実行します。

uv run python skills/performance-profiler/scripts/benchmark-designer.py --function <signature> --language <lang>

JSON 出力を解析し、セットアップコード、ベンチマークコード、反復回数、ウォームアップを確認します。

ベンチマークステップ 2：方法論をレビューする

ベンチマークのベストプラクティスに照らして検証します。

1. JIT／キャッシュを安定させるのに十分なウォームアップ期間がある
2. 統計的有意性を確保できる反復回数である
3. 測定対象からセットアップ／後処理のオーバーヘッドを除外している
4. 環境が制御されており、他のプロセスによる干渉がない
5. 結果に平均値だけでなく、分散／パーセンタイルも含まれている

ベンチマークステップ 3：提示する

方法論に関する注記、予想されるメトリクス、解釈ガイドを添えて、完全なベンチマークコードを提示します。

モード 5：回帰

コード差分によるパフォーマンス回帰のリスクを評価します。

回帰ステップ 1：差分を収集する

パスが指定されている場合は差分を読み取ります。Git の範囲が指定されている場合は git diff を実行します。変更された関数とその呼び出し箇所を特定します。

回帰ステップ 2：リスクを評価する

変更された関数ごとに評価します。

リスク要因	重み	確認項目
複雑さの増加	3x	ループのネストが追加された、アルゴリズムが変更された
ホットパスの変更	3x	リクエスト／レンダリングパスで関数が呼び出される
データ構造の変更	2x	コレクション型またはサイズの前提が変更された
I/O パターンの変更	2x	ネットワーク／ディスク呼び出しが追加された、バッチ処理が削除された
メモリ割り当て	1x	ループ内で新たな割り当てがある、バッファーが大きくなった

リスクスコア = （重み × 深刻度）の合計。LOW／MEDIUM／HIGH／CRITICAL に分類します。

回帰ステップ 3：報告する

次の内容を含む回帰リスクマトリックスを提示します。

• 関数ごとのリスク評価と根拠
• 差分の総合リスクスコア
• マージ前にベンチマークすべき対象の推奨
• 検証すべき具体的な測定項目（プロファイルの対象と箇所）

リークパターン

よくあるメモリーリークパターンをスキャンします。静的解析のみであり、実際のリーク検出ではありません。

リークステップ 1：スキャンする

対象ファイルを読み取り、references/leak-patterns.md のパターンと照合します。

• クリーンアップされないまま蓄積するイベントリスナー
• クロージャーに捕捉された参照によって GC が妨げられる
• 上限なしに増え続けるコレクション（無制限のキャッシュ、追記専用リスト）
• 参照カウント方式の言語における循環参照
• 解放されないリソースハンドル（ファイル、接続、カーソル）
• グローバル状態の蓄積

リークステップ 2：分類する

見つかったリークの可能性があるパターンごとに分類します。

パターン	言語	深刻度	偽陽性のリスク

リークステップ 3：報告する

コードを引用して検出結果を提示し、各パターンがリークのリスクとなる理由を説明して、修正方法を提案します。静的解析では偽陽性率が高いことを明記し、確認には実際のプロファイリングツールを推奨します。

スケーリング戦略

範囲	戦略
単一関数	直接分析し、インラインで報告
単一ファイル（< 500 LOC）	スクリプトを活用して分析し、構造化したレポートを作成
複数ファイル／モジュール	ファイルごとにサブエージェントを並行実行し、レポートを統合
コードベース全体	エントリーポイントとホットパスを優先し、サンプルベースで分析

参照ファイル

一度に読み込む参照ファイルは1つだけにしてください。すべての参照ファイルをコンテキストに事前読み込みしないでください。

ファイル	内容	読み込むタイミング
references/complexity-patterns.md	コードパターンと Big-O の対応関係（例付き）	モード1（分析）
references/caching-strategies.md	キャッシュの判断ツリー、削除ポリシー、トレードオフ	モード3（キャッシュ）
references/anti-patterns.md	パフォーマンスのアンチパターン一覧（N+1、上限のない割り当てなど）	モード2（プロファイル）、モード5（リグレッション）、モード6（リーク）
references/leak-patterns.md	言語別のメモリーリークパターン（Python、JS、Go、Java）	モード6（リークパターン）
references/profiler-guide.md	プロファイラー出力の解釈、フレームグラフの読み方	モード2（プロファイル）
references/benchmark-methodology.md	ベンチマーク設計のベストプラクティス、統計的手法	モード4（ベンチマーク）

スクリプト	実行するタイミング
scripts/complexity-estimator.py	モード1 — AST による静的な計算量分析
scripts/profile-parser.py	モード2 — cProfile/pstats のテキスト出力を JSON に解析
scripts/benchmark-designer.py	モード4 — 関数シグネチャからベンチマークのひな形を生成

テンプレート	レンダリングするタイミング
templates/dashboard.html	いずれかのモードの後 — 結果の JSON をデータタグに挿入

データファイル

ファイル	内容
data/complexity-patterns.json	コードパターンと Big-O の対応関係（機械可読形式）
data/caching-strategies.json	キャッシュの判断ツリー（機械可読形式）
data/anti-patterns.json	パフォーマンスのアンチパターン一覧（機械可読形式）

重要なルール

1. パフォーマンスを測定したと主張しないでください。このスキルが提供するのは分析であり、測定ではありません
2. すべての推奨事項にトレードオフを含めてください。「とにかくXをする」といった助言はしないでください
3. 計算量の推定には常に不確実性があることを明記してください。静的分析には限界があります
4. 早まった最適化は推奨しないでください。まず、対象のコードが実際にホットパス上にあることを確認してください
5. プロファイラー出力の解釈では、一般論ではなく具体的なデータポイントを引用してください
6. キャッシュ戦略の推奨では、無効化の方法を必ず扱ってください。「キャッシュ無効化は難しい」は戦略ではありません
7. ベンチマーク設計には、ウォームアップ、統計的有意性、分散の報告を含めてください
8. リグレッションリスクの評価は、一般的な懸念ではなく、具体的なコード変更を根拠にしてください
9. リークパターンのスキャンはパターンマッチングのみです。確認のため、必ず実際のプロファイリングも推奨してください
10. 一度に読み込む参照ファイルは1つだけにしてください。すべての参照ファイルをコンテキストに事前読み込みしないでください
11. 修正を提案する前に、根拠を示して調査結果を提示してください（承認ゲート）
12. アンチパターンの指摘には、コードの引用 [file:line] が必要です。一般的な警告だけでは不十分です