Agent Eval Skill
一個輕量級 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
任務：add-retry-logic（每個代理執行 3 次）
┌──────────────┬───────────┬────────┬────────┬─────────────┐
│ 代理 │ 通過率 │ 成本 │ 時間 │ 一致性 │
├──────────────┼───────────┼────────┼────────┼─────────────┤
│ 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% 通過率的代理可能不是最佳選擇
- 對你的任務定義進行版本管理——它們是測試裝置，應視為程式碼對待