에이전트 평가 하네스(Eval Harness) 구축 가이드 — "느낌"이 아니라 "숫자"로 신뢰성을 증명하기

시리즈 2편. 1편 하네스 엔지니어링 입문에서 우리는 제약·도구·피드백 루프로 에이전트를 둘러싸야 한다고 이야기했습니다. 이번 글은 그 중 피드백 루프의 심장, 평가 하네스를 다룹니다.

들어가며: "어제보다 나아졌나요?"

프롬프트 한 줄 바꾸고, 도구 하나 추가하고, 모델을 Sonnet에서 Opus로 올렸습니다. 에이전트가 더 좋아졌을까요? 더 나빠졌을까요?

"느낌상 좋아진 것 같아요"로 답하는 팀은 곧 프로덕션에서 무너집니다. 평가 하네스가 없으면 개선과 회귀를 구분할 수 없기 때문입니다.

평가 하네스란, 에이전트의 동작을 재현 가능한 방식으로 측정하고 회귀를 잡아내는 자동화된 테스트 인프라입니다.

 

전통 소프트웨어의 단위 테스트와 비슷하지만, 출력이 비결정적이라는 점에서 본질적으로 다릅니다.

---

평가 하네스의 4가지 구성 요소

구성 요소	역할	전통 SW 비슈
데이터셋(Dataset)	입력 + 기대 동작	테스트 케이스
러너(Runner)	에이전트를 격리 환경에서 실행	테스트 러너
채점기(Scorer)	결과를 점수로 변환	assert 문
대시보드(Dashboard)	시계열 추적 + 회귀 알림	CI 리포트

---

1️⃣ 데이터셋 — 가장 중요하고 가장 소홀히 다뤄지는 부분

좋은 eval 데이터셋의 3가지 원칙:

• 다양성(Diversity) — 쉬운 케이스 60%, 어려운 케이스 30%, 엣지 케이스 10%
• 현실성(Realism) — 합성 데이터보다 프로덕션 로그에서 추출한 실제 케이스가 훨씬 강력
• 계층화(Stratification) — 기능별·난이도별 태깅으로 회귀 위치를 좁힐 수 있어야 함

# 좋은 eval case 예시
{
  "id": "refactor-001",
  "category": "code_refactor",
  "difficulty": "medium",
  "input": "Extract the validation logic in user_service.py into a separate module",
  "repo_snapshot": "fixtures/user_service_v1/",
  "expected": {
    "must_pass_tests": ["test_user_validation"],
    "must_not_break": ["test_user_create", "test_user_update"],
    "files_modified_max": 3
  },
  "tags": ["refactor", "python", "imports"]
}

핵심 팁: 버그 리포트가 들어올 때마다 eval 케이스로 박제하세요. 한 번 잡은 회귀는 다시 일어나지 않아야 합니다.

---

2️⃣ 러너 — 격리, 재현, 병렬화

async def run_eval(case, agent_config):
    with isolated_sandbox(case.repo_snapshot) as sandbox:
        trace = await agent.run(
            task=case.input,
            workspace=sandbox.path,
            max_steps=50,
            max_cost_usd=2.0,
            seed=42,  # 가능한 경우 결정성 확보
        )
    return EvalResult(case_id=case.id, trace=trace, sandbox_diff=sandbox.diff())

필수 요건: 격리된 작업 공간, 비용/스텝 상한, 전체 트레이스 저장, 병렬 실행.

---

3️⃣ 채점기 — 3가지 레이어를 조합하라

평가는 단일 점수가 아닙니다. 저렴하고 확실한 것부터, 비싸고 모호한 것까지 계층적으로 쌓습니다.

🎯 채점 피라미드

레이어	비용	신뢰도	예시
L1: 결정적 검증	매우 낮음	매우 높음	테스트 통과? 컴파일됨? 스키마 일치?
L2: 휴리스틱	낮음	중간	파일 수정 개수, 토큰 사용량, 금지 패턴 미사용
L3: LLM-as-judge	높음	낮음~중간	"코드 품질이 적절한가?", "설명이 명확한가?"

중요한 원칙: L1으로 잡을 수 있으면 절대 L3을 쓰지 마세요. LLM 채점기는 비싸고, 불안정하며, 자체 편향이 있습니다.

def score_refactor_case(result, case):
    scores = {}
    # L1: 무조건 통과해야 하는 것
    scores["tests_pass"] = run_tests(result.sandbox, case.expected.must_pass_tests)
    scores["no_regression"] = run_tests(result.sandbox, case.expected.must_not_break)
    # L2: 휴리스틱
    scores["files_within_budget"] = len(result.modified_files) <= case.expected.files_modified_max
    # L3: LLM judge (선택적)
    scores["code_quality"] = await llm_judge(
        rubric="단일 책임 원칙 준수, 명확한 네이밍",
        diff=result.sandbox.diff()
    )
    return scores

LLM-as-judge의 함정 피하기

• ❌ 점수 1~10을 직접 묻지 마세요 → LLM은 6~8 사이만 답합니다
• ✅ A/B 페어 비교를 시키거나, 명확한 루브릭(체크리스트) 을 주세요
• ✅ Judge 모델은 피평가 모델과 다른 모델을 쓰세요 (자기 편향 방지)
• ✅ Judge 자체도 메타 평가셋으로 검증해야 합니다

---

4️⃣ 대시보드 — 회귀를 즉시 알아차리기

대시보드가 보여줘야 할 것:

• 카테고리별 통과율 (전체가 아니라 분해된 점수)
• 회귀 알림 (이전 빌드 대비 N% 이상 하락 시 슬랙)
• 실패 케이스의 트레이스 링크 (디버깅까지 1클릭)
• 비용과 지연시간 (정확도가 같다면 더 싸고 빠른 게 이김)

---

평가 하네스 구축 로드맵

1주차: 프로덕션 로그에서 20개 케이스 추출 + L1 채점기
2주차: CI에 통합, 매 PR마다 자동 실행
3주차: 카테고리 태깅, 대시보드 구축
4주차: 50개로 확장, LLM judge 추가, 메타 평가
이후: 버그 리포트마다 케이스 추가, 분기마다 데이터셋 리뷰

작게 시작하세요. 20개의 잘 큐레이팅된 케이스가 2,000개의 합성 데이터보다 훨씬 강력합니다.

---

마치며: Eval은 제품이다

많은 팀이 평가 하네스를 "있으면 좋은 도구"로 취급하지만, 성숙한 AI 팀에서는 eval 데이터셋 자체가 가장 중요한 자산입니다. 모델은 갈아끼울 수 있지만, 6개월간 큐레이팅한 1,000개의 골든 케이스는 갈아끼울 수 없습니다.

"측정할 수 없으면 개선할 수 없다." — 피터 드러커

비결정적 시스템에서는 이 격언이 두 배로 무겁습니다.

 

다음 글에서는 도구 설계 베스트 프랙티스 — 어떤 tool spec이 에이전트를 똑똑해 보이게 만드는지 — 를 다루겠습니다.

---

#AI에이전트 #EvalHarness #LLMOps #AgentEvaluation #하네스엔지니어링