agent-eval

Agent Eval スキル

コーディングエージェントを再現可能なタスクで直接比較するための軽量CLIツールです。「どのコーディングエージェントが最適か？」という比較は、これまで感覚に頼っていましたが、このツールはそれを体系化します。

使用すべきタイミング

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

インストール

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

基本概念

YAMLタスク定義

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

name: add-retry-logic
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

Task: add-retry-logic (各3回実行)
┌──────────────┬───────────┬────────┬────────┬─────────────┐
│ Agent        │ Pass Rate │ Cost   │ Time   │ Consistency │
├──────────────┼───────────┼────────┼────────┼─────────────┤
│ 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による判定）

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

ベストプラクティス

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

リンク

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