eval

eval skill の概要

AgentHub セッションで eval が行うこと

eval は、完了したエージェントの成果を順位付けするための AgentHub skill です。複数のエージェントが同じタスクに取り組んだあと、スコアリング、比較、勝者の選定が必要になる /hub:eval コマンド向けに設計されています。eval skill は、eval コマンドが設定されている場合はメトリクスベースの評価を、利用できるメトリクスがない場合は LLM ジャッジによる評価を、客観スコアとコード上の判断の両方が重要な場合はハイブリッドな意思決定を支援します。

向いているユーザーと用途

eval skill が最も効果を発揮するのは、AgentHub 型のマルチエージェントワークフローを使う開発者です。つまり、1 つのタスクに対して複数のエージェントブランチや worktree を作り、最後に比較する流れです。「どのエージェントが最速の実装を作ったか」「どのパッチが最も安全にマージできるか」「どの成果が元のタスクを最もよく満たしているか」といった問いに、再現性のある答えを出したいときに役立ちます。一方で、AgentHub のセッション構造、エージェントの結果投稿、ブランチ、diff を前提にしているため、単体のベンチマークフレームワークとしてはあまり向いていません。

汎用プロンプトとの違い

汎用プロンプトでも、LLM に出力同士を比較させることはできます。しかし eval は、評価の進め方を具体化します。利用可能であればエージェントごとにメトリクスコマンドを実行し、ジャッジモードでは各エージェントの diff と結果投稿を確認します。重要な違いは、この skill が自由な意見ではなく、完了済みの AgentHub 成果物を軸にアシスタントを動かす点です。そのため推測が減り、ランキングを後から検証しやすくなります。

導入前に確認したいこと

eval をインストールしたり本格的に使ったりする前に、エージェントの結果が想定される AgentHub の場所に保存されていること、エージェントのブランチや worktree がまだ参照できることを確認してください。メトリクスモードでは、動作する評価コマンド、メトリクス名、そして latency のように低いほど良いのか、スコアのように高いほど良いのかという方向づけも必要です。この skill のリポジトリパスには SKILL.md しか含まれていないため、挙動の大部分は skill ディレクトリ内の補助ファイルではなく、コマンドの指示内容で定義されています。

eval skill の使い方

eval のインストールとリポジトリ確認

通常使っている skill インストーラーで、GitHub の skill リポジトリからインストールします。例:

npx skills add alirezarezvani/claude-skills --skill eval

インストール後は、まず engineering/agenthub/skills/eval/SKILL.md を読んでください。この skill ディレクトリにはローカルの rules/、resources/、references/、scripts/ フォルダーがないため、SKILL.md が信頼すべき情報源です。なお、skill 本文ではメトリクスモード用に scripts/result_ranker.py が参照されています。メトリクスベースのランキングに依存する前に、自分の AgentHub 環境全体でそのスクリプト、または同等の評価ランナーが提供されているか確認してください。

基本的な eval 実行コマンド

エージェントがセッションを完了したあとに、次のコマンドを使います。

/hub:eval
/hub:eval 20260317-143022
/hub:eval --judge

/hub:eval は最新セッションを評価します。セッション ID を渡すと、特定の実行を対象にできます。--judge は LLM ジャッジモードを強制します。メトリクスコマンドがない、信頼できない、または正しさを捉えるには狭すぎる場合に便利です。

eval をうまく機能させる入力

メトリクスモードでは、セッション ID、eval コマンド、メトリクスラベル、方向を指定または設定します。良い依頼は具体的です。

“Run /hub:eval 20260317-143022 using the configured benchmark. Rank by latency_ms, lower is better, and call out any agent whose result fails tests.”

LLM ジャッジモードでは、アシスタントが base branch、エージェントブランチ、git diff、そして .agenthub/board/results/agent-1-result.md のような結果投稿にアクセスできるようにしてください。より良いプロンプトには、タスクの目的と優先順位を含めます。

“Use /hub:eval --judge for the latest session. Prioritize correctness first, then minimal risk, then simplicity. Treat changed public APIs as risky unless justified in the result post.”

信頼できるランキングのための実践的ワークフロー

すべてのエージェントが結果を投稿し、各ブランチが diff を取れる程度に整ってから eval を実行してください。ランタイム、テスト数、精度、サイズ、ベンチマーク出力のような客観スコアがあるタスクでは、まずメトリクスモードから始めます。設計、リファクタリング、バグ修正、またはメトリクスが攻略されやすいタスクでは、LLM ジャッジモードを使います。重要なマージ判断では、勝者だけでなく、主なリスク、diff に基づく根拠、同点をどう扱ったかの前提も報告するよう eval に依頼するとよいでしょう。

eval skill FAQ

eval は Model Evaluation 用か、エージェント結果のランキング用か

この eval skill は主に、汎用的な Model Evaluation スイートではなく、AgentHub のエージェント結果を順位付けするためのものです。モデルが生成した作業を評価することはできますが、比較の単位はエージェントが完了したセッション結果です。つまり、そのブランチ、diff、結果メモ、そして必要に応じて worktree 内で実行されるメトリクスコマンドが対象になります。

メトリクスモードとジャッジモードの使い分け

成功を一貫して測定できる場合は、メトリクスモードを使います。たとえば、合格したテスト数、ベンチマークスコア、レイテンシ、メモリ、精度、バンドルサイズ、その他の数値出力です。実際に問いたいことが「そのパッチは正しく、保守しやすく、安全か」である場合は、ジャッジモードを使います。メトリクスが目標の一部しか捉えていないなら、ハイブリッドな読み方を依頼してください。つまり、メトリクスで順位付けしつつ、diff から正しさやリグレッションの懸念を指摘してもらいます。

初心者でも eval skill を使えるか

AgentHub のセッションという考え方をすでに理解しているなら、初心者でも eval を使えます。コマンドの表面積は小さいものの、評価品質はリポジトリの状態に大きく左右されます。具体的には、ブランチ、worktree、結果投稿、設定済みの eval コマンドです。これらの成果物が欠けていると、初心者にはランキングが分かりにくかったり、不完全に見えたりする可能性があります。

eval が向いていない場面

エージェントがまだ完了していない場合、結果が 1 つしかない場合、またはアシスタントが diff や結果ファイルにアクセスできない場合は、eval を使うべきではありません。また、周辺ワークフローを調整しない限り、広範なモデルベンチマーク、プロンプトのリーダーボード作成、オフラインデータセット評価にも適していません。そうした用途には、専用の評価ハーネスのほうが適切です。

eval skill を改善する方法

明確な基準で eval の結果を良くする

品質を最も大きく引き上げるのは、明確なランキング方針です。eval に、何を最重視するかを伝えてください。正しさ、テスト通過、性能、シンプルさ、セキュリティ、互換性、コード変更量の少なさなどです。「一番良いものを選んで」のような曖昧な依頼は避けましょう。代わりに、次のように依頼します。「正しさを最優先にエージェントを順位付けしてください。同点なら、変更ファイルが少なく、新しい依存関係がないものを優先してください。未検証の前提があれば明記してください。」

よくある eval の失敗を防ぐ

よくある失敗には、誤解を招くメトリクスで順位付けする、失敗するエッジケースを見落とす、古いブランチを比較する、タスクを解決していない小さな diff を過大評価する、といったものがあります。評価前に base branch、セッション ID、メトリクスの方向、タスクの目的を確認することで防げます。ジャッジモードでは、特定の diff と結果投稿にひもづいた、根拠のあるランキングを求めてください。

最初のランキングのあとに反復する

最初の eval 出力は、意思決定のドラフトとして扱います。勝者が意外に見える場合は、争点になっている基準に絞って再評価を依頼します。たとえば “Re-evaluate only the top two agents for regression risk,” や “Explain whether agent-2’s faster metric comes from skipping required behavior.” のように聞きます。これにより、エージェントセッション全体をやり直さずに、eval ワークフローを実務的に進められます。

自分のワークフロー向けに skill を強化する

AgentHub 環境を運用しているなら、結果投稿フォーマットを標準化し、メトリクス名を一貫させ、eval コマンドを決定的にすることで eval を改善できます。何を正しさとみなすか、どのテストを必ず通すべきか、どのリスクがマージを妨げるかについて、プロジェクト固有のガイダンスを追加してください。この skill はコンパクトなので、日常的に eval をどれだけ信頼できるかは、セッション、ブランチ、メトリクスに関するローカルな運用ルールに大きく左右されます。