Eval Harness 스킬
Claude Code 세션을 위한 공식 평가 프레임워크로, Eval 중심 개발(EDD) 원칙을 구현합니다.
활성화 시점
- AI 지원 워크플로에 Eval 중심 개발(EDD) 설정
- Claude Code 작업 완료의 통과/실패 기준 정의
- pass@k 메트릭으로 에이전트 신뢰성 측정
- 프롬프트 또는 에이전트 변경에 대한 회귀 테스트 스위트 생성
- 모델 버전 간 에이전트 성능 벤치마킹
철학
Eval 중심 개발은 평가를 "AI 개발의 단위 테스트"로 취급합니다:
- 구현 전에 예상 동작 정의
- 개발 중 지속적으로 평가 실행
- 각 변경 사항에 대한 회귀 추적
- 신뢰성 측정을 위해 pass@k 메트릭 사용
평가 유형
기능 평가
Claude가 이전에는 할 수 없었던 작업을 수행할 수 있는지 테스트:
[기능 평가: feature-name]
작업: Claude가 수행해야 할 작업 설명
성공 기준:
- [ ] 기준 1
- [ ] 기준 2
- [ ] 기준 3
예상 출력: 예상 결과 설명
회귀 평가
변경 사항이 기존 기능을 망가뜨리지 않는지 확인:
[회귀 평가: feature-name]
기준: SHA 또는 체크포인트 이름
테스트:
- 기존-테스트-1: 통과/실패
- 기존-테스트-2: 통과/실패
- 기존-테스트-3: 통과/실패
결과: X/Y 통과 (이전 Y/Y)
평가자 유형
1. 코드 기반 평가자
코드를 사용한 결정론적 검사:
# 파일에 예상 패턴이 포함되어 있는지 확인
grep -q "export function handleAuth" src/auth.ts && echo "통과" || echo "실패"
# 테스트 통과 여부 확인
npm test -- --testPathPattern="auth" && echo "통과" || echo "실패"
# 빌드 성공 여부 확인
npm run build && echo "통과" || echo "실패"
2. 모델 기반 평가자
Claude를 사용하여 개방형 출력 평가:
[모델 평가자 프롬프트]
다음 코드 변경을 평가하세요:
1. 명시된 문제를 해결합니까?
2. 잘 구조화되었습니까?
3. 엣지 케이스가 처리되었습니까?
4. 오류 처리가 적절합니까?
점수: 1-5 (1=나쁨, 5=우수)
근거: [설명]
3. 사람 평가자
수동 검토 플래그 지정:
[사람 검토 필요]
변경: 변경된 내용 설명
이유: 사람 검토가 필요한 이유
위험 수준: 낮음/중간/높음
메트릭
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 # 회귀 기준
모범 사례
- 코딩 전에 평가 정의 - 성공 기준에 대한 명확한 사고 강제
- 자주 평가 실행 - 조기에 회귀 발견
- pass@k 추적 - 신뢰성 추세 모니터링
- 가능하면 코드 평가자 사용 - 결정론적 > 확률론적
- 보안에 대해서는 사람 검토 - 보안 검사를 완전히 자동화하지 않음
- 평가를 빠르게 유지 - 느린 평가는 실행되지 않음
- 코드와 함께 평가 버전 관리 - 평가는 일급 아티팩트
예시: 인증 추가
## 평가: 인증-추가
### 1단계: 정의 (10분)
기능 평가:
- [ ] 사용자가 이메일/비밀번호로 등록 가능
- [ ] 사용자가 유효한 자격 증명으로 로그인 가능
- [ ] 잘못된 자격 증명은 적절한 오류와 함께 거부됨
- [ ] 페이지 새로고침 시 세션 유지
- [ ] 로그아웃 시 세션 삭제
회귀 평가:
- [ ] 공개 경로 여전히 접근 가능
- [ ] API 응답 변경 사항 없음
- [ ] 데이터베이스 스키마 호환 가능
### 2단계: 구현 (상이)
[코드 작성]
### 3단계: 평가
실행: /eval check 인증-추가
### 4단계: 보고
평가 보고서: 인증-추가
==============================
기능: 5/5 통과 (pass@3: 100%)
회귀: 3/3 통과 (pass^3: 100%)
상태: 출시 준비 완료