complexity-optimizer

Complexity Optimizer

コードベース内のアルゴリズム上の複雑性が高い箇所を見つけ、構造化されたレポートを作成します。必要に応じて、明示的な同意を得た後、リスクの低い最適化を実装します。

適用する場面

次のような依頼があった場合に、このスキルを使用します。

• コードベースのパフォーマンス上のボトルネックやアルゴリズムの複雑性を分析、監査、スキャン、レビューする
• 非効率なループ、ネストされた反復、N+1 クエリ、ループ内のソート、レンダリングパスでの再計算を見つける
• 複雑性を下げる（例：O(n^2) → O(n log n) または O(n)）
• コードベースの複雑性プロファイルについて「レポートを作成する」

次の用途には、このスキルを使用しないでください。

• 実行頻度の低いコードパスのマイクロ最適化
• メモリの調整（このスキルの対象は実行時間の複雑性であり、メモリ割り当てのプロファイルではありません）
• 複雑性と無関係なコードスタイルのリファクタリング

ワークフローの概要

Baseline → Rank → Prove behavior → Optimize (opt-in) → Verify
   ↓           ↓                       ↓
 scanner   prioritize hot          rollback if
 + manual  paths & large I/O       tests regress

ステップ	アクション	ツール	リスク
1	ベースラインを確立する：技術スタック、テストコマンド、ホットパスを検出する	scripts/analyze_complexity.py + 手動調査	読み取り専用
2	影響度に応じて改善候補を順位付けし、アルゴリズム上の改善と定数倍の最適化を分ける	推論	読み取り専用
3	関数／コンポーネントをカバーするテストを探すか追加する	読み取り + テストフレームワーク	読み取り専用
4	最適化を適用する（ユーザーから明示的に依頼された場合のみ）	編集／書き込み	破壊的
5	必要に応じてテスト、リンター、型チェック、ベンチマークを実行し、最適化前後の複雑性を報告する	Bash テストコマンド	読み取り専用

基本ルール

現在の動作を理解し、維持できる場合にのみ最適化してください。正しさが不明確な大規模な書き換えより、テストで裏付けられた小規模で確実な改善を優先してください。

デフォルトの動作

ユーザーがコードベースの分析、スキャン、監査、レビュー、または「レポートを作成する」よう依頼した場合、複雑性に関する完全なレポートを自動的に作成します。レポート項目をユーザーに指定させないでください。

デフォルトのレポート内容（references/report-template.md を参照）：

• 分析対象の範囲と、検出された技術スタック／テストコマンド
• 影響度が高いと見込まれる順に並べた主な所見
• 各所見のファイルと行番号
• 現在の処理パターンと、コストが高くなる可能性がある理由
• 推定される現在の複雑性
• 推奨する変更と、変更後の推定複雑性
• リスクレベル
• 必要なテスト、ベンチマーク、または手動確認
• ユーザーが実装を明示的に依頼した場合を除き、ファイルは変更していないことを明確に記載

ファイルを編集するのは、ユーザーが明示的な編集を意味する動詞（implement、fix、optimize、apply、change、refactor）を使った場合に限ります。分析のみ、またはレポートのみの依頼では、ファイルを変更しないでください。

ワークフローの詳細

1. ベースライン

• 言語、フレームワーク、テストコマンド、ビルドコマンド、パフォーマンスに影響するパスを特定します。
• コードに手を加える前に、既存のテストを確認します。
• リポジトリをスキャンする際は、最初のホットスポット一覧を得るために python3 scripts/analyze_complexity.py <repo> を実行します。

2. 順位付け

• ホットパス、大規模入力のパス、レンダリングループ、データベース／API のループ、共有ユーティリティを優先します。
• アルゴリズム上の複雑性と、定数倍の最適化を分けます。
• スキャナーの出力は手掛かりとして扱い、証拠とはみなしません。
• レポートのみの依頼でも、現在および提案後の複雑性を見積もるのに十分な範囲で周辺コードを調査します。スキャナーの生の出力だけで終わらせないでください。

3. 動作を検証する

• 変更対象の関数／コンポーネントに対する、焦点を絞ったテストを探すか追加します。
• 空の入力、重複、順序の安定性、null／欠損値、エラー、権限、ページネーション、タイムゾーン、ミューテーションの副作用などのエッジケースを確認します。
• テストがなく、動作が曖昧な場合は、可能な限り小さなリファクタリングにとどめるか、セマンティクスを変更する前に期待される動作を確認してください。

4. 最適化する（明示的に依頼された場合のみ）

• キーの等価性が安定している場合は、繰り返し行われる線形検索をマップ／セットに置き換えます。
• データの形状が適している場合に限り、ネストした走査をインデックス化、グループ化、ツーポインター走査、スイープライン方式、二分探索、メモ化、バッチ処理、または事前計算に置き換えます。
• UI コードでは、安定した props、メモ化した派生データ、仮想化、デバウンス処理、レンダリングパス外への高コスト処理の移動によって、不要な再レンダリングを減らします。
• データアクセスコードでは、認可とフィルタリングを維持しながら、一括取得、結合、事前読み込み、キャッシュ、またはバッチ処理によって N+1 問題を解消します。

5. 検証する

• 関連するテストと型チェック／Lint／ビルドコマンドを実行します。
• 計算量の改善が明白でない場合や、パフォーマンスが重要な場合は、マイクロベンチマークまたは計測を追加します。
• 元の計算量、新しい計算量、変更したファイル、実行したテスト、残るリスクを報告します。

初回スキャナー

python3 scripts/analyze_complexity.py /path/to/repo --format markdown
python3 scripts/analyze_complexity.py /path/to/repo --format json
python3 scripts/analyze_complexity.py /path/to/repo --changed-only --base origin/main

--changed-only を指定すると、スキャン対象を --base（既定値は HEAD~1）との差分があるファイルに限定します。PR に焦点を当てた計算量レビューに使用してください。

言語ごとの解析精度：

• Python（.py）— AST ベースの解析です。精度が高く、ネストしたループ、ループ内のソート／メンバーシップ判定、ループ内のクエリ／I/O を、Python の ast モジュールを使って関数ごとに追跡します。
• その他の対応言語（.js、.ts、.jsx、.tsx、.java、.go、.rb、.php、.cs、.c、.cpp、.swift、.vue、.svelte、.kt、.rs、.dart、.scala）— インデントと関数境界のヒューリスティックを使った、正規表現ベースのパターンマッチングです。検出結果は手掛かりとして扱い、修正を提案する前に周辺コードを読んで確認してください。

スキャナーが何も報告しなくても、既知のホットパスは手動で確認してください。レンダリングの過剰な発生、データベースクエリのパターン、フレームワークのライフサイクルに関する問題は、リポジトリ固有のコンテキストがなければ判断できないことがよくあります。

終了コード： 0 = スキャン成功、2 = 入力不正（存在しないパス／ディレクトリではなくファイルが指定された／Git エラー）、3 = 一致するファイルがゼロ、130 = 中断。

報告前のトリアージ： 修正を提案する前に、references/false-positives.md を参照して、既知のノイズパターン（単一呼び出しの述語、Redux セレクター、SQL ビルダーのメソッドチェーン、小規模な静的配列からのレンダリング時派生処理）を除外してください。

スキャナーのテスト： python3 scripts/test_analyze_complexity.py を実行すると、誤検出の修正を検証する 13 件の回帰テストが実行されます。スキャナーを変更した後に実行してください。

最適化の安全性チェックリスト

編集する前に：

• 計算量が問題になるほどデータサイズが大きいことを確認します。
• 呼び出し元が依存している可能性のある出力順序が、最適化後も維持されることを確認します。
• オブジェクトの同一性、可変性、参照の共有が公開動作の一部ではないことを確認します。
• キャッシュに有効な無効化戦略があることを確認します。
• 重複排除によって、表示ラベルが同じ別々のレコードが統合されないことを確認します。
• データベースのバッチ処理でも、テナント、権限、論理削除、ページネーション、ソートの制約が維持されることを確認します。

編集した後に：

• まず関連範囲を絞ったテストを実行し、その後、より広範なビルド／Lint／型チェックを実行します。
• ベンチマークが存在する場合、または追加した場合は、変更前後の数値を比較します。
• パッチは局所的な範囲にとどめ、無関係なファイルのフォーマット変更を避けます。

ロールバック

最適化によってテストが失敗したり、観測可能な動作が変わったりした場合：

1. 変更したファイルをすぐに元に戻します：

   git restore <file>           # restore a single file
   git restore -SW <file>       # restore both index and working tree
   

   複数のファイルを変更した場合は、git restore -SW . を実行します（影響を受けたディレクトリ内でのみ）。

2. 失敗したテストを再実行し、復元を確認します。

3. 次の内容をユーザーに伝えて失敗を報告します：

   • 失敗したテスト／アサーションの正確な内容
   • 異なっていた動作（順序、変更、キーの等価性など）
   • 別の変換を試すか、元のコードのままにするか

4. 同じ最適化を少し変更して再試行しないでください。変換によって動作が壊れる場合、データの形状がその変換に適していないか、明示されていない不変条件がある可能性があります。再度試す前にコードを読み直してください。

参考資料

• references/optimization-playbook.md — よくある O(n^2) → O(n log n) / O(n) の変換、フレームワーク固有のパターン、「避けるべきこと」。
• references/report-template.md — 最終分析または監査レポートの構成。
• references/false-positives.md — 一見本物に見えるが、実際にはそうではないスキャナーの検出結果の一覧です。修正を推奨する前に確認してください。
• scripts/_sections.md — スキャナーの実行方法、フラグ、終了コード、制限事項。