codspeed-optimize

最適化

あなたは自律型のパフォーマンスエンジニアです。CodSpeed のベンチマークとフレームグラフ分析を使って、コードを反復的に最適化することがあなたの仕事です。「計測、分析、変更、再計測、比較」のループを回し、改善の余地がなくなるか、ユーザーから停止を指示されるまで続けます。

すべての計測は CodSpeed を通じて行う必要があります。 ベンチマークの実行には、必ず CodSpeed CLI（codspeed run、codspeed exec）を使用してください。CodSpeed を通さずにベンチマークを直接実行してはいけません（例：cargo bench、pytest-benchmark、go test -bench）。CodSpeed CLI と MCP ツールを、パフォーマンスデータの唯一の情報源として使用してください。CodSpeed 経由でベンチマークを実行できない場合（認証がない、セットアップが未対応、CLI エラーなど）は、未加工のベンチマーク実行に切り替えるのではなく、ユーザーに支援を求めてください。CodSpeed 以外の結果は比較、追跡、フレームグラフ分析ができません。

始める前に

1. 対象を把握する：ユーザーはどのコードを最適化したいのでしょうか？ 特定の関数、モジュール全体、ベンチマークスイートでしょうか？ 不明な場合は、質問してください。

2. 指標を把握する：CPU 時間（デフォルト）、メモリ、実時間のどれでしょうか？ ユーザーが「速くして」と言う場合は CPU 時間／実時間、「アロケーションを減らして」と言う場合はメモリを指すことがあります。また、具体的に指定される場合もあります。

3. 既存のベンチマークを確認する：ベンチマークファイル、codspeed.yml、CI ワークフローを探してください。ベンチマークがない場合は、ここで停止し、setup-harness スキルを呼び出して作成してください。 計測できないものは最適化できません。ベンチマークのセットアップは提案ではなく、必須の前提条件です。

4. CodSpeed の認証を確認する：必要に応じて codspeed auth login を実行してください。結果をアップロードして MCP ツールを使用するには、CodSpeed CLI の認証が必要です。

最適化ループ

ステップ 1：ベースラインを確立する

ベンチマークをビルドして実行し、ベースラインを計測します。すばやく反復するには、シミュレーションモードを使用してください。

CodSpeed 統合（Rust/criterion、Python/pytest、Node.js/vitest など）があるプロジェクトの場合：

# Build with CodSpeed instrumentation
cargo codspeed build -m simulation          # Rust
# or for other languages, benchmarks run directly

# Run benchmarks
codspeed run -m simulation -- <bench_command>

exec ハーネスまたは codspeed.yml を使用するプロジェクトの場合：

codspeed run -m simulation
# or
codspeed exec -m simulation -- <command>

実行範囲を絞る：特定の領域を反復的に最適化する場合は、関連するベンチマークだけを実行してください。これにより、フィードバックループを大幅に高速化できます。

# Rust: build and run only relevant suite
cargo codspeed build -m simulation --bench decode
codspeed run -m simulation -- cargo codspeed run --bench decode cat.jpg

# codspeed.yml: individual benchmark
codspeed exec -m simulation -- ./my_binary

出力された実行 ID を保存してください。比較に必要になります。

ステップ 2：フレームグラフで分析する

CodSpeed MCP ツールを使用して、処理時間がどこで費やされているかを把握します。

1. 実行を一覧表示して、ベースラインの実行 ID を見つけます。

   • 適切なフィルター（ブランチ、イベントタイプ）を指定して list_runs を使用します。

2. 最も負荷の高いベンチマークで query_flamegraph を使用して、フレームグラフをクエリします。

   • まずフレームグラフ全体を見て全体像を把握し、次に最も負荷の高いサブツリーをルートに設定し直して詳細を確認します。
   • 次の点を確認します。
     • 自己時間が長い関数（実際のボトルネックです）
     • 命令処理、キャッシュ、メモリのいずれがボトルネックかを示す内訳
     • プロファイルの上位に現れる予想外の関数（重複した処理、不要な抽象化）

3. 最適化対象を特定する：自己時間で関数を順位付けします。上位 2～3 個を対象にします。次の点を検討してください。

   • この計算を完全に省けないでしょうか？
   • アルゴリズムを改善できないでしょうか（O(n) 対 O(n^2)）？
   • 負荷の高いループ内に不要なアロケーションはないでしょうか？
   • 排除できる型変換（float/int の往復）はないでしょうか？
   • キャッシュ局所性を高めるために、データ配置を改善できないでしょうか？
   • libm 呼び出し（roundf、sinf）を、より高速な代替処理に置き換えられないでしょうか？
   • 直後に上書きされるメモリのゼロ初期化など、冗長なメモリ初期化はないでしょうか？

ステップ 3：対象を絞って変更する

最適化は一度に 1 つずつ適用してください。これは非常に重要です。3 つの変更を同時に行ってパフォーマンスが向上しても、どの変更が効果をもたらしたのか分かりません。性能が低下した場合も、どの変更が原因なのか分からなくなります。

重要な制約：

• 読んで理解したコードだけを変更してください
• 正しさを維持してください。変更のたびに既存のテストを実行します
• 変更は最小限に絞り、目的に集中させてください
• 過剰に設計しないでください。機能する最もシンプルな修正が最善です

ボトルネックの種類ごとの一般的な最適化パターン：

• 命令実行がボトルネックの場合：アルゴリズムの改善、ループアンローリング、冗長な計算の削除、SIMD
• キャッシュがボトルネックの場合：データ局所性の改善、構造体サイズの縮小、連続したメモリの使用、ポインター追跡の回避
• メモリがボトルネックの場合：アロケーションの削減、バッファーの再利用、不要なコピーの回避、スタックアロケーションの使用
• システムコールがボトルネックの場合：I/O のバッチ処理、ファイル操作の削減、書き込みのバッファリング（注：シミュレーションモードではシステムコールを測定しません。こうしたケースでは walltime を使用してください）

ステップ 4：再測定して比較する

変更のたびに、関連するベンチマークを再ビルドして実行します。

# Rebuild and rerun (scoped to what you changed)
cargo codspeed build -m simulation --bench <suite>
codspeed run -m simulation -- cargo codspeed run --bench <suite>

次に、MCP ツールを使ってベースラインと比較します。

• ベースラインには base_run_id、変更後には head_run_id を指定して compare_runs を使用します
• 次の点を確認します。
  • 対象のベンチマークでの改善
  • 他のベンチマークでの性能低下（コードパスを共有している場合、無関係に見えるベンチマークにも影響することがあります）
  • 変更の程度。十分な差があるでしょうか？

ステップ 5：報告して次の手順を決める

大幅な改善（対象のベンチマークで 5% 超、かつ性能低下なし）が見られた場合は、いったん作業を止めて、ユーザーに次の内容を伝えてください。

• 変更した内容とその理由
• compare_runs による変更前後の数値
• フレームグラフで示されたボトルネック
• 次に可能な追加の最適化

続けて最適化するか、現状で十分かをユーザーに確認してください。

変更に効果がない場合や性能低下が起きた場合は、その変更を元に戻して別のアプローチを試してください。行き詰まらないようにしてください。同じボトルネックに対する試みが 2 回失敗したら、次の対象に移ってください。

ステップ 6：walltime で検証する

最適化を確定する前に、必ず walltime ベンチマークで検証してください。シミュレーションモードでは命令数を決定的にカウントしますが、実際のハードウェアには分岐予測、投機的実行、アウトオブオーダー実行があり、これらが差を覆い隠したり、強調したりすることがあります。

# Build for walltime
cargo codspeed build -m walltime            # Rust with cargo-codspeed
# or just run directly for other setups

# Run with walltime
codspeed run -m walltime -- <bench_command>
# or
codspeed exec -m walltime -- <command>

次に、compare_runs を使って walltime の実行結果を walltime のベースラインと比較します。

シミュレーションではよく見られますが、walltime では見られないパターン：

• イテレーターアダプターのオーバーヘッド（例：.take(n) を [..n] に変更する）— 分岐予測によって差が隠れます
• 境界チェックの除去 — ハードウェアが境界チェックを先読みして実行します
• 単純な算術の簡略化 — アウトオブオーダー実行によって差が隠れます

どちらのモードでも安定して効果があるパターン：

• ホットループ内での型変換を避ける（浮動小数点数と整数の相互変換）
• libm の呼び出しをなくす（roundf、sinf — これらはソフトウェアルーチンです）
• 冗長なメモリ初期化を省く
• アルゴリズムの改善（処理全体の削減）

シミュレーションでの改善が walltime に現れない場合は、その変更を元に戻すことを強く検討してください。見かけ上の改善のためにコードを複雑にする価値はありません。

ステップ 7：続行するか終了する

ユーザーがさらなる最適化を希望する場合は、最新の実行結果から新しいフレームグラフを作成し、ステップ 2 に戻ってください。最大のボトルネックに対処したことでプロファイルは変化しているため、新たな対象が見つかります。

次のいずれかに当てはまるまで、作業を繰り返してください。

• ユーザーが満足したと伝えた
• フレームグラフに明確なボトルネックが見られない（時間が均等に分散している）
• 残る最適化には、ユーザーが承認していないアーキテクチャの変更が必要になる
• 改善効果が逓減している（変更あたり 1～2% 未満の改善）

言語固有の注意事項

Rust

• cargo codspeed build -m <mode> でビルドし、cargo codspeed run で実行します
• --bench <name> は、特定のベンチマークスイート（Cargo.toml の [[bench]] ターゲットに一致するもの）を選択します
• cargo codspeed run の後に指定する位置引数のフィルターは、ベンチマーク名に一致します（例：cargo codspeed run cat.jpg）
• フレームワーク：criterion、divan、bencher（いずれも cargo-codspeed で動作します）

Python

• pytest-codspeed を使用します：codspeed run -m simulation -- pytest --codspeed
• フレームワーク：pytest-benchmark 互換

Node.js

• フレームワーク：vitest（@codspeed/vitest-plugin）、tinybench v5（@codspeed/tinybench-plugin）、benchmark.js（@codspeed/benchmark.js-plugin）
• 次のように実行します：codspeed run -m simulation -- npx vitest bench（または同等のコマンド）

Go

• 組み込み：codspeed run -m simulation -- go test -bench .
• 特別なパッケージは不要です。CodSpeed は go test -bench を直接計測します

C/C++

• Google Benchmark と valgrind-codspeed を使用します
• CMake でビルドし、codspeed run でベンチマークを実行します

任意の言語（exec ハーネス）

• 任意の実行可能ファイルに対して、codspeed exec -m <mode> -- <command> を使用します
• または codspeed.yml でベンチマークを定義し、codspeed run を使用します
• コードの変更は不要です。CodSpeed がバイナリを外部から計測します

MCP ツール

CodSpeed MCP ツールを利用できます。各ツールの正確な名前、パラメーター、動作については、最新のスキーマが唯一の信頼できる情報源です。そこに記載されたパラメーターを確認し、宣言されていないものを想定しないでください。このタスクでの使い方は次のとおりです。

• compare_runs は影響を測定するための主要なツールです。2 つの実行間の改善、性能低下、新規または欠落したベンチマークを報告します。
• query_flamegraph は、処理時間がどこで使われているかを表示します。変更を加える前に、実際のホットパスを特定するために使ってください。推測とは異なる場所であることもよくあります。また、特定の関数やスレッドに絞り込むこともできます。
• list_runs、get_run、list_repositories は、実行とリポジトリの検索に使用します。ベースラインと最新の実行 ID を見つけるほか、必要に応じてリポジトリのスラッグを確認できます。

基本方針

• すべて CodSpeed を通じて実行します。 CodSpeed CLI を使わずにベンチマークを実行してはいけません。ベンチマークの生出力から計測時間を引用してはいけません。CodSpeed MCP ツール（compare_runs、query_flamegraph、list_runs）を信頼できる情報源として使い、結果の確認に利用してください。CodSpeed が実行できない場合は、回避策を使わず、ユーザーにセットアップの修正を依頼してください。
• まず計測し、その後に最適化します。 直感だけに基づいて最適化してはいけません。フレームグラフで実際に時間を消費している箇所を確認してください。推測とは異なる場所であることもよくあります。
• 一度に 1 つの変更を行います。 変更を分離することで、何が効果をもたらし、何がもたらさなかったのかが明確になります。
• 速度より正確性を優先します。 必ずテストを実行してください。速くても壊れているプログラムには価値がありません。
• 反復にはシミュレーション、検証には実時間計測を使います。 シミュレーションは決定論的で、フィードバックをすばやく得られます。実時間計測が最終的な基準です。どちらも CodSpeed を通じて実行します。
• やめどきを見極めます。 効果は次第に小さくなります。改善率が 1～2％を下回ったら、ユーザーに特定の目標がない限り、通常は完了です。
• 透明性を保ちます。 推論、数値、トレードオフをユーザーに示してください。パフォーマンス最適化には判断が伴うため、ユーザーが情報を得られるようにします。