eval-harness

Eval Harness Skill

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

활성화 시점

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

철학

평가 주도 개발은 평가를 "AI 개발의 유닛 테스트"로 취급합니다:

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

평가 유형

능력 평가

Claude가 이전에 하지 못했던 작업을 수행할 수 있는지 테스트:

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

회귀 평가

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

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

채점기 유형

1. 코드 기반 채점기

코드를 사용한 결정론적 검사:

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

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

# 빌드 성공 여부 확인
npm run build && echo "PASS" || echo "FAIL"

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. 평가

# 능력 평가 실행
[각 능력 평가 실행, PASS/FAIL 기록]

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

# 보고서 생성

4. 보고

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

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

회귀 평가:
  login-flow:      PASS
  session-mgmt:    PASS
  logout-flow:     PASS
  전체:           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. 코드와 함께 평가 버전 관리 - 평가는 일급 아티팩트

예시: 인증 추가

## 평가: 인증 추가

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

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

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

### 3단계: 평가
실행: /eval check 인증-추가

### 4단계: 보고
평가 보고서: 인증-추가
==============================
능력: 5/5 통과 (pass@3: 100%)
회귀: 3/3 통과 (pass^3: 100%)
상태: 출시 준비 완료

로컬 프레임워크 유틸리티

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

node scripts/eval-harness.js example

• 캡슐: 다섯 계보와 로컬 무결성 검사가 있는 해시 연결 저널입니다.
• 검사: 소스 다이제스트, 검증된 변형 경로, 구문 경고입니다.
• 재생: 선언된 도구와 콘텐츠 주소 지정 장치입니다. 누락된 장치는 실패로 종료되며, SE3 이상은 재생에서 거부됩니다. 기록 모드는 등록된 구현을 호출하므로 신뢰할 수 있는 함수만 등록하세요.
• 영수증: 캡슐과 아티팩트 바이트의 오프라인 검증입니다.
• 회고 준비: 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-판사 루브릭)
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 릴리스 스냅샷