Post

AI 코딩 에이전트 평가(Evals) — Anthropic Evals 프레임으로 회귀 잡기

Anthropic의 evals 프레임워크와 Claude Agent SDK를 활용해 AI 코딩 에이전트의 품질을 측정하고, 재현 가능한 골든셋과 회귀 게이트를 CI/CD에 통합하는 방법을 단계별로 안내한다.

AI 코딩 에이전트 평가(Evals) — Anthropic Evals 프레임으로 회귀 잡기

들어가며

AI 코딩 에이전트가 코드베이스에 개입하는 범위가 넓어질수록 조용히 쌓이는 문제가 있다. 프롬프트 한 줄을 바꾸거나, 모델이 업그레이드되거나, 새로운 도구 설정이 추가될 때마다 에이전트의 행동이 미묘하게 달라진다. 어제까지 완벽하게 작동하던 리팩터 로직이 오늘 갑자기 엉뚱한 코드를 생성한다. 이것이 AI 에이전트의 회귀(Regression)다.

소프트웨어 개발에서 회귀는 단위·통합 테스트로 잡는다. 하지만 AI 에이전트의 출력은 결정적(deterministic)이지 않다. 같은 입력에도 출력이 매번 달라질 수 있다. 기존 테스트 패러다임을 그대로 적용하면 실제 회귀를 놓치거나, 정상적인 출력 변동을 회귀로 오판하는 문제가 생긴다.

Anthropic은 이 문제를 evals(평가) 프레임워크로 접근한다. 이 글에서는 Anthropic의 evals 1차 자료를 바탕으로, AI 코딩 에이전트의 품질을 정량적으로 추적하는 방법을 정리한다. 골든셋 설계부터 CI/CD 회귀 게이트 통합까지, 독자가 자신의 팀에 즉시 도입할 수 있는 형태로 안내한다.

이 글은 AI 다중 에이전트 코드 리뷰 패턴과 Spec 기반 AI 코딩 가이드의 품질 측정 편이다. 에이전트를 빌드했다면, 그 에이전트가 퇴행하지 않는지 측정하는 것이 다음 단계다.

목차


Evals란 무엇인가 — AI 에이전트에게 테스트가 필요한 이유

Evals는 AI 모델이나 에이전트의 출력을 체계적으로 평가하는 테스트 스위트다. 소프트웨어의 단위 테스트가 함수의 입출력을 검증하듯, evals는 AI 에이전트의 출력 품질·일관성·정확성을 검증한다.

Anthropic의 “Demystifying Evals” 문서는 evals를 정의하면서 핵심 긴장을 짚는다: AI 시스템의 출력은 확률적이고, 정답이 하나가 아닌 경우가 많다. 그럼에도 불구하고 품질이 저하됐는지를 탐지하는 체계가 없으면 배포를 신뢰할 수 없다.1

AI 코딩 에이전트에서 evals가 필요한 이유는 세 가지다.

첫째, 모델 업그레이드. 모델 버전이 올라가면 일부 태스크의 출력 특성이 달라진다. 전반적 성능은 향상될 수 있지만, 특정 에지 케이스에서 오히려 퇴행할 수 있다. 업그레이드 전후를 같은 기준으로 측정하지 않으면 퇴행을 놓친다.

둘째, 프롬프트 변경. 시스템 프롬프트를 수정하거나 컨텍스트를 추가하면 다른 태스크의 동작에 의도치 않은 영향을 준다. 프롬프트 변경을 안전하게 롤아웃하려면 변경 전 기준선(baseline)과 비교해야 한다.

셋째, 도구 설정 변경. 에이전트에게 새로운 도구를 추가하거나 허용 범위를 바꾸면 에이전트의 전략 자체가 달라진다. 의도한 변화인지 의도치 않은 변화인지를 evals 없이는 구분하기 어렵다.

AI 에이전트의 “회귀”는 코드 오류가 아니라 행동 변화다. 기존 테스트로는 잡히지 않는다.


Anthropic Evals 프레임워크 — 핵심 개념 정리

Anthropic의 evals 프레임워크는 네 가지 핵심 요소로 구성된다.

Task (태스크)

평가할 구체적인 작업 단위다. “Python 함수에서 버그를 찾아라”, “이 YAML을 JSON으로 변환하라”, “이 PR diff에서 보안 취약점을 탐지하라” 등이 태스크다.

좋은 태스크의 조건:

  • 명확한 성공 기준: 성공/실패를 판단할 수 있는 기준이 존재한다
  • 실제 업무 반영: 에이전트가 실제로 처리하는 작업과 일치한다
  • 재현 가능성: 같은 입력으로 언제든 다시 실행할 수 있다

Grader (평가자)

에이전트의 출력을 점수화하는 컴포넌트다. 크게 세 가지 방식이 있다.

방식설명적합한 케이스
Exact Match정확한 문자열 일치코드 생성, JSON 변환 등 결정적 출력
LLM-as-judge다른 LLM이 출력을 평가코드 품질, 설명의 정확성 등 주관적 판단
Heuristic규칙 기반 검사형식 준수, 금지 패턴 포함 여부 등

Anthropic의 Eval Tool 문서는 LLM-as-judge 방식을 쓸 때 평가자 모델과 피평가 모델이 같은 계열일 경우 자기 편향(self-favoritism)이 생길 수 있음을 경고한다. 평가자 모델을 별도로 지정하거나 복수의 그레이더를 조합하는 것이 권장된다.2

Dataset (데이터셋)

태스크와 예상 출력(ground truth)의 모음이다. 데이터셋의 품질이 evals의 신뢰도를 결정한다.

좋은 데이터셋의 조건:

  • 실제 업무에서 발생하는 케이스를 대표한다
  • 에지 케이스와 경계값을 포함한다
  • 레이블(예상 출력)이 팀 내 합의를 거쳤다

Run (실행 환경)

동일한 데이터셋으로 여러 모델·프롬프트·설정을 비교하는 실험 단위다. Run 결과를 비교해 어느 설정이 더 나은지 판단한다.


Claude Agent SDK의 eval 지원 구조

Claude Agent SDK는 에이전트 워크플로우를 코드로 정의하고, 그 워크플로우를 평가하는 구조를 제공한다.3

SDK eval 지원의 핵심은 에이전트 실행의 추적 가능성(traceability)이다. 에이전트가 어떤 도구를 호출했는지, 어떤 순서로 작업을 처리했는지, 최종 출력이 무엇인지를 구조화된 형태로 기록한다. 이 기록이 있어야 “이번 실행이 기준선과 얼마나 달라졌는가”를 측정할 수 있다.

SDK에서 eval을 구성하는 기본 패턴:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
import anthropic

client = anthropic.Anthropic()

def run_coding_agent(task_input: str) -> dict:
    """에이전트를 실행하고 결과와 메타데이터를 반환한다."""
    messages = [{"role": "user", "content": task_input}]

    response = client.messages.create(
        model="claude-opus-4-7-20251101",
        max_tokens=4096,
        messages=messages,
        tools=[
            # 코딩 에이전트 도구 목록
        ]
    )

    return {
        "output": response.content,
        "stop_reason": response.stop_reason,
        "usage": response.usage.model_dump()
    }

def eval_bug_detection(golden_case: dict) -> dict:
    """버그 탐지 태스크에 대한 단일 eval 실행."""
    result = run_coding_agent(golden_case["input"])

    # Grader: 예상 버그 식별자가 출력에 포함되었는지 확인
    detected = any(
        bug_id in str(result["output"])
        for bug_id in golden_case["expected_bugs"]
    )

    return {
        "case_id": golden_case["id"],
        "passed": detected,
        "output": result["output"],
        "tokens_used": result["usage"]
    }

핵심 설계 원칙: 에이전트 실행 로직과 평가 로직을 분리한다. 같은 함수에 구현을 넣고 자기 평가를 하면 자기 편향이 생긴다.


골든셋 설계 — 재현 가능한 테스트 기준 만들기

골든셋(Golden Set)은 에이전트를 평가하기 위한 고품질 테스트 케이스 모음이다. “골든”이라는 이름은 이 케이스들이 팀이 합의한 정답 기준을 담고 있다는 의미다.

flowchart TD
    REAL["실제 업무 케이스\n수집"] --> FILTER["케이스 필터링\n(중복·모호성 제거)"]
    FILTER --> LABEL["Ground Truth\n레이블링 (팀 합의)"]
    LABEL --> GS["🏆 골든셋 v1"]
    GS --> RUN["회귀 게이트\nCI 실행"]
    RUN -->|"임계값 이상"| DEPLOY["✅ 배포 허용"]
    RUN -->|"임계값 미달"| BLOCK["❌ 배포 차단"]
    BLOCK --> ANALYZE["원인 분석"]
    ANALYZE --> FIX["모델·프롬프트\n수정"]
    FIX --> RUN
    DEPLOY --> MONITOR["프로덕션\n모니터링"]
    MONITOR -->|"새 실패 패턴 발견"| NEW["신규 케이스 추가"]
    NEW --> GS

    style DEPLOY fill:#69db7c,color:#000
    style BLOCK fill:#ff6b6b,color:#fff
    style GS fill:#74c0fc,color:#000

케이스 선정 기준

좋은 골든셋 케이스는 다음 세 가지를 균형 있게 포함한다.

① 해피 패스(Happy Path): 에이전트가 정상적으로 처리해야 하는 대표적 케이스. 전체 케이스의 60% 내외.

② 에지 케이스(Edge Case): 경계값·예외 입력·비정상 형식 등. 에이전트가 예외를 올바르게 처리하는지 검증한다. 전체의 30% 내외.

③ 회귀 케이스(Regression Case): 과거에 실패했던 케이스. 동일한 실패가 재발하지 않는지 확인한다. 전체의 10% 내외.

골든셋 스키마

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# golden_set.yaml 예시
cases:
  - id: "bug_null_ptr_001"
    category: "bug_detection"
    description: "Python에서 NoneType 접근 패턴 탐지"
    input: |
      다음 Python 코드에서 버그를 찾아라:

      def get_user_name(user):
          return user.profile.name
    expected_bugs:
      - "AttributeError"
      - "profile이 None일 수 있음"
      - "None 체크 누락"
    severity: "critical"
    tags: ["python", "null-safety", "happy-path"]

  - id: "refactor_nested_001"
    category: "refactoring"
    description: "3단계 이상 중첩된 if문 리팩터 — Early Return 패턴"
    input: |
      다음 코드를 Early Return 패턴으로 리팩터하라.
      [... 중첩 코드 ...]
    grader_type: "llm_judge"
    grader_criteria:
      - "Early Return 패턴이 적용됐는가"
      - "기능이 보존됐는가"
      - "중첩 깊이가 감소했는가"
    tags: ["python", "refactoring", "edge-case"]

레이블링 프로세스

Ground Truth 레이블은 반드시 팀 합의를 거쳐야 한다. 한 사람이 혼자 레이블링한 골든셋은 그 사람의 편향을 증폭시킨다.

레이블링 워크플로우:

  1. 케이스 초안 작성 (1명)
  2. 독립 검토 — 2명 이상이 예상 출력을 각자 작성
  3. 불일치 케이스 토론 및 합의
  4. 합의된 레이블로 골든셋 업데이트

불일치율이 높은 케이스는 태스크 자체가 모호하다는 신호다. 기준을 명확히 한 뒤 다시 레이블링하거나, 케이스를 제거한다.


회귀 게이트 구현 — CI/CD에 통합하기

회귀 게이트는 골든셋을 CI/CD 파이프라인에 삽입해, 일정 임계값 미만의 통과율이 나오면 배포를 차단하는 자동화 장치다.

기본 구조

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
import yaml
import json
import sys
from typing import List

def run_eval_suite(golden_set_path: str) -> dict:
    """골든셋 전체를 실행하고 결과를 집계한다."""
    with open(golden_set_path) as f:
        golden_set = yaml.safe_load(f)

    results = []
    for case in golden_set["cases"]:
        result = eval_case(case)
        results.append(result)
        status = "PASS" if result["passed"] else "FAIL"
        print(f"[{status}] {case['id']}")

    passed = sum(1 for r in results if r["passed"])
    total = len(results)

    return {
        "passed": passed,
        "failed": total - passed,
        "total": total,
        "pass_rate": passed / total if total > 0 else 0,
        "results": results
    }

def regression_gate(eval_results: dict, threshold: float = 0.85) -> bool:
    """
    임계값 미만이면 False(배포 차단)를 반환한다.
    임계값: 전체 케이스 중 통과해야 하는 최소 비율.
    """
    pass_rate = eval_results["pass_rate"]
    print(f"\n통과율: {pass_rate:.1%} (임계값: {threshold:.1%})")

    if pass_rate < threshold:
        print("❌ 회귀 감지 — 배포 차단")
        failed_cases = [
            r["case_id"] for r in eval_results["results"] if not r["passed"]
        ]
        print(f"실패 케이스: {', '.join(failed_cases)}")
        return False

    print("✅ 회귀 게이트 통과")
    return True

if __name__ == "__main__":
    results = run_eval_suite("golden_set.yaml")
    with open("eval_report.json", "w") as f:
        json.dump(results, f, ensure_ascii=False, indent=2)
    passed = regression_gate(results, threshold=0.85)
    sys.exit(0 if passed else 1)

GitHub Actions 통합

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# .github/workflows/eval-gate.yml
name: AI Agent Eval Gate

on:
  pull_request:
    paths:
      - 'agents/**'
      - 'prompts/**'
      - '.github/workflows/eval-gate.yml'

jobs:
  eval:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: pip install anthropic pyyaml

      - name: Run eval suite
        env:
          ANTHROPIC_API_KEY: $
        run: python eval_runner.py

      - name: Upload eval report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: eval-report
          path: eval_report.json

임계값 설정 가이드

임계값은 팀의 위험 허용 수준과 골든셋 크기에 따라 조정한다.

시나리오권장 임계값이유
초기 도입 (케이스 10개 이하)0.90 이상케이스 수가 적어 통계 노이즈가 큼
성숙 단계 (케이스 50–100개)0.85에지 케이스 포함 시 현실적 목표
핵심 경로 전용 (케이스 20개 내외)1.00핵심 기능은 100% 통과 강제

임계값을 낮추면 배포 차단 빈도가 줄지만 회귀를 놓칠 위험이 커진다. 골든셋이 충분히 커지기 전까지는 카테고리별 임계값을 별도로 관리하는 것이 낫다.


포스트모템에서 배운 교훈 — 2026-04-23 사례 분석

Anthropic이 2026년 4월 공개한 AI 코딩 에이전트 회귀 포스트모템은, 실제 배포 환경에서 에이전트 회귀가 어떤 방식으로 발생하고 어떻게 탐지됐는지를 서술한다.4

회귀가 통과한 지점들

포스트모템은 회귀가 어떤 단계를 통과해 사용자 환경까지 도달했는지를 솔직하게 짚는다. 구체 수치·시점은 원문에 위임하고, 이 글에서는 evals 설계에 시사하는 일반화된 패턴만 정리한다.

  1. 마이너 변경의 위험 과소평가 — “작은 변경”이라는 자체 판단이 평가 게이트를 건너뛰는 빌미가 될 수 있다.
  2. 품질이 아닌 인프라 메트릭에만 기댄 모니터링 — 응답 시간·토큰 수 같은 지표가 정상이어도 출력 품질은 별도 신호로 잡아야 한다.
  3. 내부 게이트 부재로 외부 피드백이 1차 탐지 채널이 되는 구조 — 사용자가 먼저 보고하면 그 시점에 이미 영향 반경이 넓어져 있다.

세 가지 핵심 교훈

교훈 1: 마이너 업데이트도 eval 대상이다

모델 버전 번호의 크기와 회귀 위험은 비례하지 않는다. “마이너 업데이트”라는 레이블은 배포 위험을 줄이지 않는다. 모든 모델 변경은 동일한 eval 스위트를 통과해야 한다.

교훈 2: 토큰 비용·레이턴시만으로는 품질을 측정할 수 없다

인프라 메트릭(응답 시간, 토큰 수, 오류율)이 정상이어도 출력 품질은 저하될 수 있다. 에이전트 품질은 태스크 완료 정확도를 별도로 측정해야 한다.

교훈 3: 골든셋은 살아 있는 문서여야 한다

포스트모템에서 회귀가 발생한 케이스 유형은 기존 골든셋에 포함되지 않았던 것이었다. 골든셋은 일회성 구성이 아니라, 새로운 실패 패턴이 발견될 때마다 업데이트되는 살아 있는 문서여야 한다.

포스트모템의 세부 수치(회귀 지속 시간, 영향 범위 등)는 Anthropic 공식 게시물을 직접 참조한다. 이 글에서는 수치 없이 교훈만 정리한다.


팀 도입 전략 — 단계별 실행 가이드

evals 도입은 한 번에 완성하는 것이 아니라 단계적으로 구축한다. 다음 4단계를 순서대로 진행한다.

Step 1: 태스크 인벤토리 (1주)

에이전트가 실제로 처리하는 태스크를 목록으로 만든다. 이 목록이 없으면 무엇을 평가해야 할지 알 수 없다.

1
2
3
4
태스크 인벤토리 체크리스트:
□ 에이전트가 처리하는 주요 태스크 유형 5-10개 나열
□ 각 태스크의 성공/실패 기준 초안 작성
□ 빈도·비즈니스 영향도 기준으로 우선순위 정렬

Step 2: 최소 골든셋 구성 (2주)

우선순위 상위 3개 태스크에 대해 각 5–10개 케이스를 구성한다. 총 15–30개의 케이스로 시작한다.

케이스 수가 적어도 괜찮다. 완벽한 골든셋을 기다리다 도입을 미루는 것보다, 15개 케이스로 시작해 빠르게 반복하는 것이 낫다.

Step 3: 로컬 eval 실행 환경 구성 (1주)

CI 통합 전에 로컬에서 먼저 실행할 수 있는 환경을 만든다. 개발자가 프롬프트를 수정하기 전에 로컬 eval을 돌려 영향을 확인하는 습관을 만드는 것이 목적이다.

1
2
3
4
5
6
7
8
# eval 실행 (로컬)
python eval_runner.py --golden-set golden_set.yaml --verbose

# 특정 카테고리만 실행
python eval_runner.py --golden-set golden_set.yaml --category bug_detection

# 이전 결과와 비교
python eval_runner.py --compare baseline_results.json

Step 4: CI 회귀 게이트 통합 (1주)

로컬 eval이 안정적으로 동작하면 GitHub Actions(또는 팀 CI 환경)에 통합한다. 프롬프트·에이전트 설정 파일이 변경된 PR에 자동으로 eval 스위트가 실행되도록 구성한다.

gantt
    title evals 도입 로드맵 (예시)
    dateFormat  YYYY-MM-DD
    section 준비
    태스크 인벤토리    :2026-06-01, 7d
    section 구축
    최소 골든셋 구성   :2026-06-08, 14d
    로컬 실행 환경     :2026-06-22, 7d
    section 자동화
    CI 게이트 통합     :2026-06-29, 7d
    section 운영
    골든셋 확장        :2026-07-06, 28d

지속적 관리: 골든셋 갱신 프로토콜

회귀 게이트가 작동하기 시작하면, 골든셋을 어떻게 갱신할지 프로토콜을 정한다.

트리거조치
프로덕션에서 새 실패 패턴 발견해당 패턴을 골든셋에 즉시 추가
분기별 태스크 인벤토리 검토새 태스크 추가, 구식 케이스 제거
골든셋 통과율이 장기간 100%케이스 난이도 상향 또는 에지 케이스 추가
팀 합의 없이 레이블 변경 시도PR 차단 — 레이블 변경은 반드시 리뷰 필요

마치며

AI 코딩 에이전트의 evals는 “있으면 좋은 것”이 아니라 “배포를 신뢰하기 위한 최소 요건”이다. 에이전트가 코드베이스에 깊이 개입할수록, 그 에이전트의 행동 변화를 탐지하지 못하는 위험이 커진다.

시작은 단순하게 한다. 태스크 인벤토리, 최소 골든셋, 통과율 임계값. 이 세 가지면 회귀 게이트의 첫 버전이 완성된다. 그 다음은 프로덕션에서 새로운 실패 패턴이 나올 때마다 케이스를 추가하면 된다.

완벽한 골든셋을 기다리는 동안, 회귀는 조용히 쌓인다.


참고

A등급 (본문 직접 인용 출처)

B등급 (방향성 참고용, 본문 직접 인용 없음)


관련 글:

  1. Anthropic, “Demystifying Evals” — Anthropic 엔지니어링 블로그. https://www.anthropic.com/engineering/demystifying-evals ↩︎

  2. Anthropic, Eval Tool 사용 가이드. https://docs.anthropic.com/en/docs/test-and-evaluate/eval-tool ↩︎

  3. Anthropic, Claude Agent SDK 문서. https://docs.anthropic.com/en/docs/claude-code/sdk ↩︎

  4. Anthropic Engineering, “An update on recent Claude Code quality reports” (April 23 postmortem), 2026-04. Claude Code 품질 저하 보고에 대한 원인·조치·교훈을 정리한 공식 포스트모템. https://www.anthropic.com/engineering/april-23-postmortem ↩︎

This post is licensed under CC BY 4.0 by the author.