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
每次執行：
- 從指定的提交建立一個新的 Git worktree
- 將提示交給代理人
- 執行判斷標準
- 記錄通過/失敗、成本和時間
3. 比較結果
產生比較報表：
agent-eval report --format table
Task: 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 作為判斷器）
judge:
- type: llm
prompt: |
這個實作是否正確處理了指數退避？
檢查：最大重試次數、遞增延遲、抖動。
最佳實踐
- 從 3-5 個任務開始，代表您的實際工作負載，而非玩具範例
- 每個代理人至少執行 3 次，以捕捉變異性 — 代理人是非確定性的
- 在任務 YAML 中鎖定提交，使結果在數天/數週內可重現
- 每個任務至少包含一個決定性判斷器（測試、建置）— LLM 判斷器會增加雜訊
- 同時追蹤成本與通過率 — 成本高 10 倍但通過率 95% 的代理人可能並非正確選擇
- 對任務定義進行版本控制 — 它們是測試裝置，需將其視為程式碼