ln-34-benchmark-comparator

ベンチマーク比較

目標： 管理された再現可能な条件下で代替案を比較します。速度より正確性を優先し、測定データは推定値、セットアップコスト、解釈と分けて扱う必要があります。

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

ツールの使い分け

必要なもの	推奨ツール	使用する状況	代替手段
正規のワークロードとオラクル	リポジトリのフィクスチャ、テスト、期待される差分、スキーマ、または独立して定義された結果	いずれかの候補を実行する前に、成功の定義を確立するとき	判断を表現する最小限の決定論的なフィクスチャを作成する
分離	クリーンな Git ワークツリー、一時ディレクトリ、制御された環境、固定シード、リセット可能なキャッシュ	ある候補や実行が別の候補や実行に影響するのを防ぐとき	検証済みのクリーンアップを伴う、順次のクリーンルーム設定
実行	すべての候補で同じシェルランナーとラッパー	コマンド、終了ステータス、標準出力、標準エラー、時間、成果物を一貫して記録するとき	再現性に関する制約を明示した手動実行
有効化の証明	ログ、トレース、コマンド記録、プロセスメタデータ、または候補固有の成果物	意図した代替案が実際に実行され、フォールバックしなかったことを検証するとき	有効化を証明できない場合、その実行を無効として扱う
正確性の評価	テスト、出力パーサー、差分、スキーマ検証、または独立したオラクル	コストを比較する前の、すべてのシナリオ	記述済みの期待値に照らした、手動でのブラインド評価
性能とコスト	単調時計、リソース指標、トークンまたは利用状況のテレメトリー、ツール呼び出しログ、失敗回数	すべての候補で同じ方法を通じて指標を観測できるとき	派生値または推定値と明記し、測定値の集計から除外する
外部仕様	公式ドキュメントと仕様書	候補の設定や主張された動作について最新の確認が必要なとき	一次情報に基づくウェブ調査。それ以外は主張を UNVERIFIED とする

候補の実行結果を見てからシナリオを調整したり、異なるワークロードの測定値を混在させたり、内部推定値を外部で測定された事実として示したりしないでください。ベンチマークでは一時的なワークツリーや成果物を作成できますが、ソースのベースラインや未承認の外部状態を変更してはなりません。

証拠のルール

• テスト対象以外の変数はすべて一定に保つか、交絡因子を記録して分析してください。
• 正確性の失敗は、意思決定で正確性の低下が明示的に許容されていない限り、速度、トークン使用量、またはコストの改善で補うことはできません。
• 複数回実行し、生の値、中心傾向、ばらつき、失敗、外れ値を報告してください。最良の実行結果を見出しにしてはなりません。
• セットアップまたはインデックス作成のコスト、定常状態のコスト、保守負担、実行時コストは分けて報告してください。
• 測定値、派生値、推定値、定性的な証拠は、別々のフィールドで報告してください。

チェックリスト

1. 意思決定と実験を定義する

• ベンチマークで判断する必要がある事項、候補、想定ユーザー、代表的なワークロード、明示的な対象外事項を示します。
• よりシンプルな候補や組み込みの候補が合理的に優位となり得る通常のケースと、各候補が主張する利点を発揮するケースの両方を含めます。一方の候補だけを対象にした機能紹介にならないようにします。
• シナリオの入力、期待される結果、正確性の基準、失敗条件、および候補自身の自己申告に依存しない判定基準を定義します。
• 主要および副次的な指標、単位、測定時点、合格基準、許容されるトレードオフ、同点または判定不能の場合のルールを定義します。
• 変更する変数を定め、それ以外の関連する変数（リビジョン、モデル、プロンプト、権限、ランタイム、ハードウェア、データ、キャッシュ、ネットワーク）を固定します。比較対象の変数を固定変数として宣言してはなりません。
• 既存のばらつきを示す根拠、または範囲を限定した予備試験に基づいて、反復回数を事前に宣言します。または、許容誤差と実行回数の上限を固定した、範囲を限定した逐次実行ルールを定めます。予算内で意味のある効果を判定できない場合は、INCONCLUSIVE を返します。
• 最初の候補の結果を確認する前に、シナリオのテキスト、フィクスチャ、期待値、ランナー、パーサー、判定ルールを凍結してハッシュを記録します。
• ワークツリー、一時データ、ランナーを作成する前に、リポジトリの指示を読み、Git の状態を確認します。
• 実行ごとに作成したすべての絶対パス、ワークツリー、プロセス ID、キャッシュ、アカウント、データセット、レポート、一時成果物を記録するリソース台帳を作成します。既存のリソースや認証情報をクリーンアップ対象として登録してはなりません。
• 副作用のない、またはべき等なシナリオと、破棄可能なアカウントまたはデータセットを必須とします。外部への書き込みの許可、コストとレートの上限、クリーンアップ、ロールバックの証拠を実行前に定義します。
• 候補が同じタスクを解決しない場合、正確性を独立して採点できない場合、外部への影響を分離できない場合、または結果を見た後に判定ルールを選んでいる場合は、BLOCKED を返します。

2. 対称的なハーネスを構築する

• すべての候補で、同じランナー、タイムアウト、ログ記録、環境構築、成果物収集を使用します。
• 同じコミットからクリーンなワークツリー、または同等の分離されたコピーを作成し、開始時の状態が同一であることを確認します。
• 分離されているはずの候補間で挙動が漏れる可能性がある、グローバルおよびユーザーレベルの指示、フック、プラグイン、設定、認証情報、キャッシュ、環境変数をすべて調査します。それぞれを無効化するか、候補間で同等にするか、記録します。
• 結果に影響し得る場合は、シード、時刻、ロケール、並行実行、ネットワークアクセス、依存関係のバージョン、キャッシュの状態、ウォームアップ、シナリオの順序を制御します。
• 候補の正確な設定、機能フラグ、プロンプト、コマンドライン、権限、バージョンを記録します。
• 既定の設定、同等の調整を施した設定、またはその両方のいずれかを採用する、対称的な調整方針と予算を定義します。一方の候補の結果を見てから他方を最適化することがないようにします。
• 各候補が実際に使用されたことを証明し、暗黙のフォールバック、部分的な有効化、混在した実行を特定する有効化チェックを追加します。
• ベンチマークの前に、既知の合格および失敗フィクスチャを使って、出力パーサー、差分ルール、テスト判定基準、指標収集器を検証します。
• 1 回限りのセットアップ、インデックス作成、コンパイル、ダウンロードのコストを、定常状態の実行コストおよび償却コストと分けて扱います。
• リソース台帳に基づいてクリーンアップと障害復旧の手順を定義し、実行がクラッシュまたはタイムアウトしても後続の実行に影響しないようにします。

3. 実行して証拠を収集する

• ウォームキャッシュや実行時刻による体系的な有利不利が生じないよう、候補をバランスの取れた順序またはランダムな順序で実行します。
• すべての実行について、開始時と終了時の状態、コマンド、終了ステータス、実行時間、リソース指標、ログ、出力、差分、テスト、候補固有の成果物を記録します。
• 採点前に有効化を確認します。実証できていない実行やフォールバック実行は、意図した候補に割り当てず、無効として扱います。
• パフォーマンスやコストの指標を確認する前に、事前に定義した正解基準に照らして正確性を採点します。
• タスクの完全性は、正確性や効率とは分けて採点します。差分が小さいこと、トークン数が少ないこと、一部が成功したことを完了とみなさず、必要な成果と禁止された副作用をすべて確認します。
• 手動または定性的な採点者には候補の識別情報を伏せ、提示順をランダム化します。意見の相違は記録し、好ましい候補に有利になるよう解消しません。
• タイムアウト、クラッシュ、不正な形式の出力、部分的な完了、ツールエラー、環境上の失敗は、それぞれ異なる失敗クラスとして記録します。
• 事前に定めた反復ルールまたは逐次的な停止ルールに従い、失敗や無効な実行も含めてすべての試行を数え、保存します。希望する成功回数に達するまで再試行を続けてはいけません。
• 環境の変化、レート制限、外部サービスの停止、バックグラウンド負荷、実行環境の不具合により、追加実行の比較可能性が損なわれた場合は、いったん停止します。
• ハーネスを修正した後は、影響を受ける比較を無効とし、修正済みのハーネスで該当シナリオの両候補を再実行します。影響を受けない証拠は保持し、以前の無効な結果にはその旨を明記します。
• セットアップ、有効化、パーサー、環境に関する失敗は、タスクの不正確さとは分けて扱い、セットアップの信頼性を実際の製品選定の一部とするかどうかを明記します。

4. 妥当性と結果を分析する

• 事前に定めた無効化ルールに該当する実行のみを除外し、その理由と根拠、および除外によって結論が変わるかどうかを記録します。
• 集計する前に、シナリオごとの正確性、失敗、レイテンシ、リソース使用量、トークン数または使用量、ツール呼び出し、その他のコストを報告します。
• サンプルと分布に適した中央値、パーセンタイル、信頼区間、または別の統計量を使用し、ばらつきとサンプル数を示します。
• 単位やワークロードが異なる指標は分けて扱い、実行前に重み付けを定めていない限り、単一の総合スコアにまとめないでください。
• 差が測定ノイズを超えているか、また特定のシナリオが集計結果を支配していないかを確認します。
• セットアップコスト、定常状態のコスト、保守の複雑さ、移植性、障害時の挙動、運用負荷は、ランタイム指標とは分けて分析します。
• 合成フィクスチャ、推定トークン数、文字数ベースの代理指標、モデル化されたコスト、手動による判定には、実測テレメトリと誤認されないよう明記します。
• 定性的な出力品質が判断に大きく影響し、自動評価だけでは不十分な場合は、独立したブラインドレビューを依頼します。

5. 判断し、保持し、クリーンアップする

• 候補が正確性と事前定義した判断ルールを満たし、有効な証拠が十分にある場合にのみ、WIN を使用します。
• 事前定義した無視できる差の範囲、または均衡の取れたトレードオフを証拠が裏付ける場合にのみ、TIE を使用します。証拠が不十分で差を検出できなかった場合は、INCONCLUSIVE とします。
• サンプルサイズ、アクティベーション、オラクル、環境制御、またはシナリオ間の矛盾により信頼できる選択ができない場合は、INCONCLUSIVE を使用します。
• 独立した検証に必要な、再現可能なコマンド、設定、シナリオ定義、期待値、生の結果、正規化した結果、分析を保持します。
• 実行に関連する台帳エントリのみを削除します。絶対パスが承認済みの一時ルート内にあることを確認し、記録されたプロセス ID と完全に一致するものを停止し、変更済みまたは既存のワークツリーを保持し、認証情報は決して削除せず、ソースと外部ベースラインの状態を確認します。
• 無効な実行、除外項目、交絡因子、前提への感度、結論を覆す可能性のある条件を報告します。
• 比較後に残る判断上のリスクを報告します。これには、未対応のワークロード、未測定のコスト、不安定な環境、判定を覆す可能性のある前提が含まれます。
• クリーンアップと制約を考慮したうえで、判断の指針がシナリオ単位の証拠と凍結されたルールに従っていることを確認します。

セルフチェック

• 返却前に整合性を確認します。 項目ごとの証拠、要件の網羅性、矛盾、範囲、判定、適用されるクリーンアップを確認します。レポートまたは承認済みの成果物を修正します。有効な証拠を再利用し、リポジトリを自動的に再スキャンしたり、成功したコマンドを再実行したりしないでください。関連する変更、失敗、未解決の証拠がある場合にのみ、確認を繰り返します。残る不足を明示します。

出力契約

ユーザーの言語で、次の順序で報告します。5つのフィールドをすべて保持し、各事実は一度だけ記載します。結果が少ない場合は各フィールドを1行にしてもかまいません。空の表は省略し、リンク先の成果物をコピーしないでください。

1. 結果： スキル固有の判定と、証拠に裏付けられた結果。
2. 範囲： レビュー／変更した範囲、除外項目、ベースライン、重要な前提。
3. 証拠： 以下のスキル固有の項目。事実、推論、未検証の主張を区別します。成果物にリンクし、役立つ場合は表を使用します。
4. 検証： 確認項目／結果、取得できなかった証拠、適用されるクリーンアップ／外部状態。
5. 完了： Checklist: X/Y complete、Incomplete: None、または各 UNPROVEN 項目の理由、結果への影響、具体的な次のアクション。残余リスクと必要な判断。

スキル固有の証拠： 凍結した判断、候補、シナリオ、独立したオラクル、固定変数、設定、指標、反復回数、除外項目、判断ルール。アクティベーションとハーネスの妥当性を証明し、無効な実行、交絡因子、除外項目、クリーンアップを報告します。集計する前に、シナリオ単位の網羅性、正確性、失敗、主要指標、ばらつき／サンプルサイズ、その他のコストを比較します。セットアップ／保守のトレードオフ、感度、反証条件、生の結果、設定、シナリオの成果物、利用可能な場合はハッシュを保持します。