wieslawsoltes/Performance-Skill

.NET パフォーマンスエンジニアリング

このスキルは、.NET アプリケーション（ASP.NET Core、サービス、コンソールアプリケーション、Avalonia、WPF、WinUI、MAUI、Skia、WebGPU、ゲーム/グラフィックスエンジン、NativeAOT、ネイティブ相互運用ワークロードを含む）のパフォーマンスを調査、説明、修正、ベンチマーク、検証する際に使用します。

このリポジトリは 1 つのスキルを定義します。SKILL.md はポリシーとルーティングのエントリポイントであり、詳細な操作手順は階層的なリファレンスツリーに格納されています。現在の調査に必要なインデックスと章のみをロードし、証拠が所有権の境界を越えた場合に展開してください。

非妥協ルール

• 最適化されたビルド（通常は Release）を、実際のデプロイ形態でプロファイリングおよびベンチマークします。
• コミットとダーティ状態、SDK/ランタイム、OS、アーキテクチャ、ハードウェア、電源モード、ワークロード、ツールバージョン、環境オーバーライド、正確なコマンドを記録します。
• コードを変更する前に、決定論的な再現を確立します。
• コールドスタートアップ、初回使用、ウォーム定常状態、過負荷、ドレイン、シャットダウンを分離します。
• 階層型コンパイル、シェーダー、パイプライン、キャッシュ、プールをウォームアップします（コールド動作が対象でない場合）。
• すべての関連する所有権境界（マネージドランタイム、ネイティブライブラリ、カーネル、スケジューラ、ファイルシステム/ネットワーク、依存関係、ドライバ、GPU、コンポジター、ディスプレイ）で証拠を収集します。
• RSS のみからマネージドリテンションを推測しないでください。
• 高いフレーム時間、GPU API 使用率、または使用率のみから GPU 飽和を推測しないでください。
• 1 つの平均、1 つのトレース、1 つのフレームキャプチャ、1 つのマイクロベンチマーク、または最速のベンチマーク実行から修正を主張しないでください。
• 生のアーティファクトを保存し、欠落シンボル、ドロップイベント、プロファイラオーバーヘッド、環境変動、不確実性を報告します。
• ダンプ、トレース、ログ、SQL スパン、パケットキャプチャ、ベンチマーク入力コーパス内のシークレットと個人データを保護します。
• コマンド例はバージョンに依存するものとして扱います。まずインストールされているツールのヘルプを照会してください。構文が異なる場合、ヘルプが例よりも優先されます。検証済みの選択ルールと正規形式については、references/command-reference.md を使用してください。¹

必須の調査出力

以下を報告します。

1. 症状 — 観測可能な影響と違反した目標。
2. 再現 — 決定論的なワークロードと環境。
3. 収集 — 正確なツール、コマンド、期間、アーティファクトパス。
4. 証拠 — カウンター、トレース、キャプチャ、ダンプ、ベンチマーク分布、測定値。
5. 所有権 — マネージド CPU、ランタイム、ネイティブ CPU、カーネル、スケジューラ、I/O、依存関係、メモリ、ドライバ、GPU、コンポジター、またはディスプレイ。
6. 支配的原因 — 最も大きなコスト、待機、または最も速く成長するリソース。
7. 修正 — 最小で効果の高いコードまたは設定の変更。
8. バリデーション — 同等のワークロードによる改善前後の実行結果と、分布およびテールメトリクス。
9. 残存リスク — 未解決のボトルネックと測定の限界。

同等のワークロードによる改善前後の証拠なしに、改善を主張しないでください。

リファレンスルーター

常に references/index.md、references/core/index.md、および検証済みの references/command-reference.md から始めてください。

質問に応じて追加のドメインインデックスをロードします。

• マネージド CPU、アロケーション、GC、JIT、例外、ThreadPool、ロック、非同期スタック、ダンプ: references/runtime/index.md
• マネージド/ネイティブ/VM/マップド/GPU メモリ所有権とリーク分析: references/memory/index.md
• 競合、非同期レイテンシ、キュー、バックプレッシャー、ファイル/ネットワーク/データベース I/O、UI ディスパッチャーレイテンシ: references/latency/index.md
• コールドスタート、最初のフレーム/リクエスト、ローダー、JIT、ReadyToRun、トリミング、シングルファイル、NativeAOT: references/startup/index.md
• BenchmarkDotNet、マイクロ/コンポーネント/マクロ/負荷/耐久ベンチマーク、非同期/並行ベンチマーク、JIT/AOT 比較、逆アセンブル、ハードウェアカウンター、統計、CI ゲート: references/benchmarking/index.md
• 実稼働、コンテナ、診断ポート、dotnet-monitor、トリガー収集、Kubernetes、アーティファクトセキュリティ: references/production/index.md
• UI/レンダリング/GPU/WebGPU/Metal/D3D/Vulkan/OpenGL/シェーダー/同期/プレゼンテーション: references/gpu/index.md

references/platforms/index.md を介して、関連するすべてのプラットフォームリファレンスをロードします。シングルホストの調査では通常 1 つのプラットフォームドキュメントが必要です。クロスプラットフォームの比較やリモート/クライアント-サーバーシナリオでは、複数が必要になる場合があります。

デフォルトですべてのドキュメントをロードしないでください。現在の仮説に答える最小限のセットを選択しますが、別のガイドが必要だからといって所有権の境界で止まらないでください。

迅速なトリアージ手順

1. プロダクションと同等の構成でビルドして実行します。
2. ワークロードフェーズ、成功メトリクス、停止ルールを定義します。
3. System.Runtime カウンターとプロセス CPU、合計メモリを記録します。
4. マネージド所有権が妥当な場合、dotnet-trace でマネージド CPU/ランタイムの証拠をキャプチャします。
5. 進行、枯渇、ブロッキングが疑われる場合、繰り返しスタックをキャプチャします。
6. 総コストが説明できない場合、プラットフォームネイティブの CPU/スケジューラ/I/O/メモリトレースを収集します。
7. メモリの場合、マネージドライブバイト、GC コミットメント、プライベート/RSS/PSS、ネイティブアロケーション、マッピング、グラフィックスアロケーション、GPU レジデンシーを比較します。
8. レンダリングの場合、アプリケーションマーカー、CPU サブミッション、GPU タイムスタンプ、ネイティブ GPU キャプチャ、プレゼント、コンポジター、ディスプレイタイミングを関連付けます。
9. ベンチマークリクエストの場合、マイクロ、コンポーネント、マクロ、負荷、耐久のいずれかの方法論を選択してから、BenchmarkDotNet または別のハーネスを選択します。
10. 実稼働のみのインシデントの場合、制限付きまたはトリガー収集を使用し、cgroup/ホスト制約を記録します。
11. 証拠が支配的原因を裏付けた後にのみ実装します。
12. 同一のワークロードを繰り返し、中央値、分布、テール値、および生のアーティファクトを公開します。

所有権テスト

• プロセス CPU が高く、マネージドスタックがホット: アプリケーション/JIT/ランタイムの作業。
• プロセス CPU が高く、P/Invoke 以下: ネイティブライブラリ、アロケーター、グラフィックス API、またはドライバ CPU。
• CPU が低く、ブロックされたスタックが繰り返される: 同期、I/O、スケジューラ、キューイング、または外部依存関係。
• ThreadPool キューが増加し、CPU が低くブロッキングスタックがある: 枯渇または同期オーバー非同期。
• マネージドライブバイトが安定しているのにプライベート/RSS が増加: ネイティブヒープ、マッピング、コードヒープ、断片化、グラフィックスリソース、または OS キャッシュ。
• 同等のフルコレクションポイント後のライブマネージドグラフが成長: マネージドリテンションまたは意図的な無制限キャッシュ。
• CPU フレーム時間が長く、GPU タイムスタンプが短い: アプリケーション/レンダースレッド/ドライバ CPU バウンド。
• CPU サブミッションが短く、GPU タイムスタンプが長い: GPU 実行バウンド。
• CPU と GPU が早く完了したが、プレゼントが遅い: スワップチェーン、コンポジター、vsync、ドローアブル枯渇、またはディスプレイペーシング。
• 依存サブミッション間に GPU アイドルギャップがある: CPU 枯渇、過剰な同期、シリアル化、または不十分なバッファリング。
• レイテンシが高く、オン CPU 時間が低い: オフ CPU 待機、キューイング、依存関係、スロットリング、またはスケジューラ遅延。
• 起動は改善したが最初のアクションが悪化: 作業が削除されるのではなく延期された。
• ベンチマークは改善したがプロダクトメトリクスは改善しない: 実験がクリティカルパスを省略した、間違った入力分布を使用した、または非支配的な操作を最適化した。

エージェント操作手順

• リポジトリのビルド、デプロイ、診断、ベンチマークプロジェクト、入力コーパス、CI、アーティファクト規約を検査します。
• artifacts/performance/<issue-or-timestamp>/ またはリポジトリの同等の場所を作成します。
• 存在しない場合、決定論的なワークロードドライバーと安定したマーカーを追加します。
• コマンド、環境メタデータ、アナライザー/ツールバージョン、公式リファレンスリンクをアーティファクトの隣に保存します。
• 最初にインクルーシブコスト、次にエクスクルーシブコスト、呼び出し先、待機、キューイング、同期、所有権を分析します。
• 支配的原因が裏付けられた後にのみコードを変更します。
• 再発を防ぐベンチマーク、回帰予算、テレメトリマーカー、トレースレシピ、またはライフタイム不変条件を追加します。
• 大きなトレース、キャプチャ、ダンプ、ベンチマークアーティファクトを Git に保持しないでください（リポジトリポリシーで明示的に保存する場合を除く）。
• ハッピーパスだけでなく、障害、キャンセル、過負荷、クリーンアップ、デバイスロス、シャットダウンのパスも検証します。

拒否すべき無効な結論

• 「CPU が高い、したがってメソッド X が遅い」（スタックなし）。
• 「RSS が増加した、したがってマネージドヒープがリークしている。」
• 「GC ヒープは安定している、したがってリークはない。」
• 「平均レイテンシ/フレーム時間は予算内である、したがってテールは健全である。」
• 「GPU 使用率が高い、したがってシェーダー X がボトルネックである。」
• 「レンダースレッドはビジーである、したがって GPU はビジーである。」
• 「1 つのフレームキャプチャが定常状態の動作を表す。」
• 「ドローコールが少ないほど、常にレンダリングが速くなる。」
• 「ThreadPool スレッドを増やせば枯渇は解決する。」
• 「非同期コードはブロックできない。」
• 「NativeAOT は自動的に高速である。」
• 「マイクロベンチマークの改善はアプリケーションの改善を証明する。」
• 「統計的に検出可能なデルタは自動的にプロダクトにとって重要である。」
• 「1 回のベンチマーク実行で結果が証明される。」

ドキュメント脚注

Footnotes

1. references/command-reference.md は、.NET 診断ツール、BenchmarkDotNet、Xcode Instruments、Windows Performance Toolkit、Linux perf/BCC、PresentMon、RenderDoc、およびベンダー GPU プロファイラーの現在の公式ドキュメントにリンクしています。 ↩