Bottleneck Lens
ボトルネックを見つけて、改善を証明する。
デフォルトでは収集データをローカルに保持し、ソース、トレース、レポートをアップロードしないこと。このポータブルな手順とバンドルされたスクリプトは、特定のエージェントベンダーを必要としません。バンドルされたパスは、この SKILL.md からの相対パスで解決すること。CLI は Python 3.10+ を必要とします。ターゲットアダプターは Python 3.10+ および Node.js 22+ をサポートします。Node はベンチマーク/CPU モードをサポートし、Python はアロケーションプロファイリングもサポートします。
ワークロードを発見し合意する
プロジェクトの説明、マニフェスト、ロックファイル、エントリーポイント、既存のパフォーマンス/正確性テストを、プロジェクトモジュールをインポートしたりセットアップフックを実行したりせずに読み取ること。言語、フレームワーク、インタプリタ、依存関係、実際に遅い処理を特定する。Python または Node アダプターと、既存のプロジェクトランタイムを選択する。他の言語の場合は、コレクターの境界を説明し、バンドルされたアダプターがそれをサポートしているふりをするのではなく、適切なプロファイラーを提案すること。
安定したデータセット、シード、同時実行数、キャッシュポリシー、期待される出力を持つ、代表的で範囲を限定したワークロードを選択すること。信頼できる既存のベンチマーク、または結果をアサートする小さなレビュー済みのドライバーを優先すること。テストコレクションとアプリケーションのインポートもコードを実行すること。実行可能なワークロードが利用できない場合は、仮説と収集計画を提供し、決して測定値を捏造しないこと。
馴染みのないリポジトリを実行する前に、正確なインタプリタ、作業ディレクトリ、コマンドと引数、呼び出し回数、タイムアウト、出力パス、およびデータベース/ネットワーク/ファイルへの影響の可能性を示すこと。その具体的なワークロードについて、会話ですでにカバーされていない場合は、承認を得ること。検査またはプロファイリングの許可は、アプリケーションコードを変更する許可ではない。ユーザーが最適化をすでに承認していない限り、変更前に確認すること。すでに承認された変更されていないスコープについては、再度確認しないこと。依存関係のインストール、プロセスへのアタッチ、本番環境へのアクセスには、それぞれ個別の承認が必要である。
コレクターはユーザーの権限でコードを実行する。サブプロセスの分離とタイムアウトはセキュリティサンドボックスではない。必要に応じてフィクスチャまたはテストデータベースを使用すること。ワークロード ID やコマンドライン引数に資格情報を渡さないこと。引数とパスはローカルに記録される。レポートは内部パスを明らかにする可能性がある。未知のコマンドを、何をするのかを知るためだけに実行しないこと。
エビデンスを収集する
コマンド、メトリクス定義、統計的判断、終了コードについては、references/measurement.md を参照すること。共有のバージョン 2 形式は references/measurement.schema.json で定義されている。承認されたワークロードに対してのみ、バンドルされたコレクターを実行すること。古いアドホックなアーティファクトを再収集するよりも、欠落しているメトリクスの境界を推測しないこと。
- まず、計装なしのベンチマーク を収集すること。すべてのサンプル、環境メタデータ、ワークロード ID、コードリビジョンを保存すること。各サンプルは新しいプロセスを使用する。破棄されるウォームアップも新しいプロセスであり、後続のプロセスでアプリケーションの状態をウォームアップすることはない。
- CPU プロファイルと、Python の場合はアロケーションプロファイルを 個別の呼び出し で収集すること。これらのタイミングは診断用であり、ベンチマークのタイミングの代わりにはならない。Node CPU モードは V8 プロファイルとイベントループ診断を保持する。サンプルヒットは呼び出し回数ではなく、V8 プロファイルにはコレクターの起動が含まれる。デフォルトのベンチマークとアロケーション収集は、それぞれワークロードを 8 回（ウォームアップ 1 回、記録された実行 7 回）実行する。CPU プロファイルはウォームアップなしで 1 回の呼び出しを追加する。これらの回数を承認された計画に含めること。
- 編集する前にベースラインを保持すること。新しい出力名を使用すること。スクリプトはアーティファクトの上書きを拒否する。耐久性のある結果ディレクトリを選択し、各 JSON を隣接するアーティファクトディレクトリとともに保持すること。データセット ID、
--inputファイルのハッシュ、シード、リビジョン、関連する--sourceファイル、キャッシュポリシーを記録すること。記録されたシードはアプリケーションコードをシードしない。自動メタデータは実際のキャッシュ状態や指定されていない入力を確立できない。 - 意味がある場合は、独立してレビューされた既知の回答とともに
--expected-stdoutを使用すること。ウォームアップを含むすべての呼び出しがチェックされる。そのオラクルがない場合、自動比較は正しさを評価しない。プロジェクトのテストを個別に実行し、報告すること。出力の狭い範囲での等価性は、すべてのアプリケーションの不変条件をカバーするわけではない。 - Python API またはワーカーには、有限のドライバーを優先すること。バンドルされたツールは、HTTP ロードジェネレーター、ライブプロセスサンプラー、スレッド全体の CPU プロファイラー、またはプロセッツリーモニターではない。I/O バイト数、クエリ数、リクエストパーセンタイル、スループットを直接測定しない。必要な場合は、ユーザーと追加の計装を選択し、その範囲とオーバーヘッドを記録すること。
診断し提案する
各発見について、アーティファクト、関数/ファイル/行、呼び出し回数またはアロケーションサイズ、関連するセルフ/累積時間を引用すること。観測された事実、仮説、提案された変更 を区別すること。累積時間はコールツリー全体で重複する。決してそれらを合計して全体の時間のパーセンテージにしないこと。累積時間が大きいことは高コストなパスを特定するが、必ずしも書き換えるべき関数ではない。
CPU 時間が wall time を下回ることは待機を示唆する可能性があるが、ディスク、データベース、ネットワークの因果関係を証明するものではない。関数の繰り返し呼び出しは N+1 クエリの証明ではない。クエリカウント/スパンを取得し、ループを検査すること。アロケーションスナップショットはスナップショット時点でのライブアロケーションを説明するものであり、すべての一時的なアロケーションやリークを説明するものではない。疑わしいリークは、繰り返しワークロードと保持エビデンスを用いて確認すること。未知のものは明示的に述べること。
変更は、測定された貢献度、推定される利点、実装コスト、正しさのリスク、リソースのトレードオフによって優先順位付けすること。必要に応じて、キャッシュの無効化、順序付け、トランザクション、同時実行性、メモリへの影響を説明すること。測定する前に、改善率を約束しないこと。
承認範囲内で最適化し検証する
最小限の承認された変更を行い、関連のない作業は保持すること。関連する正確性テストを実行し、同じフィクスチャ上で出力/不変条件を比較すること。プロセスが正常終了しただけでは正確性の検証にはならない。
同じ環境、ワークロード、シード、キャッシュポリシー、実行回数、タイムアウトで、同じベンチマークと影響を受けるプロファイル を繰り返すこと。rerun は、記録されたリクエストで現在のコードを実行し、入力ハッシュをチェックする。履歴リビジョンを復元しない。計装なしのタイミングは計装なしのタイミングと、同じ種類のメモリメトリクスは同じ種類のメモリメトリクスと比較すること。共通の JSON は、異なるプロセス/スレッドスコープまたはランタイムタイミング間隔を交換可能にしない。依存関係/インタプリタ/ワークロードが変更された場合は、非互換性チェックを回避するのではなく、別の実験として報告すること。
バンドルされた比較コマンドを使用して、記述的な中央値/平均値の変化、設定された実用的なしきい値、平均値の差に関する独立サンプル順列検定（比較されたメトリクス間で Holm 補正）を分離すること。しきい値は結果を確認する前に選択すること。デフォルトの 5% が普遍的に意味があるわけではない。範囲の重複は有意性検定ではない。この検定は独立した交換可能なサンプルを前提としている。変動性を検査し、ドリフトによってその前提が無効になる可能性がある場合は、A/B 測定を繰り返すか、交互に行うこと。決定的でない結果は同等性を確立しない。
自動化された verified_improvement ステータスは、測定されたワークロードと一致するパスした出力オラクルに限定され、サポートされている実用的な主要メトリクスの改善を必要とし、他の比較されたメトリクスにおけるサポートされている実用的なリグレッションによってブロックされる。出力チェックに失敗すると exit 3 となり、実行が速くても検証がブロックされる。--fail-on-regression は、サポートされている実用的なリグレッションを exit 1 にする。決定的でない比較でのゼロ終了は改善を認定しない。評価されていない、または失敗した結果を説明の中で宣伝しないこと。代表的な隣接するワークロードが存在し、承認されている場合はそれらを実行すること。リグレッションのカバレッジは、テストされたシナリオについてのみ主張すること。合意された質問に回答した場合、実行が失敗した場合、承認の境界に達した場合、または比較可能な測定値を取得できなかった場合に、実験の拡大を停止すること。
結果を提供する
ユーザーの言語を使用すること。各収集/比較は Markdown レポートと JSON を出力する。生のエビデンスを保持しながら、エージェントの解釈をユーザーの言語で追加すること。何が見つかったか、そのエビデンス、次の実験を先頭に示し、次に以下を含めること。
- スコープ、コマンド、環境/リビジョン、入力、繰り返し回数、測定の境界。
- エビデンスと信頼性を備えた発見。測定されていない提案は分離すること。
- 行われた、または提案された変更、トレードオフ、およびコマンド/結果を含む正確性チェック。
- 比較可能な各メトリクスの改善前後の中央値と平均値、最小/最大、サンプル数、変化率。テストと実用的な決定は平均値を使用する。中央値の変化は記述的である。単位、プロセス/スレッド/起動の境界を含めること。正の変化は値が高いことを意味し、負の変化は低いことを意味する。ゼロのベースラインは未定義としてマークすること。
- ステータス: 測定されたベースライン、決定的でない、観測された改善/リグレッション、または 検証された改善。検証された改善は、比較可能な繰り返し測定とパスした正確性チェックのために予約する。速度の向上とメモリの増加はトレードオフであり、無条件の勝利ではない。
- テストされていないパス、利用できないメトリクス、ノイズ、次のアクション、具体的な記録された再実行コマンド。バンドルされた
scripts/demo.pyの既知の回答デモンストレーションを明確にラベル付けし、それらの数値をアプリケーションの結果として決して再利用しないこと。
Markdown/JSON ファイルはポータブルなベースラインである。エージェントは、利用可能なプレゼンテーションツールを使用してチャートを追加してもよい。このワークフローを完了するために、ホストされたダッシュボード、外部 AI エンドポイント、プロプライエタリなコネクタ、またはオプションのチャートツールに依存しないこと。