agent-eval

エージェント評価スキル

コーディングエージェントを再現可能なタスクで直接比較するための軽量CLIツールです。「どのコーディングエージェントが最適か」という比較は、これまで雰囲気で判断されがちでしたが、このツールはそれを体系化します。

いつアクティブにするか

• コーディングエージェント（Claude Code、Aider、Codexなど）を自分のコードベースで比較する場合
• 新しいツールやモデルを導入する前に、エージェントのパフォーマンスを測定する場合
• エージェントがモデルやツールを更新した際に、回帰チェックを実行する場合
• チーム向けにデータに基づいたエージェント選定の意思決定を行う場合

インストール

注意: agent-evalはソースコードを確認した上で、そのリポジトリからインストールしてください。

コアコンセプト

YAMLタスク定義

タスクを宣言的に定義します。各タスクは、何を行うか、どのファイルを編集するか、成功をどう判断するかを指定します。

name: リトライロジックの追加
description: HTTPクライアントに指数バックオフリトライを追加
repo: ./my-project
files:
  - src/http_client.py
prompt: |
  すべてのHTTPリクエストに指数バックオフを用いたリトライロジックを追加してください。
  最大リトライ回数は3回。初期遅延は1秒、最大遅延は30秒。
judge:
  - type: pytest
    command: pytest tests/test_http_client.py -v
  - type: grep
    pattern: "exponential_backoff|retry"
    files: src/http_client.py
commit: "abc1234"  # 再現性のために特定のコミットに固定

Git Worktreeによる分離

各エージェントの実行は、独自のgit worktree上で行われます。Dockerは不要です。これにより、エージェント間の干渉やベースリポジトリの破損を防ぎ、再現性のある分離環境を提供します。

収集されるメトリクス

メトリクス	測定内容
合格率	エージェントが判定をパスするコードを生成したか
コスト	タスクあたりのAPI使用料（利用可能な場合）
時間	完了までの実時間（秒）
一貫性	複数回実行での合格率（例：3/3 = 100%）

ワークフロー

1. タスクを定義する

tasks/ディレクトリを作成し、タスクごとにYAMLファイルを配置します。

mkdir tasks
# タスク定義を記述（上記テンプレートを参照）

2. エージェントを実行する

タスクに対してエージェントを実行します。

agent-eval run --task tasks/add-retry-logic.yaml --agent claude-code --agent aider --runs 3

各実行では以下の処理が行われます。

1. 指定されたコミットから新しいgit worktreeを作成
2. プロンプトをエージェントに渡す
3. 判定基準を実行
4. 合格/不合格、コスト、時間を記録

3. 結果を比較する

比較レポートを生成します。

agent-eval report --format table

タスク: add-retry-logic (各3回実行)
┌──────────────┬───────────┬────────┬────────┬─────────────┐
│ Agent        │ 合格率    │ コスト │ 時間   │ 一貫性      │
├──────────────┼───────────┼────────┼────────┼─────────────┤
│ claude-code  │ 3/3       │ $0.12  │ 45s    │ 100%        │
│ aider        │ 2/3       │ $0.08  │ 38s    │  67%        │
└──────────────┴───────────┴────────┴────────┴─────────────┘

判定タイプ

コードベース（決定論的）

judge:
  - type: pytest
    command: pytest tests/ -v
  - type: command
    command: npm run build

パターンベース

judge:
  - type: grep
    pattern: "class.*Retry"
    files: src/**/*.py

モデルベース（LLM-as-judge）

judge:
  - type: llm
    prompt: |
      この実装は指数バックオフを正しく処理していますか？
      チェック項目: 最大リトライ回数、増加する遅延、ジッター。

ベストプラクティス

• 実際のワークロードを代表する3〜5個のタスクから始める — おもちゃの例ではなく
• エージェントごとに少なくとも3回の試行を実行する — エージェントは非決定論的であるため
• タスクYAMLでコミットを固定する — 日や週をまたいで結果が再現可能になるように
• タスクごとに少なくとも1つの決定論的な判定（テスト、ビルド）を含める — LLM判定はノイズを加える
• 合格率とコストを一緒に追跡する — コストが10倍の95%エージェントが常に最良の選択とは限らない
• タスク定義をバージョン管理する — これらはテストフィクスチャであり、コードとして扱う

リンク

• リポジトリ: github.com/joaquinhuigomez/agent-eval