mturac エージェント評価スキル
再現可能なタスクでコーディングエージェントをヘッドツーヘッドで比較するための軽量 CLI ツールです。「どのコーディングエージェントが最適か？」という比較はすべて感覚に頼りがちです — このツールはそれを体系化します。
起動タイミング
- 自分のコードベースでコーディングエージェント（OpenAI Codex、Aider、Codex など）を比較する
- 新しいツールやモデルを採用する前にエージェントパフォーマンスを測定する
- エージェントがモデルやツールを更新した際にリグレッションチェックを実行する
- チームにデータに基づいたエージェント選択の判断を提供する
インストール
注意: agent-eval はソースを確認した後、リポジトリからインストールしてください。
コアコンセプト
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" # 再現性のために特定コミットに固定
Git ワークツリー分離
各エージェント実行は独自の git ワークツリーを取得します — Docker 不要。これにより再現性の分離が提供され、エージェントが互いに干渉したりベースリポジトリを破壊したりしません。
収集メトリクス
| メトリクス | 測定内容 |
|---|---|
| 合格率 | エージェントはジャッジをパスするコードを生成できたか？ |
| コスト | タスクあたりの API 費用（利用可能な場合） |
| 時間 | 完了までのウォールクロック秒数 |
| 一貫性 | 繰り返し実行での合格率（例：3/3 = 100%） |
ワークフロー
1. タスクの定義
タスクごとに 1 つの YAML ファイルを持つ tasks/ ディレクトリを作成します：
mkdir tasks
# タスク定義を作成（上記のテンプレートを参照）
2. エージェントの実行
タスクに対してエージェントを実行します：
agent-eval run --task tasks/add-retry-logic.yaml --agent codex --agent aider --runs 3
各実行：
- 指定されたコミットから新しい git ワークツリーを作成
- エージェントにプロンプトを渡す
- ジャッジ基準を実行
- 合格・不合格、コスト、時間を記録
3. 結果の比較
比較レポートを生成します：
agent-eval report --format table
Task: add-retry-logic (3 runs each)
┌──────────────┬───────────┬────────┬────────┬─────────────┐
│ Agent │ Pass Rate │ Cost │ Time │ Consistency │
├──────────────┼───────────┼────────┼────────┼─────────────┤
│ codex │ 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: |
Does this implementation correctly handle exponential backoff?
Check for: max retries, increasing delays, jitter.
ベストプラクティス
- 3〜5 タスクから始める — おもちゃの例ではなく、実際のワークロードを代表するタスク
- エージェントごとに少なくとも 3 試行実行する — エージェントは非決定論的なので分散を把握する
- タスク YAML でコミットを固定する — 日や週をまたいで結果が再現可能になる
- タスクごとに少なくとも 1 つの決定論的ジャッジを含める（テスト、ビルド）— LLM ジャッジはノイズを加える
- 合格率と一緒にコストを追跡する — 10 倍のコストで 95% のエージェントが正しい選択でない場合もある
- タスク定義をバージョン管理する — それらはテストフィクスチャであり、コードとして扱う