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. 작업 정의
작업당 하나씩 YAML 파일을 tasks/ 디렉토리에 생성합니다:
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 │ 45초 │ 100% │
│ aider │ 2/3 │ $0.08 │ 38초 │ 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: |
이 구현이 지수 백오프를 올바르게 처리하고 있나요?
확인할 사항: 최대 재시도 횟수, 증가하는 지연 시간, 지터.
모범 사례
- 실제 작업 부하를 대표하는 3-5개의 작업으로 시작하세요. 장난감 예제는 피하세요.
- 에이전트당 최소 3회 시도를 실행하여 변동성을 포착하세요. 에이전트는 비결정적입니다.
- 작업 YAML에서 커밋을 고정하여 며칠/몇 주에 걸쳐 결과를 재현할 수 있도록 하세요.
- 작업당 최소 하나의 결정적 심사(테스트, 빌드)를 포함하세요. LLM 심사는 노이즈를 추가합니다.
- 통과율과 함께 비용도 추적하세요. 10배 비용의 95% 에이전트가 항상 올바른 선택은 아닙니다.
- 작업 정의에 버전을 지정하세요. 이는 테스트 픽스처이며 코드처럼 취급해야 합니다.