agent-eval

agent-eval の概要

agent-eval は、コーディングエージェントを同じタスクで横並びにベンチマークし、合格率、コスト、時間、一貫性で結果を比較するための skill です。Claude Code、Aider、Codex、あるいは別の agent を実際の repo で採用すべきか判断したいときに、agent-eval skill は、好みの議論を再現可能な根拠に変えるのに役立ちます。

この skill は、単なる「とりあえず prompt を投げて様子を見る」テストではなく、公平な比較が必要なチームやヘビーユーザーに最適です。実際にやるべきことは、タスクを一度定義し、同じベースラインで複数の agent を走らせ、制約条件の中でどれが最もよく機能するかを見極めることです。

agent-eval が役立つ理由

agent-eval の核となる価値は、同じ repo、同じタスク、同じ成功判定、分離された worktree という制御された比較にあります。そのため、場当たり的な試行や単発の prompt よりも、結果を信頼しやすくなります。

どんなときにこの skill が向いているか

agent-eval skill は、次のような目的で使うと効果的です。

• ワークフローを標準化する前に agent を比較したい
• model の更新で結果が変わったか確認したい
• 自分の codebase とルールの上で性能を試したい
• チーム内の意思決定や調達判断のための根拠を集めたい

向いていない場合

単に 1 回の coding 回答が欲しいだけなら、普通の prompt のほうが簡単です。agent-eval が特に価値を発揮するのは、再現性、評価基準、速度・品質・コストのトレードオフを重視するときです。

agent-eval skill の使い方

skill をインストールして中身を確認する

agent-eval の install では、repo から skill を追加し、まず core の skill file を確認します。
npx skills add affaan-m/everything-claude-code --skill agent-eval

次に SKILL.md と、ワークフローで使う関連コンテキストを開いてください。この repository では、主な情報源は skill file そのものです。そのため、install するかどうかの判断は、その task モデルが自分の評価プロセスに合っているかに強く左右されます。

漠然とした目的を、使える task に落とし込む

agent-eval の使い方は、具体的な task、対象 repo、客観的なチェックを定義したときに最も機能します。弱い prompt は「refactoring に強い agent をテストする」です。より強い prompt は次のような形です。

• src/http_client.py に retry logic を追加する
• reproducibility のために repo を commit に固定する
• 変更してよい file を明示する
• pytest や grep のような judge command を定義する
• 重要であれば、許容できる最大時間やコストを明記する

task を自動で検証しやすいほど、比較の価値は高くなります。

推奨ワークフロー

実践的な agent-eval の進め方は次のとおりです。

1. 本当に判断したいことを反映する task を 1 つ選ぶ。
2. repo path、files、prompt、judges を含めて YAML で task を書く。
3. 同じ task に対して複数の agent を実行する。
4. 出力品質、実行時間、コストを比較する。
5. 最終判断の前に、別の task でもう一度試す。

この skill は git worktree による isolation を使うため、agent 同士が変更を上書きし合うのを防ぎやすく、並列での評価も見やすくなります。

先に読むべき files

まず確認するのは次の項目です。

• task format と workflow のための SKILL.md
• テストや判定ルールを定義している repo-local な files
• YAML の task 定義で指定した files

agent-eval を Model Evaluation 用に評価する場合は、より大きな benchmark に進む前に、task と judges が十分に安定していて、比較可能な run を再現できるかを確認してください。

agent-eval skill の FAQ

agent-eval は coding-agent ベンチマーク専用ですか？

はい、基本的にはその用途です。この skill は、一般的な prompt テストや広範な LLM ベンチマークではなく、coding agent を head-to-head で比較するために設計されています。

使うのに Docker は必要ですか？

必要ありません。skill は git worktree の isolation を使うので、container の追加負荷なしで run を分離できます。

初心者向けですか？

task を明確に定義でき、command-line の workflow を回せるなら扱いやすいです。逆に、セットアップ不要のワンクリック評価器を求める人にはあまり向きません。

通常の prompt と何が違いますか？

通常の prompt は、1 つの agent に 1 つの task を解かせます。agent-eval skill は、複数の agent に同じ task を固定された judges で解かせることで、より少ない bias で結果を比較できるようにします。

agent-eval skill を改善する方法

より強い task 定義を使う

agent-eval でよい結果を得るには、入力が明確で、編集範囲がはっきりしていて、客観的な judge がある task が最適です。prompt があまりに自由度高く曖昧だと、比較結果は agent の品質よりも解釈の違いを測るものになってしまいます。

実際の成功基準を反映する judges を追加する

自分たちのチームが実際に変更を検証するときのやり方に近いチェックを優先してください。たとえば、tests、lint、file diff、pattern check などです。judge が緩すぎると弱い解決策でも良く見え、逆に厳しすぎると壊れやすい小細工を評価してしまうことがあります。

答えではなく benchmark を改善する

ある agent が間違った理由で勝ったなら、結論を急ぐ前に task を見直してください。files の範囲を絞り、受け入れ条件を明確にし、commit を固定することで、agent-eval skill が毎回同じ対象を測れるようにします。

よくある失敗パターンに注意する

最も多いミスは、曖昧な prompt、不一致な judges、そして公平な比較には大きすぎる task です。agent-eval をよりよく使うには、最初の benchmark を小さく、再現可能で、実際に agent にやってほしい作業を代表するものに保ってください。