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 워크트리 격리
각 에이전트 실행은 자체 git 워크트리를 사용합니다—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 워크트리를 생성합니다.
- 프롬프트를 에이전트에 전달합니다.
- 판정 기준을 실행합니다.
- 통과/실패, 비용, 시간을 기록합니다.
3. 결과 비교
비교 보고서를 생성합니다:
agent-eval report --format table
Task: add-retry-logic (각 3회 실행)
┌──────────────┬───────────┬────────┬────────┬─────────────┐
│ Agent │ 통과율 │ 비용 │ 시간 │ 일관성 │
├──────────────┼───────────┼────────┼────────┼─────────────┤
│ 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 판정기는 노이즈를 추가합니다.
- 통과율과 함께 비용을 추적하세요—95% 통과율의 에이전트라도 비용이 10배라면 올바른 선택이 아닐 수 있습니다.
- 태스크 정의에 버전을 관리하세요—이는 테스트 픽스처이므로 코드처럼 취급하세요.