devtu-benchmark-harness

ベンチマークハーネス — 継続的改善システム

ToolUniverse のツール、スキル、プラグインの品質を向上させるための、5 ステップのフィードバックループです。

注：このスキルはデータセットに依存しません。ベンチマークごとのスコア履歴、既知の失敗質問 ID、データセット固有の調査内容は、temp_docs_and_tests/benchmark_tracking/（gitignore される作業フォルダー）に保存してください。このスキルディレクトリには保存しないでください。

フィードバックループ

1. RUN benchmark → 2. ANALYZE results → 3. DIAGNOSE failures → 4. FIX via devtu skill → 5. RETEST → repeat

オーケストレーション実行（推奨）

1 つのコマンドでステップ 0（記憶監査）、1（ビルド）、2（実行）、3（分析）、4（診断＋失敗の抽出）を実行します。

bash skills/devtu-benchmark-harness/scripts/run_harness_loop.sh --benchmark bixbench --n 20 --seed 42
# After reviewing diagnose.log and applying devtu skill fixes:
bash skills/devtu-benchmark-harness/scripts/run_harness_loop.sh --retest /path/to/failures.json

スクリプトは temp_docs_and_tests/benchmark_tracking/run_<TS>/ に results.json、analysis.log、diagnose.log、failures.json を作成します。診断の出力には、各失敗と、呼び出すべき正確な devtu スキルが記載されます。手動で修正しないでください。

記憶の丸暗記防止ガード

devtu-optimize-skills による編集でも手動編集でも、スキルの編集を受け入れる前に、次を実行してください。

python3 skills/devtu-benchmark-harness/scripts/check_memorization.py --all

いずれかのスキルにベンチマーク名、カプセル UUID、bix-N 質問 ID、または正解（GT）と判明している特定の数値回答が含まれていると、失敗します。これにより、プラグインが単一ベンチマークの解答集に過剰適合するのを防ぎます。--strict モードで実行すると、特定の遺伝子名とデータセットのファイル名も検出します（より弱いシグナルです）。

ステップ 1：実行 — ベンチマークを実行

bash scripts/build-plugin.sh   # rebuild plugin with latest skills

python skills/devtu-benchmark-harness/scripts/run_eval.py \
  --benchmark bixbench \        # bixbench | lab-bench | custom
  --mode plugin-only \          # plugin-only | baseline-only | comparison
  --n 205 \                     # number of questions
  --timeout 1800 \              # seconds per question
  --max-turns 30                # agent turns per question

オプション：--category DESeq2（絞り込み）、--resume results.json（完了済みをスキップ）、--guidance path.md（カスタム指示を追加）。

信頼性モード：APPEND_CONVENTIONS 環境変数

対話モードでのスキルの自動マッチングにはばらつきがあります。Claude がスキルの説明を読んでも、スキル本文を読み込む前にコードを書き始めることがあります。ルーターの重要な規約をすべてのリクエストのシステムプロンプトに強制的に追加するには、次を設定します（より信頼性が高く、実装されたスキルルーティングではなく、設計された規約に基づいてプラグインを評価できます）。

APPEND_CONVENTIONS=1 python skills/evals/run_benchmark.py --benchmark bixbench --plugin-only

規約の正しさ（ルールが適切かどうか）を測定する場合は、このモードを使用してください。スキルルーティングの信頼性（Claude が実際にスキルを呼び出すかどうか）を測定する場合は、デフォルトモードを使用してください。この 2 つの数値の差が、ルーティングの信頼性に関する問題です。

ベンチマークのセットアップ（初回のみ）

Rscript skills/evals/install_r_packages.R                  # R packages
python3 skills/evals/bixbench/download_capsules.py         # BixBench data (~5 GB)

利用可能なベンチマーク

ベンチマーク	質問数	テスト内容	データ
lab-bench	20 問の MCQ	データベース検索の精度	skills/evals/lab-bench/questions.json
bixbench	205 問の計算問題	データ分析＋統計	skills/evals/bixbench/questions.json ＋カプセルデータ
custom	ユーザー定義	任意	カスタム JSON ファイル

ステップ 2：分析 — 失敗をスキルに対応付け

python skills/devtu-benchmark-harness/scripts/analyze_results.py \
  --results results.json \
  --questions skills/evals/bixbench/questions.json \
  --benchmark bixbench

出力：

• スキル別：精度が最も低いスキル（それらを優先して修正）
• カテゴリ別：DESeq2、ANOVA、系統発生学、variant_analysis など
• 失敗の種類：timeout、wrong_answer、tool_error、api_key_missing

カテゴリ → スキルの対応表

カテゴリ	スキル
DESeq2、fold_change	tooluniverse-rnaseq-deseq2
ANOVA、regression、chi_square、spline_fitting	tooluniverse-statistical-modeling
pathway_enrichment、DESeq2+enrichGO	tooluniverse-gene-enrichment
phylogenetics	tooluniverse-phylogenetics
variant_analysis、epigenomics	tooluniverse-variant-analysis
crispr_screen、functional_genomics	tooluniverse-crispr-screen-analysis
single_cell	tooluniverse-single-cell

ステップ 3：診断 — 改善案を取得

python skills/devtu-benchmark-harness/scripts/analyze_results.py \
  --results results.json \
  --questions skills/evals/bixbench/questions.json \
  --diagnose

各提案には、失敗したカテゴリ、該当するスキル、失敗の種類、修正に呼び出す devtu スキルが含まれます。

根本原因の調査

各失敗について、エージェントのエラーか、GT（正解データ）の問題かを確認します。

1. カプセルデータを探します：temp_docs_and_tests/bixbench/bixbench/data/CapsuleFolder-{uuid}/
2. 信頼できるスクリプトを探します：*.py、*.R、analysis.R、run_*.py
3. スクリプトを自分で実行し、GT の値が再現されるか確認します。
4. 計算結果が GT ではなくエージェントの結果と一致する場合、これはエージェントのエラーではなく、GT の問題です。

ステップ 4：修正 — 適切な devtu スキルに振り分ける

手動で修正しないでください — devtu スキルを使い、確立されたパターンに沿ってテストも含めて修正します。

診断	対応	実行するもの
ツールが誤ったデータを返す	ツールコードと JSON 設定を修正する	Skill('devtu-fix-tool')
この計算を行うツールがない	新しい ToolUniverse ツールを作成する	Skill('devtu-create-tool')
スキルが誤ったガイダンスを提供する	SKILL.md の規約を更新する	Skill('devtu-optimize-skills')
エージェントにバンドルスクリプトが必要	スキルの scripts/ ディレクトリにスクリプトを追加する	Skill('devtu-optimize-skills') Pattern 15
採点で偽陰性が発生する	grade_answers.py を修正する	コードを直接修正
複数の変更を連携して行う	全サイクルを実行する	Skill('devtu-self-evolve')

修正ワークフロー

1. analyze_results.py --diagnose → get recommendations
2. For each recommendation → invoke the appropriate devtu skill
3. bash scripts/build-plugin.sh → rebuild dist
4. run_eval.py --retest failures.json → verify fix

例

Diagnosis: "ANOVA wrong_answer → tooluniverse-statistical-modeling"
  → Invoke: Skill('devtu-optimize-skills')
  → Tell it: "statistical-modeling skill produces wrong F-statistics for
     per-gene expression ANOVA. Agent aggregates at sample level instead
     of gene level."
  → The skill handles: read SKILL.md, add convention, verify no
     memorization, rebuild, suggest retest.

ステップ 5：再テスト — 修正を検証する

# Extract failed question IDs
python skills/devtu-benchmark-harness/scripts/analyze_results.py \
  --results results.json --extract-failures /tmp/failures.json

# Retest only failures
python skills/devtu-benchmark-harness/scripts/run_eval.py \
  --benchmark bixbench --mode plugin-only --retest /tmp/failures.json

比較：誤答から正答に変わった件数を確認します。改善した場合はベースラインを更新します。

採点

grade_answers.py は、次の 7 つの戦略を順番に適用します。

1. 完全一致 — 予測に GT の部分文字列が含まれる
2. 選択式問題の一致 — 選択肢の文字（A/B/C/D）を検出する
3. 範囲一致 — 数値が丸め誤差の許容範囲内で (low, high) に含まれる
4. 正規化一致 — 句読点を除去し、双方向の部分文字列照合と太字部分の抽出を行う
5. 数値の近似一致 — 5% の許容誤差内
6. 同義語一致 — 科学用語の同義語を照合する
7. LLM 検証 — Claude が意味上の正しさを判定する（eval_mode=llm_verifier の場合）

Unicode 正規化：マイナス記号（U+2212）、上付き指数（10⁻²⁶ → e-26）。

# Re-grade with LLM
python skills/devtu-benchmark-harness/scripts/grade_answers.py \
  --results results.json --output graded.json --llm

プラグインアーキテクチャ

ToolUniverse プラグインでは、ルーターのみでスキルを照合します。

1 auto-matchable skill: "tooluniverse" (router, ~300 chars)
  └── Routing table → 113 sub-skills (all disable-model-invocation: true)

理由：Claude Code ではスキルの説明に文字数の上限（コンテキストの約 1%）があります。114 スキル × 500 文字 = 57K となり上限を超えるため、説明が省略されます。ルーターを 1 つにすれば、エージェントは常にそれを参照し、正しく振り分けられます。

-p モードではスキルは自動照合されません。ベンチマークランナーは full_skill_injection モードを使って対話時の動作をシミュレートします。該当するスキルをプログラムで検出し、その SKILL.md の全文を注入します。

devtu-self-evolve との統合

Testing と Fix の間に Phase 3.5 として挿入します。

Phase 3 (Test) → Phase 3.5 (Benchmark) → Phase 4 (Fix via devtu) → Phase 5 (Retest)

既知の失敗パターン

--diagnose フラグは次のパターンを参照します。

パターン	根本原因	修正アクション
DESeq2 wrong_answer	pydeseq2 と R の不一致、集合演算の誤り	rnaseq-deseq2 に対して devtu-optimize-skills を実行
ANOVA wrong_answer	F 統計量と p 値の混同、集計の誤り	statistical-modeling に対して devtu-optimize-skills を実行
spline wrong_answer	R の ns() と Python の patsy は一致しない。端点の扱いも異なる	statistical-modeling に対して devtu-optimize-skills を実行
phylogenetics wrong_answer	PhyKIT の出力列選択、ファイルの組み合わせ	phykit_batch_analysis に対して devtu-fix-tool を実行
variant wrong_answer	Excel の複数行ヘッダー、コーディングバリアントの分母	variant-analysis に対して devtu-optimize-skills を実行
enrichGO wrong_answer	R clusterProfiler のバージョン依存性	run_deseq2_analysis に対して devtu-fix-tool を実行
timeout	パイプラインが 30 分を超える（Trimmomatic、GATK）	パイプラインをラップするため devtu-create-tool を実行
GT issue	現在のツールでは正解データを再現できない	結果に記録し、スコアから除外する

スキル規約のルール

ベンチマークの知見をもとにスキルへ規約を追加する場合：

• 一般的な知識のみ — データセット固有の値や、記憶した回答を含めない
• 例より原則を重視 — 「サンプルごとではなく遺伝子ごとに ANOVA を行う」とし、「このデータセットでは F=0.77」としない
• ツールの優先設定 — 「分散推定には R DESeq2 を使う」とし、「R では 4、pydeseq2 では 2」としない
• 情報の混入がないことを確認 — 規約のテキストにデータセット名や特定の数値回答がないか grep で検索する