mcpField
L
ln-840-benchmark-compare

ln-840-benchmark-compare

github.com/levnikolaevichテスト・品質584149 回インストール2 日前に更新
リポジトリ

ln-840-benchmark-compare について

Claude Codeで標準ツールのみの場合とhex-line利用時を比較するA/Bベンチマーク用スキルです。期待差分で結果を検証し、起動状況、正確性、時間、コスト、トークンを報告します。

主な機能

  1. 01シナリオ別A/B実行
  2. 02差分に基づく正確性検証
  3. 03実行ごとの分離ワークツリー
  4. 04起動状況と利用指標の集計
  5. 05Markdownと機械可読レポート

活用シーン

  1. 01hex-lineの有無でClaude Codeを比較
  2. 02期待差分に対するシナリオ結果の確認
  3. 03時間、コスト、トークンの変化を確認

MCP 対応

hex-line MCPサーバーを設定したClaudeセッションと、標準ツールのみのセッションを比較します。必要なログと差分成果物を出力できる場合、3つ目のMCP互換セッションも追加できます。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/levnikolaevich/claude-code-skills --skill ln-840-benchmark-compare

インストール後、Claude Code で/ln-840-benchmark-compareを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
benchmark_worker_runtime_contract.md
coordinator_summary_contract.md
expectations.json
goals.md
mcp-bench.json
monitor_integration_pattern.md
references/scripts/benchmark-worker-runtime/
cli.mjs
references/scripts/benchmark-worker-runtime/lib/
guards.mjs
phases.mjs
store.mjs
references/scripts/coordinator-runtime/lib/
artifacts.mjs
cli-helpers.mjs
core.mjs
loop-health.mjs
runtime-constants.mjs
schemas.mjs
validate.mjs
worker-guards.mjs
worker-runtime.mjs
scripts/
extract-scenarios.mjs
parse-results.mjs
run-benchmark.sh

詳細

パス： ファイルパス（references/）は、このスキルのディレクトリを基準とします。

ベンチマーク比較

タイプ： L3 ワーカー カテゴリ： 8XX 最適化 -> 840 ベンチマーク

Claude Code でクリーンな A/B ベンチマークを実行します。1つは組み込みツールのみのセッション、もう1つは hex-line を使用するセッションです。このベンチマークはシナリオベースで、差分検証、マニフェスト駆動、実行時データに基づいています。アクティベーション、正確性、所要時間、コスト、トークン数を測定します。現在のランナーは、この内部 A/B に意図的に範囲を限定しています。このベンチマーク単独では、外部の代替手段と比較して最良であることは証明できません。

入力 / 出力

方向内容
入力mcp/hex-line-mcp/ を含むリポジトリのチェックアウト、任意の references/goals.md、任意の references/expectations.json
出力plugins/optimization-suite/skills/ln-840-benchmark-compare/results/{date}-comparison.md に保存される比較レポートと、機械可読なベンチマーク要約アーティファクト

前提条件

  • claude --version が成功する
  • git が成功する
  • mcp/hex-line-mcp/server.mjs が存在する
  • mcp/hex-line-mcp/hook.mjs が存在する
  • plugins/optimization-suite/skills/ln-840-benchmark-compare/references/goals.md が存在する
  • plugins/optimization-suite/skills/ln-840-benchmark-compare/references/expectations.json が存在する
  • plugins/optimization-suite/skills/ln-840-benchmark-compare/references/mcp-bench.json が存在する

クイック実行

bash plugins/optimization-suite/skills/ln-840-benchmark-compare/scripts/run-benchmark.sh \
  [plugins/optimization-suite/skills/ln-840-benchmark-compare/references/goals.md] \
  [plugins/optimization-suite/skills/ln-840-benchmark-compare/references/expectations.json]

追加セッションプロファイル（任意）：

EXTRA_SESSION_ID=other-mcp \
EXTRA_SESSION_LABEL="Other MCP" \
EXTRA_MCP_CONFIG=/abs/path/to/other-mcp.json \
EXTRA_SETTINGS='{"disableAllHooks":true}' \
bash plugins/optimization-suite/skills/ln-840-benchmark-compare/scripts/run-benchmark.sh
モニターとの統合（Claude Code 2.1.98+）

必ず読んでください： references/monitor_integration_pattern.md を読み込みます

ベンチマークの進捗をストリーミングします： Monitor(command="bash plugins/optimization-suite/skills/ln-840-benchmark-compare/scripts/run-benchmark.sh 2>&1 | grep --line-buffered -E 'scenario|PASS|FAIL|error|session'", timeout_ms=3600000, description="benchmark run")

フォールバック：Bash(run_in_background=true)。

ランナーが処理する内容：

  • 構文の事前チェック
  • SessionStart の事前チェック
  • goals.md からのシナリオ抽出
  • シナリオ／セッションごとに分離されたワークツリー
  • シナリオごとの差分
  • 最終比較レポート

現在の範囲：

  • 組み込み Claude セッション
  • Claude と hex-line の組み合わせ
  • 環境変数 EXTRA_SESSION_* を介した、任意の3つ目の Claude 互換セッションプロファイル

外部ベースラインに関する注意：

  • 同じ goals.md と expectations.json を使用します
  • 外部ツールに合わせてシナリオを書き換えないでください
  • 内部 A/B のみを根拠に「最高のツール」と主張しないでください
  • 3つ目の任意セッションプロファイルが有効なのは、同じ stream-json ログ形式と差分アーティファクトを出力できる場合に限ります

ワークフロー

フェーズ 1：標準スイートを定義する

このスキルが管理する標準ペアを1組使用します：

  • plugins/optimization-suite/skills/ln-840-benchmark-compare/references/goals.md
  • plugins/optimization-suite/skills/ln-840-benchmark-compare/references/expectations.json

ルール：

  • スイートは、一般的なエンジニアリングシナリオをバランスよく組み合わせたものでなければなりません。
  • hex-line に有利になるようスイートを設計しないでください。
  • goals.md のすべてのシナリオに、expectations.json の対応するエントリーが必要です。
  • 正確性の基準には expectations.json を使用します。
  • 今後、外部ベースラインを使用する場合も、同じペアを変更せずに再利用してください。

シナリオごとにサポートされる期待値フィールド：

フィールド意味
id結果ファイル名に使用されるシナリオ識別子
expectedChangedFiles変更が必要なファイル
forbiddenChangedFiles変更してはならないファイル
requiredDiffPatterns保存された差分に含まれている必要がある正規表現パターン
forbiddenDiffPatterns差分に含まれてはならない正規表現パターン
requiredResultPatterns最終的なアシスタントの結果テキストに含まれている必要がある正規表現パターン
requiredCommands少なくとも1つの Bash コマンドに一致する必要がある正規表現パターン
exactChangedFilestrue の場合、追加の変更ファイルは許可されません
フェーズ 2：事前チェック

ランナーは以下に合格する必要があります。

  • node --check server.mjs
  • node --check hook.mjs
  • node --check extract-scenarios.mjs
  • node --check parse-results.mjs
  • hook.mjs による SessionStart のスモークチェック

事前チェックに失敗した場合、ベンチマークは無効となり、シナリオを実行する前に停止する必要があります。

フェーズ 3：シナリオごとの実行

goals.md にある各 ## シナリオについて、次を行います。

  1. 独立したプロンプトファイルを生成する
  2. 同じコミットから、クリーンなワークツリーを 2 つ作成する
  3. 組み込みの Claude セッションを実行する
  4. hex-line の Claude セッションを実行する
  5. .jsonl ログと .diff.txt の成果物を保存する
  6. 両方のワークツリーを削除する

組み込みセッション：

  • MCP なし
  • フックは無効

Hex-line セッション：

  • server.mjs を指す解決済み MCP 設定
  • outputStyle: "hex-line"
  • hook.mjs を介した PreToolUse フック
フェーズ 4：結果の解析

parse-results.mjs は、各シナリオを両方のセッションについて評価します。

シナリオの合格には、以下が必要です。

  • 有効な実行
  • セッションが正常に完了している
  • 変更されたファイルが期待と一致している
  • diff のパターンが期待と一致している
  • 結果テキストのパターンが期待と一致している
  • 必須コマンドが実際に実行されている
フェーズ 5：レポートの確認

最終レポートには、以下のセクションがあります。

  • シナリオの結果
  • 有効化
  • 時間
  • コスト
  • トークン
  • ツールの合計
  • 有効性

解釈ルール：

  • invalid run は、製品のパフォーマンスではなく、セットアップ／導入の失敗を意味します
  • シナリオの FAIL は、正確性の契約が満たされなかったことを意味します
  • hex-line では、有効化は製品品質の一部であり、外部ノイズではありません
  • このレポートは内部 A/B 評価には必要ですが、最良の代替手段を主張するには不十分です

レポートの契約

plugins/optimization-suite/skills/ln-840-benchmark-compare/results/{date}-comparison.md では、以下に回答する必要があります。

  • 各シナリオは正しく完了しましたか？
  • hex-line は、探索のずれなく適切に有効化されましたか？
  • 実時間、API 時間、コスト、出力トークン、ツール呼び出しの合計はどのように変化しましたか？
  • 実行は有効でしたか？

シナリオの正確性を考慮せずに、時間やコストの生データだけで判断しないでください。

外部ベースラインのポリシー

  • このスキルが管理するのは標準スイートであり、普遍的なリーダーボードではありません。
  • メンテナーが hex-line と外部の代替手段を比較する場合、同じ goals.md、expectations.json、および diff ベースの評価ルールを再利用する必要があります。
  • 外部での実行には異なるハーネスを使用できますが、同じタスクのテキスト、開始コミット、正確性の契約を維持する必要があります。
  • 外部ツールが契約の形式を満たせない場合は、それに合わせてスイートを書き換えるのではなく、ハーネスの制約として記録してください。
  • 組み込みの Claude と hex-line の比較のみを対象とするレポートでは、その旨を明記する必要があります。

ランタイム契約

必ず読むこと： Load references/benchmark_worker_runtime_contract.md, references/coordinator_summary_contract.md

ランタイム CLI：

node references/scripts/benchmark-worker-runtime/cli.mjs start --skill ln-840-benchmark-compare --identifier suite-default --manifest-file <file>
node references/scripts/benchmark-worker-runtime/cli.mjs checkpoint --skill ln-840-benchmark-compare --identifier suite-default --phase PHASE_0_CONFIG --payload '{...}'
node references/scripts/benchmark-worker-runtime/cli.mjs record-summary --skill ln-840-benchmark-compare --identifier suite-default --payload '{...}'
node references/scripts/benchmark-worker-runtime/cli.mjs complete --skill ln-840-benchmark-compare --identifier suite-default

必須の状態フィールド：

  • report_ready
  • summary_recorded
  • final_result
  • self_check_passed

ドメインのチェックポイント：

  • PHASE_0_CONFIG
  • PHASE_1_PREFLIGHT
  • PHASE_2_LOAD_SUITE
  • PHASE_3_RUN_SCENARIOS
  • PHASE_4_PARSE_RESULTS
  • PHASE_5_WRITE_REPORT
  • PHASE_6_WRITE_SUMMARY
  • PHASE_7_SELF_CHECK

ガードルール：

  • 現在のフェーズをチェックポイントに記録せずに先へ進まないでください
  • benchmark-worker のサマリーが記録される前に完了しないでください
  • セルフチェックに合格する前に完了しないでください
ランタイムの調整
  • 管理対象の実行では、決定的な runId と正確な summaryArtifactPath を渡せます。
  • スタンドアロンでの実行もサポートされています。両方が省略された場合、ランタイムはスタンドアロン実行を作成し、benchmark-worker ファミリーのデフォルトのサマリー成果物パスに書き込みます。

実行時サマリーアーティファクト

必ずお読みください： references/coordinator_summary_contract.md を読み込んでください

比較レポートの書き込み後、benchmark-worker サマリーエンベロープを出力してください。

管理モード：

  • 正確な summaryArtifactPath に書き込んでください

スタンドアロンモード：

  • .hex-skills/runtime-artifacts/runs/{run_id}/benchmark-worker/ln-840-benchmark-compare--{identifier}.json に書き込んでください

推奨ペイロード：

  • scenarios_total
  • scenarios_passed
  • scenarios_failed
  • activation_valid
  • validity_verdict
  • report_path
  • warnings
  • metrics

既知の落とし穴

落とし穴解決策
hex-line の実行に SessionStart がない事前チェックに失敗した時点で停止します
エージェントが hex-line を使う前に ToolSearch に逸れるアクティベーションの問題として扱い、レポートに記録します
前回のクラッシュでワークツリーが残っている新しいワークツリーを追加する前に削除します
差分アーティファクトがないシナリオの正しさを失敗として扱います
単純なシナリオで組み込み機能が有利になるよくあるケースならスイートに残します。都合のよいものだけを選ぶより、正直さを優先します
外部比較でシナリオが編集されている、または期待値が緩和されている比較を無効として扱います

完了の定義

  • goals.md で標準となるバランスの取れたスイートが定義されている
  • expectations.json でシナリオの正しさがすべて記述されている
  • ランナーが構文と SessionStart の事前チェックに合格する
  • 各シナリオが、同じコミットから作成したクリーンなワークツリー 2 つで実行される
  • パーサーがログと差分からアクティベーションとシナリオの正しさを評価する
  • 最終レポートが plugins/optimization-suite/skills/ln-840-benchmark-compare/results/ に保存されている
  • benchmark-worker サマリーアーティファクトが、管理モードまたはスタンドアロンの実行時パスに書き込まれている
  • 一時ワークツリーが削除されている
  • レポートに、内部 A/B 比較のみなのか、追加の外部ベースラインも含むのかが明記されている

バージョン： 2.0.0 最終更新日： 2026-03-24

コメント

Markdown 対応