eval-harness

Eval Harness Skill

Claude Code 세션을 위한 공식 평가 프레임워크로, 평가 중심 개발(EDD) 원칙을 구현합니다.

활성화 시점

• AI 지원 워크플로우를 위한 평가 중심 개발(EDD) 설정 시
• Claude Code 작업 완료를 위한 패스/실패 기준 정의 시
• pass@k 메트릭으로 에이전트 신뢰성 측정 시
• 프롬프트 또는 에이전트 변경을 위한 회귀 테스트 스위트 생성 시
• 모델 버전 간 에이전트 성능 벤치마킹 시

철학

평가 중심 개발(Eval-Driven Development)은 평가를 "AI 개발의 단위 테스트"로 취급합니다:

• 구현 전에 기대 동작을 정의합니다
• 개발 중 지속적으로 평가를 실행합니다
• 각 변경 사항에 대한 회귀를 추적합니다
• 신뢰성 측정을 위해 pass@k 메트릭을 사용합니다

평가 유형

능력 평가(Capability Evals)

Claude가 이전에 할 수 없었던 작업을 수행할 수 있는지 테스트합니다:

[능력 평가: feature-name]
작업: Claude가 수행해야 할 작업 설명
성공 기준:
  - [ ] 기준 1
  - [ ] 기준 2
  - [ ] 기준 3
예상 출력: 기대 결과 설명

회귀 평가(Regression Evals)

변경 사항이 기존 기능을 손상시키지 않는지 확인합니다:

[회귀 평가: feature-name]
기준: SHA 또는 체크포인트 이름
테스트:
  - existing-test-1: 통과/실패
  - existing-test-2: 통과/실패
  - existing-test-3: 통과/실패
결과: X/Y 통과 (이전 Y/Y 통과)

채점기 유형

1. 코드 기반 채점기(Code-Based Grader)

코드를 사용한 확정적 검증:

# 파일에 예상 패턴이 포함되어 있는지 확인
grep -q "export function handleAuth" src/auth.ts && echo "통과" || echo "실패"

# 테스트 통과 여부 확인
npm test -- --testPathPattern="auth" && echo "통과" || echo "실패"

# 빌드 성공 여부 확인
npm run build && echo "통과" || echo "실패"

2. 모델 기반 채점기(Model-Based Grader)

Claude를 사용하여 개방형 출력 평가:

[모델 채점기 프롬프트]
다음 코드 변경 사항을 평가하세요:
1. 문제를 해결했습니까?
2. 잘 구조화되었습니까?
3. 엣지 케이스가 처리되었습니까?
4. 오류 처리가 적절합니까?

점수: 1-5 (1=나쁨, 5=우수)
근거: [설명]

3. 인간 채점기(Human Grader)

수동 검토 플래그:

[인간 검토 필요]
변경 사항: 변경된 내용 설명
이유: 인간 검토가 필요한 이유
위험 수준: 낮음/중간/높음

메트릭

pass@k

"k번 시도 중 최소 1회 성공"

• pass@1: 첫 시도 성공률
• pass@3: 3회 시도 내 성공
• 일반적 목표: pass@3 > 90%

pass^k

"모든 k번 시도 성공"

• 신뢰성에 대한 더 높은 기준
• pass^3: 3회 연속 성공
• 중요 경로에 사용

평가 워크플로우

1. 정의 (코딩 전)

## 평가 정의: feature-xyz

### 능력 평가
1. 새 사용자 계정 생성 가능
2. 이메일 형식 검증 가능
3. 비밀번호를 안전하게 해시 가능

### 회귀 평가
1. 기존 로그인 여전히 작동
2. 세션 관리 변경 없음
3. 로그아웃 흐름 온전함

### 성공 메트릭
- pass@3 > 90% (능력 평가)
- pass^3 = 100% (회귀 평가)

2. 구현

정의된 평가를 통과하는 코드 작성.

3. 평가

# 능력 평가 실행
[각 능력 평가 실행, 통과/실패 기록]

# 회귀 평가 실행
npm test -- --testPathPattern="existing"

# 보고서 생성

4. 보고

평가 보고서: feature-xyz
========================

능력 평가:
  create-user:     통과 (pass@1)
  validate-email:  통과 (pass@2)
  hash-password:   통과 (pass@1)
  전체:            3/3 통과

회귀 평가:
  login-flow:      통과
  session-mgmt:    통과
  logout-flow:     통과
  전체:            3/3 통과

메트릭:
  pass@1: 67% (2/3)
  pass@3: 100% (3/3)

상태: 검토 준비 완료

통합 패턴

구현 전

/eval define feature-name

.claude/evals/feature-name.md에 평가 정의 파일 생성

구현 중

/eval check feature-name

현재 평가 실행 및 상태 보고

구현 후

/eval report feature-name

전체 평가 보고서 생성

평가 저장소

프로젝트에 평가 저장:

.claude/
  evals/
    feature-xyz.md      # 평가 정의
    feature-xyz.log     # 평가 실행 이력
    baseline.json       # 회귀 기준선

모범 사례

1. 코딩 전에 평가 정의 - 성공 기준에 대한 명확한 사고 강제
2. 자주 평가 실행 - 조기에 회귀 발견
3. 시간에 따른 pass@k 추적 - 신뢰성 추세 모니터링
4. 가능하면 코드 채점기 사용 - 확정적 > 확률적
5. 보안은 인간 검토 - 보안 검사를 완전히 자동화하지 마세요
6. 평가를 빠르게 유지 - 느린 평가는 실행되지 않음
7. 코드와 함께 평가 버전 관리 - 평가는 일급 산출물

예시: 인증 추가

## 평가: add-authentication

### 1단계: 정의 (10분)
능력 평가:
- [ ] 사용자가 이메일/비밀번호로 등록 가능
- [ ] 사용자가 유효한 자격 증명으로 로그인 가능
- [ ] 잘못된 자격 증명은 적절한 오류와 함께 거부
- [ ] 세션이 페이지 새로고침 후에도 지속
- [ ] 로그아웃 시 세션 삭제

회귀 평가:
- [ ] 공개 라우트 여전히 접근 가능
- [ ] API 응답 변경 없음
- [ ] 데이터베이스 스키마 호환

### 2단계: 구현 (가변적)
[코드 작성]

### 3단계: 평가
실행: /eval check add-authentication

### 4단계: 보고
평가 보고서: add-authentication
==============================
능력: 5/5 통과 (pass@3: 100%)
회귀: 3/3 통과 (pass^3: 100%)
상태: 출시 가능

로컬 프레임워크 유틸리티

기계적 유틸리티는 scripts/lib/eval-harness/에 포함됩니다:

node scripts/eval-harness.js example

• 캡슐(Capsule): 해시 연결 저널로, 5개 계보 및 로컬 무결성 검사를 포함합니다.
• 검사(Inspection): 소스 다이제스트, 검증된 변형 경로, 구문 경고를 제공합니다.
• 재생(Replay): 선언된 도구와 콘텐츠 주소 지정 픽스처를 사용합니다. 누락된 픽스처는 폐쇄적으로 실패합니다. SE3 이상은 재생에서 거부됩니다. 기록 모드는 등록된 구현을 호출하므로, 신뢰할 수 있는 함수만 등록하세요.
• 영수증(Receipt): 캡슐 및 아티팩트 바이트에 대한 오프라인 검증을 명명된 검사와 함께 제공합니다.
• 회고 준비(Retrospective preparation): node scripts/eval-harness.js capsule group <dir> [<dir> ...]는 선언된 하네스 버전에 따라 하나의 작업 패밀리에서 명시적으로 선택된 1~100개의 검증된 로컬 캡슐 스냅샷을 그룹화합니다. 반복된 스냅샷은 한 번만 계산됩니다. 충돌하는 ID 또는 유효하지 않은 캡슐은 전체 보고서를 거부합니다. 이는 읽기 전용 기록 계산이며, 새로운 롤아웃, 점수 또는 승격이 없습니다. 작고 조용한 캡슐을 사용하세요. 페이로드, 디렉터리 인수 및 원시 실행/캡슐 ID는 생략되지만, 작업 패밀리/버전 레이블은 그대로이며 다이제스트 참조는 연결 가능합니다. 공유하기 전에 검토하세요. 운영 검증은 보류 중입니다.

검증된 OS 격리 백엔드가 구현되지 않았으므로 모든 OS에서 후보 실행이 비활성화됩니다. gate run, runGate, runVariant, 직접 하위 프로세스 실행, 그리고 폐기된 효과 사전 로드는 gate.isolation_required로 거부됩니다. 신뢰 플래그나 호출자가 제공한 실행기로 이 거부를 우회할 수 없습니다. 예제는 이 거부를 기록하고 실행 또는 점수 없이 소스를 검사합니다.

정적 경고, 캡슐 영수증 또는 성공적인 유틸리티 테스트를 후보 격리 또는 승격 증거로 제시하지 마세요. 향후 게이트는 독립적으로 검토된 OS 경계, 보호된 검사기 및 감사 채널, 그리고 치명적 기준선 거부를 요구합니다. docs/architecture/eval-harness-frameworks.md를 참조하세요.

제품 평가 (v1.8)

단위 테스트만으로 동작 품질을 포착할 수 없을 때 제품 평가를 사용하세요.

채점기 유형

1. 코드 채점기 (확정적 단언)
2. 규칙 채점기 (정규식/스키마 제약 조건)
3. 모델 채점기 (LLM-as-judge 루브릭)
4. 인간 채점기 (모호한 출력에 대한 수동 판정)

pass@k 가이드

• pass@1: 직접 신뢰성
• pass@3: 통제된 재시도 하의 실용적 신뢰성
• pass^3: 안정성 테스트 (모든 3회 실행 통과 필수)

권장 임계값:

• 능력 평가: pass@3 >= 0.90
• 회귀 평가: 중요 릴리스 경로에 대해 pass^3 = 1.00

평가 안티패턴

• 알려진 평가 예제에 프롬프트 과적합
• 해피 패스 출력만 측정
• 통과율을 쫓느라 비용 및 지연 시간 드리프트 무시
• 릴리스 게이트에서 불안정한 채점기 허용

최소 평가 아티팩트 레이아웃

• .claude/evals/<feature>.md 정의
• .claude/evals/<feature>.log 실행 이력
• docs/releases/<version>/eval-summary.md 릴리스 스냅샷