benchmark-runner

ベンチマークランナー

パフォーマンス比較の方法を標準化します。指標の選定、テストケースの設計、環境の記録、結果のフォーマット、トレードオフ分析が含まれます。情報に基づいた意思決定を支える、再現可能なベンチマークレポートを作成します。単に「A は B より速い」ではなく、「小さい入力では A が速く、大規模化すると B のほうが優れたスケーリングを示す」といった結果を示します。

参照ファイル

ファイル	内容	読み込むタイミング
references/metric-selection.md	指標カタログ（レイテンシのパーセンタイル、スループット、メモリ、精度）、タスクの種類に応じた選定基準	常に
references/test-case-design.md	代表的な入力の選定、規模の変化、エッジケースの網羅、ウォームアップ戦略	常に
references/environment-capture.md	ハードウェア／ソフトウェア環境の記録、再現性の要件、ばらつきの制御	常に
references/statistical-rigor.md	サンプルサイズの決定、ばらつきの測定、有意性検定、外れ値の処理	結果の統計的な検証が必要な場合

前提条件

• 比較対象が明確であること（2 つ以上）
• 比較対象を実行または観察できること（コード、API、既存の結果）
• 代表的なワークロードが定義されていること

ワークフロー

フェーズ 1：範囲の定義

1. 比較対象は何ですか？ — 各対象の名前を、バージョンも含めて正確に記載します。 「Python dict と Redis」では曖昧すぎます。「Python 3.12 dict（プロセス内）と Redis 7.2 （localhost、TCP）」であればテスト可能です。
2. どの主張を検証する必要がありますか？ — 「A は速い」だけでは不十分です。何に対して速いのでしょうか？どの入力サイズで、どのような負荷のもとででしょうか？ベンチマークの設計は、具体的な主張に基づいて決まります。
3. 意思決定の背景は何ですか？ — なぜこの比較が重要なのでしょうか？これによって、最も重要な指標が決まります。

フェーズ 2：指標の選定

意思決定の背景に合った指標を選びます。

指標カテゴリ	具体的な指標	重要となる場面
レイテンシ	P50、P95、P99、平均、標準偏差	ユーザー向け操作、API 呼び出し
スループット	ops/sec、tokens/sec、MB/sec	バッチ処理、ストリーミング
メモリ	ピーク RSS、平均 RSS、割り当て率	リソースが制限された環境
精度	F1、BLEU、完全一致、適合率／再現率	ML モデル、品質とのトレードオフがあるアルゴリズム
コスト	1,000 操作あたりの費用、1 時間あたりの費用、1 GB あたりの費用	クラウドサービス、API の比較
起動	初回操作までの時間、コールドスタート	サーバーレス、CLI ツール

指標は 2～4 個選びます。4 個を超えると、比較表が読みにくくなります。

フェーズ 3：テストケースの設計

パフォーマンスの特性を明らかにする入力のマトリックスを作成します。

1. 規模の変化 — 小、中、大の入力を用意します。規模に応じてパフォーマンスが非線形に変化することはよくあります。
2. 代表的なデータ — 合成した理想的なデータではなく、現実的な入力を使います。
3. エッジケース — 空の入力、最大サイズ、敵対的な入力を含めます。
4. ウォームアップ — JIT コンパイル、キャッシュのウォームアップ、接続確立にかかる時間は測定対象から除外します。記録を開始する前に、N 回のウォームアップ反復を実行します。

フェーズ 4：環境の指定

結果を再現するために必要な情報をすべて記録します。

1. ハードウェア — CPU モデル、コア数、RAM 容量、GPU モデル（該当する場合）
2. ソフトウェア — OS バージョン、言語ランタイムのバージョン、依存関係のバージョン
3. 設定 — スレッド数、バッチサイズ、接続プールサイズ、キャッシュ設定
4. 分離 — ほかに何が実行されていましたか？バックグラウンドプロセスは結果に影響します。

フェーズ 5：結果の構成

指標ごとに明確な勝者を示す比較表を作成し、その後にトレードオフを分析します。

出力形式

# Benchmark: {Descriptive Title}

**Date:** {YYYY-MM-DD}
**Hardware:** {CPU}, {RAM}, {GPU if applicable}
**Software:** {runtime versions}
**Configuration:** {key settings that affect results}

## Candidates

| # | Candidate | Version | Configuration |
|---|-----------|---------|---------------|
| A | {name} | {version} | {relevant config} |
| B | {name} | {version} | {relevant config} |

## Test Cases

| # | Name | Input Size | Description | Warmup | Iterations |
|---|------|------------|-------------|--------|------------|
| 1 | Small | {size} | {what it represents} | {N} | {N} |
| 2 | Medium | {size} | {what it represents} | {N} | {N} |
| 3 | Large | {size} | {what it represents} | {N} | {N} |

## Results

### Latency (ms, lower is better)

| Test Case | A (P50 / P95 / P99) | B (P50 / P95 / P99) | Winner |
|-----------|---------------------|---------------------|--------|
| Small | {values} | {values} | {A or B} |
| Medium | {values} | {values} | {A or B} |
| Large | {values} | {values} | {A or B} |

### Memory (MB, lower is better)

| Test Case | A (Peak) | B (Peak) | Winner |
|-----------|----------|----------|--------|
| Small | {value} | {value} | {A or B} |
| Medium | {value} | {value} | {A or B} |
| Large | {value} | {value} | {A or B} |

## Analysis

### Overall Winner
**{Candidate}** wins on {N} of {M} metrics across all test cases.

### Tradeoff Summary
- **Choose A when:** {conditions where A is the better choice}
- **Choose B when:** {conditions where B is the better choice}

### Caveats
- {Limitation of this benchmark}
- {Condition under which results may differ}

## Reproduction

```bash
# Environment setup
{commands to recreate the environment}

# Run benchmark
{commands to execute the benchmark}

## Configuring Scope

| Mode | Candidates | Depth | When to Use |
|------|-----------|-------|-------------|
| `quick` | 2 candidates, 1-2 metrics | Single test case, no statistics | Rough comparison, sanity check |
| `standard` | 2-3 candidates, 2-4 metrics | 3 test cases, mean + std dev | Default for most comparisons |
| `rigorous` | Any count, full metric suite | Multiple test cases, percentiles, significance tests | Publication, critical decisions |

## Calibration Rules

1. **Measure, don't guess.** Intuition about performance is unreliable. "Obviously
   faster" is not a benchmark result.
2. **Apples to apples.** Candidates must be compared under identical conditions.
   Different hardware, configuration, or input data invalidates the comparison.
3. **Report variance, not just means.** A mean of 50ms with std dev of 100ms is not
   the same as a mean of 50ms with std dev of 2ms. Always report spread.
4. **Warm up before measuring.** First-run performance includes JIT, cache warming,
   and connection setup. Exclude warmup iterations from results.
5. **Representative inputs only.** Benchmarking with synthetic best-case input is
   misleading. Use data that resembles production workloads.
6. **State the winner per metric, not overall.** "A is better" is lazy. "A has lower
   latency; B uses less memory" is useful.

## Error Handling

| Problem | Resolution |
|---------|------------|
| Cannot run candidates locally | Design the benchmark specification. Document what to measure and how. The user executes separately. |
| Results are noisy (high variance) | Increase iteration count. Check for background processes. Use dedicated hardware or containers for isolation. |
| Candidates serve different purposes | Acknowledge that the comparison is partial. Benchmark only the overlapping functionality. |
| No baseline exists | Establish one candidate as the baseline. Report relative performance (e.g., "B is 1.3x faster than A"). |
| Hardware context unavailable | Document what is known. Note that results may not be reproducible without full context. |

## When NOT to Benchmark

Push back if:
- The comparison is not performance-related (feature comparison → use a decision matrix or ADR instead)
- The candidates are fundamentally different tools (comparing a database to a message queue)
- The user wants to benchmark trivial operations (comparing two string concatenation methods in Python)
- Results from others already exist and conditions match — link to existing benchmarks instead