Agent Eval スキル

カスタマイズ可能なタスク上でコーディング代理を直接比較するための軽量 CLI ツール。「どのコーディング代理が最適か？」という比較をデータドリブンで実施します。

使用するとき

• 独自のコードベース上でコーディング代理（Claude Code、Aider、Codex など）を比較したい
• 新しいツールやモデルを採用する前に代理のパフォーマンスを測定したい
• 代理がモデルやツールを更新したときに回帰テストを実行したい
• チームの意思決定を実データで支援したい

インストール

# pinned to v0.1.0 — latest stable commit
pip install git+https://github.com/joaquinhuigomez/agent-eval.git@6d062a2f5cda6ea443bf5d458d361892c04e749b

主要な概念

YAML タスク定義

宣言的にタスクを定義します。各タスクは実行内容、修正するファイル、成功の判定方法を指定します：

name: add-retry-logic
description: Add exponential backoff retry to the HTTP client
repo: ./my-project
files:
  - src/http_client.py
prompt: |
  Add retry logic with exponential backoff to all HTTP requests.
  Max 3 retries. Initial delay 1s, max delay 30s.
judge:
  - type: pytest
    command: pytest tests/test_http_client.py -v
  - type: grep
    pattern: "exponential_backoff|retry"
    files: src/http_client.py
commit: "abc1234"  # pin to specific commit for reproducibility

Git ワークツリー分離

各代理実行は独自の git ワークツリーを取得します（Docker 不要）。これにより再現可能な分離が提供され、代理間の干渉や元のリポジトリへの破壊がなくなります。

収集されるメトリクス

メトリクス	測定内容
通過率	代理が生成したコードが判定基準を通過しているか
コスト	タスク当たりの API 費用（利用可能な場合）
時間	完了に要した経過秒数
一貫性	反復実行全体での通過率（例：3/3 = 100%）

ワークフロー

1. タスクを定義

tasks/ ディレクトリを作成し、タスク定義を 1 ファイル 1 タスクの YAML で記述します：

mkdir tasks
# Write task definitions (see template above)

2. 代理を実行

タスクに対して代理を実行します：

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

各実行は以下のように進行します：

1. 指定されたコミットから新しい git ワークツリーを作成
2. プロンプトを代理に渡す
3. 判定基準を実行
4. 成功/失敗、コスト、時間を記録

3. 結果を比較

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

agent-eval report --format table

Task: add-retry-logic (3 runs each)
┌──────────────┬───────────┬────────┬────────┬─────────────┐
│ 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: |
      Does this implementation correctly handle exponential backoff?
      Check for: max retries, increasing delays, jitter.

ベストプラクティス

• 3～5 個のタスクから始める。おもちゃの例ではなく、実際のワークロードを代表するものを選択してください
• 各代理で最低 3 回の試行を実行。代理は非決定的であるため、バラつきを捉える必要があります
• タスク YAML にコミットをピン留め。結果が数日～数週間にわたって再現可能になります
• 各タスクに最低 1 つの決定的判定器を含める（テスト、ビルド）。LLM 判定器はノイズが増えます
• 成本と通過率を追跡。通過率 95% だが費用が 10 倍の代理は正しい選択ではないかもしれません
• タスク定義をバージョン管理。これらはテストフィクスチャであり、コードとして扱うべきです

リンク

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