ln-31-performance-optimizer

パフォーマンス最適化

目標： 実測された問題のみを最適化します。正しさを保ち、実験を分離し、比較可能な証拠により、合意した指標が許容できないリグレッションなしに改善したと示された場合にのみ変更を維持します。

実行上の取り決め： 順序付けられたチェックボックスが完了の定義です。各項目を内部で PENDING、具体的な証拠がある PROVEN、条件が存在しないことを示す証拠がある CLEARED、または不足がある UNPROVEN として管理します。読むこと、委任すること、ツールの失敗は証明にはなりません。各セクションの後に項目を見直します。返答する前にすべての PENDING を解消し、PROVEN と CLEARED のみを数えます。各不足に対して、このスキルの判定ルールと承認ルールを適用します。 ユーザーの意図、範囲、既存の承認を維持します。承認済みの作業は続行し、重大な未解決の選択や必要な外部承認がある場合にのみ確認します。重要なリスクに応じて深さを調整しつつ、チェックを黙って省略しないでください。依存関係と安全性に関する順序を守り、それ以外は各要件に適した検証方法を選択します。

ツールの使い分け

必要な作業	優先するツール	使用する状況	代替手段
リポジトリの状態と安全な編集範囲	Git のステータス、差分、ブランチまたはワークツリーの確認、リポジトリの指示	プロファイリングや編集の前に必ず実施	ユーザーの変更を安全に分離できない場合は停止
ベースラインと最終指標	既存のベンチマーク、負荷テスト、再現可能なコマンド、本番環境に近いリプレイ	指標とワークロードが報告された問題を反映している場合	本番規模をでっち上げず、動作を再現する最小限のローカルベンチマークを作成
ボトルネックの証拠	既存のプロファイラー、トレーシング、クエリ診断、割り当てツール、OS レベルの指標	CPU、メモリ、I/O、ロック、クエリ、ネットワーク、スケジューラーのコストを特定する場合	後片付け計画を伴う、対象を絞った計測
コードパスと影響範囲	言語サーバーまたはホストネイティブのコードインテリジェンス	高負荷のシンボル、呼び出し元、実装、影響を受ける契約を追跡する場合	範囲を絞った検索と、定義および利用箇所の直接確認
正しさとリグレッション	リポジトリで定義されたテスト、ビルド、リント、型チェック、スモークテストのコマンド	維持する各実験の前後	現状の証拠では発生し得る重大なリグレッションを検出できない場合、最小限の対応を選択
ランタイムと依存関係のセマンティクス	インストール済みバージョンに対応する公式ドキュメント、リリースノート、仕様	仮説がオプティマイザー、ランタイム、データベース、フレームワーク、ライブラリの動作に依存する場合	一次情報に基づくウェブ調査。それもできない場合は仮説を UNVERIFIED と記録

見た目の好みを理由に最適化したり、報告された問題とは異なるワークロードをベンチマークしたりしないでください。ユーザーの変更を破棄したり、破壊的な Git reset を使用したり、本番環境に対して制御されていない負荷をかけたりしてはいけません。

証拠に関するルール

• 報告された問題が複数の状況で発生し得る場合は、コールドスタート、ウォーム状態の定常負荷、飽和負荷の挙動を分けて扱います。
• プロファイル上の寄与とエンドツーエンドの影響を別々に評価します。高負荷の関数が改善しても、ユーザーに見える指標が改善するとは限りません。
• プロファイラーの推定値、合成ワークロード、本番環境での観測はそれぞれ別の証拠クラスとして扱い、明示します。
• 正しさ、リソースの安全性、運用の安定性は、二次的な指標ではなく厳守すべき制約です。

チェックリスト

1. 問題を定義し、ワークスペースを保護する

• 編集を始める前に、ユーザーに見える問題、ワークロード、環境、主要な指標、全体目標、実験を継続するために必要な最低限の改善幅、厳守すべき制約を明確にします。
• 測定可能なパフォーマンス上の症状を確認し、原因を誤った結果や可観測性の欠如と区別します。構成、容量、依存関係が実際のボトルネックである場合もありますが、承認された範囲内でのみ修正します。
• リポジトリの指示を読み、Git の状態、ブランチ、未コミットの変更、無視されるアーティファクト、利用可能な分離手段を確認します。
• 変更、ベンチマーク、生成されたアーティファクトが干渉する可能性がある場合は、ユーザーの作業を保護し、安全なブランチまたはワークツリーで実験を分離します。
• 実行単位で管理するリソース台帳を作成し、作成した絶対パス、ワークツリー、プロセス ID、キャッシュ、プロファイル、一時アーティファクトをすべて記録します。既存のリソースをクリーンアップ対象として登録しないでください。
• いかなる最適化でも違反してはならない、正確性、セキュリティ、メモリ、コスト、互換性、運用上の制約を特定します。
• 既存のベンチマーク、プロファイル、パフォーマンステスト、本番環境のトレース、サービスレベル目標、既知の環境変動を確認します。

2. 再現可能なベースラインを確立する

• 観測された問題と同じ種類の指標を使用します。レイテンシ分布、スループット、CPU、メモリ、割り当て、I/O、クエリ数、ロック待ち、またはその他の直接的な測定値が対象です。
• データサイズ、並行数、キャッシュ状態、ウォームアップ、ビルドモードを含め、比較に適した代表性のある決定論的なワークロードを用意します。
• 結論が覆り得る運用条件を網羅します。少なくとも報告されたケースに加え、関連するデータサイズまたは並行数の境界を含めます。根拠のない合成的な規模は持ち込まないでください。
• 重大なノイズを評価できるだけの、上限を定めた比較予算を設定します。生の結果、適切な代表値またはパーセンタイル、ばらつき、失敗、環境を記録します。改善が見えるまで測定を繰り返すのではなく、結論が出ない測定結果はそのまま報告します。
• ドリフトやノイズが大きい場合は、ベースラインと候補の実行を交互にするかランダム化し、「変更前」の測定をまとめてから「変更後」の測定をまとめる方法よりも、対応のある比較を優先します。
• 実用上可能であれば、意図的に遅くしたパスや明らかに変更したパスを使って、ベンチマークがその違いを検出できることを確認します。動作の変化に反応しないベンチマークでは、最適化を検証できません。
• 編集前に関連する正確性テストを実行し、既存の失敗が実験によるものと誤認されないようにします。
• 問題を再現できず、安全な代替指標を定義できる信頼性の高い本番環境の証拠もない場合は、作業を中止して BLOCKED と報告します。

3. プロファイルを実施して仮説を立てる

• 関数、クエリ、メモリ割り当て、ロック、ネットワーク呼び出しに注目する前に、エンドツーエンドの処理経路をプロファイルします。
• 測定した寄与度、呼び出し頻度、取得可能な場合は包括コストと排他的コスト、影響を受けるワークロードを含む、優先順位付きのコストマップを作成します。
• 上位のコストを、実装、呼び出し元、データ形状、並行処理モデル、設定、外部依存関係までたどります。
• 根本的なボトルネックと、下流の症状、測定オーバーヘッド、デバッグビルド、コールドスタート、一度限りの初期化を区別します。
• プロファイリングが、コードの調査対象に含まれるサービスやプロセスをまたぐ場合は、トレース／相関 ID を揃えて測定された下流の処理経路を追跡します。アクセス可能な内部サービスを「外部」と呼んで、そのレイテンシの調査を止めないでください。
• プロファイラーやインストルメンテーションによる測定の歪みを見積もり、侵襲的なインストルメンテーションなしで、最終的なエンドツーエンドの結果を確認します。
• 具体的な仮説を裏付ける、または否定できる場合に限り、公式のランタイム、フレームワーク、データベース、依存関係の挙動を調査します。
• 独自のキャッシュ、プール、スケジューラー、シリアライザー、データ構造を提案する前に、既存のプラットフォームと依存関係が備える機能を確認します。
• 順序付けした小規模な仮説群を作成します。それぞれについて、期待するメトリクスの変化、仕組み、影響を受けるファイル、リスク、依存関係、検証方法を記載します。
• 測定可能な仕組みがない仮説、推測に基づく規模を前提とする仮説、個別にロールバックできない仮説は除外します。

4. 原子的な実験を実施し、採用か破棄かを判断する

• リスクのある各仮説を、既存の検証と、起こり得る重大なリグレッションに対応付けます。承認済みのテスト範囲内で KEEP、ADD、UPDATE、MERGE、DELETE、または妥当な NO_TEST を実施し、信頼できる最小限の安全性を示す証拠を作成します。置き換えられたテスト資産を削除し、一時的な特性評価用の検証は、その実施条件が終了した時点で終了します。
• キャッシュ、バッチ処理、並列処理、プーリング、再試行を変更する場合は、高速化された処理経路が損なうおそれのある無効化、順序、冪等性、キャンセル、バックプレッシャー、タイムアウト、リソースの上限を明示的に保護します。
• 1 つの仕組みを検証する、整合性のある最小限の変更を適用します。変更の効果を意図的に分離できない場合に限り、まとめて実施します。
• インストルメンテーションは範囲を限定し、オーバーヘッドを低く抑え、簡単に削除できるようにします。診断出力にシークレットや機密性の高いペイロードを決して残さないでください。
• 編集後に、対象を絞った正確性チェックを実施します。失敗の原因を実験、ベースライン、環境のいずれかに特定します。実験に起因する限定的な不具合は修正して再確認するか、正確性を確立できない場合は実験を破棄します。
• 条件を揃えて、同一のベースラインベンチマークを再実行し、生の結果を保存します。
• 差分を確認し、意図しないクリーンアップ、無関係なリファクタリング、生成物の不要な変更、デバッグフラグ、変更されたベンチマーク入力、隠れた設定変更がないかを調べます。
• 事前に定めた最低改善基準をノイズを超えて満たし、すべての必須制約に合格した場合に限り、KEEP とします。
• 採用基準に達しない、結果が悪化する、安全性に不確実性が生じる場合は、DISCARD として、その実験だけを元に戻します。結果を見た後で基準を下げてはいけません。
• 変更を採用した後は、次の仮説を検証する前に、新しい複合ベースラインを確立します。

5. 停止し、検証し、報告する

• 新たな測定結果が別の仮説を裏付ける場合にのみ続行します。合意した目標に達した場合、改善効果が逓減した場合、安全な選択肢を使い切った場合、または前提条件が不足している場合は停止し、目標に到達したかどうかを明確に報告します。
• ビルド、リンター、型、テスト、スモーク、ベンチマーク、運用に関するエビデンスが、最終的に保持する状態とすべての必須ゲートを網羅していることを確認します。その状態に対する合格済みのエビデンスは再利用し、後続の変更や未解決の失敗によって無効になった場合に限りチェックを再実行します。
• 実行で作成した台帳エントリのみを削除します。絶対パスが承認済みの一時ルート内にあることを確認し、記録された正確なプロセス ID を停止し、変更のある作業ツリーや既存の作業ツリーは保持し、意図的に報告するエビデンス成果物は残します。
• ベンチマークの定義と合格基準が実行中に変わっていないことを確認します。
• 仮説台帳と、保持した変更および生の結果（破棄した実験を含む）を照合します。
• 保持した変更のうち少なくとも 1 つが、すべての制約を満たしつつ、合意した指標をノイズの範囲を超えて改善した場合にのみ IMPROVED を使用します。すべての実験を破棄してベースラインに戻した場合は NO_CHANGE を使用します。安全上の前提条件、再現可能なベースライン、または安全に復元する方法が得られない場合は BLOCKED を使用します。

セルフチェック

• 返答前に照合します。 項目単位のエビデンス、要件の網羅状況、矛盾、対象範囲、判定、該当するクリーンアップを確認します。報告内容または許可された成果物を修正します。有効なエビデンスは再利用し、リポジトリの再スキャンや成功済みコマンドの再実行を自動的に行わないでください。関連する変更、失敗、未解決のエビデンスがある場合にのみチェックを繰り返します。残る不足事項を明示します。

出力仕様

ユーザーの言語で、次の順に報告します。5 つのフィールドをすべて残し、各事実は 1 回だけ記載します。小規模な結果はフィールドごとに 1 行で構いません。空の表は省略し、リンク先の成果物をコピーしないでください。

1. 結果： スキル固有の判定と、エビデンスで裏付けられた成果。
2. 対象範囲： レビュー／変更した範囲、除外事項、ベースライン、重要な前提。
3. エビデンス： 以下のスキル固有項目。事実、推論、未検証の主張を区別します。成果物にリンクし、必要に応じて表を使用します。
4. 検証： チェックと結果、利用できないエビデンス、該当するクリーンアップ／外部状態。
5. 完了状況： Checklist: X/Y complete；Incomplete: None、または各 UNPROVEN 項目の理由、結果への影響、正確な次のアクション；残存リスクと必要な判断。

スキル固有のエビデンス： 対象ワークロード、指標、合格基準、正確性の制約、環境、サンプリング方法と分散の算出方法、比較可能なベースライン／最終分布と差分。すべての仮説、仕組み、KEEP / DISCARD、測定結果、検証を記録します。影響を受けるテストポートフォリオで実施した対応、残存するボトルネック、実行で所有する生サンプル、コマンド、設定、最終差分、クリーンアップのエビデンスを、入手可能な場合はパス／ハッシュとともに含めます。