Eval Harness

Eval Harness Skill

Claude Code oturumları için eval-driven development (EDD) ilkelerini uygulayan formal değerlendirme çerçevesi.

Ne Zaman Aktifleştirmeli

• AI destekli iş akışları için eval-driven development (EDD) kurarken
• Claude Code görev tamamlama için geçti/kaldı kriterleri tanımlarken
• pass@k metrikleriyle agent güvenilirliğini ölçerken
• Prompt veya agent değişiklikleri için regresyon test paketleri oluştururken
• Model versiyonları arasında agent performansını benchmark ederken

Felsefe

Eval-Driven Development, eval'ları "AI geliştirmenin birim testleri" olarak ele alır:

• İmplementasyondan ÖNCE beklenen davranışı tanımla
• Geliştirme sırasında eval'ları sürekli çalıştır
• Her değişiklikle regresyonları izle
• Güvenilirlik ölçümü için pass@k metriklerini kullan

Eval Tipleri

Capability Eval'ları

Claude'un daha önce yapamadığı bir şeyi yapıp yapamadığını test et:

[CAPABILITY EVAL: feature-name]Görev: Claude'un başarması gereken şeyin açıklamasıBaşarı Kriterleri:  - [ ] Kriter 1  - [ ] Kriter 2  - [ ] Kriter 3Beklenen Çıktı: Beklenen sonucun açıklaması

Regression Eval'ları

Değişikliklerin mevcut fonksiyonaliteyi bozmadığından emin ol:

[REGRESSION EVAL: feature-name]Baseline: SHA veya checkpoint adıTestler:  - existing-test-1: PASS/FAIL  - existing-test-2: PASS/FAIL  - existing-test-3: PASS/FAILSonuç: X/Y geçti (önceden Y/Y)

Grader Tipleri

1. Code-Based Grader

Kod kullanarak deterministik kontroller:

# Dosyanın beklenen pattern içerip içermediğini kontrol etgrep -q "export function handleAuth" src/auth.ts && echo "PASS" || echo "FAIL"
# Testlerin geçip geçmediğini kontrol etnpm test -- --testPathPattern="auth" && echo "PASS" || echo "FAIL"
# Build'in başarılı olup olmadığını kontrol etnpm run build && echo "PASS" || echo "FAIL"

2. Model-Based Grader

Açık uçlu çıktıları değerlendirmek için Claude kullan:

[MODEL GRADER PROMPT]Aşağıdaki kod değişikliğini değerlendir:1. Belirtilen sorunu çözüyor mu?2. İyi yapılandırılmış mı?3. Edge case'ler işleniyor mu?4. Hata işleme uygun mu?
Puan: 1-5 (1=kötü, 5=mükemmel)Gerekçe: [açıklama]

3. Human Grader

Manuel inceleme için işaretle:

[HUMAN REVIEW REQUIRED]Değişiklik: Neyin değiştiğinin açıklamasıSebep: Neden insan incelemesi gerekliRisk Seviyesi: DÜŞÜK/ORTA/YÜKSEK

Metrikler

pass@k

"k denemede en az bir başarı"

• pass@1: İlk deneme başarı oranı
• pass@3: 3 denemede başarı
• Tipik hedef: pass@3 > %90

pass^k

"Tüm k denemeler başarılı"

• Güvenilirlik için daha yüksek çıta
• pass^3: Ardışık 3 başarı
• Kritik yollar için kullan

Eval İş Akışı

1. Tanımla (Kodlamadan Önce)

## EVAL DEFINITION: feature-xyz
### Capability Eval'ları1. Yeni kullanıcı hesabı oluşturabilir2. Email formatını doğrulayabilir3. Şifreyi güvenli şekilde hash'leyebilir
### Regression Eval'ları1. Mevcut login hala çalışıyor2. Oturum yönetimi değişmedi3. Logout akışı sağlam
### Başarı Metrikleri- capability eval'lar için pass@3 > %90- regression eval'lar için pass^3 = %100

2. Uygula

Tanımlanan eval'ları geçmek için kod yaz.

3. Değerlendir

# Capability eval'ları çalıştır[Her capability eval'ı çalıştır, PASS/FAIL kaydet]
# Regression eval'ları çalıştırnpm test -- --testPathPattern="existing"
# Rapor oluştur

4. Rapor

EVAL REPORT: feature-xyz========================
Capability Eval'ları:  create-user:     PASS (pass@1)  validate-email:  PASS (pass@2)  hash-password:   PASS (pass@1)  Genel:           3/3 geçti
Regression Eval'ları:  login-flow:      PASS  session-mgmt:    PASS  logout-flow:     PASS  Genel:           3/3 geçti
Metrikler:  pass@1: %67 (2/3)  pass@3: %100 (3/3)
Durum: İNCELEMEYE HAZIR

Entegrasyon Kalıpları

İmplementasyondan Önce

/eval define feature-name

.claude/evals/feature-name.md konumunda eval tanım dosyası oluşturur

İmplementasyon Sırasında

/eval check feature-name

Mevcut eval'ları çalıştırır ve durumu raporlar

İmplementasyondan Sonra

/eval report feature-name

Tam eval raporu oluşturur

Eval Depolama

Eval'ları projede sakla:

.claude/  evals/    feature-xyz.md      # Eval tanımı    feature-xyz.log     # Eval çalıştırma geçmişi    baseline.json       # Regression baseline'ları

En İyi Uygulamalar

1. Kodlamadan ÖNCE eval'ları tanımla - Başarı kriterleri hakkında net düşünmeyi zorlar
2. Eval'ları sık çalıştır - Regresyonları erken yakala
3. pass@k'yı zaman içinde izle - Güvenilirlik trendlerini gözle
4. Mümkün olduğunda code grader kullan - Deterministik > olasılıksal
5. Güvenlik için insan incelemesi - Güvenlik kontrollerini asla tam otomatikleştirme
6. Eval'ları hızlı tut - Yavaş eval'lar çalıştırılmaz
7. Eval'ları kodla versiyonla - Eval'lar birinci sınıf artifact'lardır

Örnek: Kimlik Doğrulama Ekleme

## EVAL: add-authentication
### Faz 1: Tanımla (10 dk)Capability Eval'ları:- [ ] Kullanıcı email/şifre ile kayıt olabilir- [ ] Kullanıcı geçerli kimlik bilgileriyle giriş yapabilir- [ ] Geçersiz kimlik bilgileri uygun hatayla reddedilir- [ ] Oturumlar sayfa yeniden yüklemelerinde kalıcıdır- [ ] Logout oturumu temizler
Regression Eval'ları:- [ ] Halka açık rotalar hala erişilebilir- [ ] API yanıtları değişmedi- [ ] Veritabanı şeması uyumlu
### Faz 2: Uygula (değişir)[Kod yaz]
### Faz 3: DeğerlendirÇalıştır: /eval check add-authentication
### Faz 4: RaporlaEVAL REPORT: add-authentication==============================Capability: 5/5 geçti (pass@3: %100)Regression: 3/3 geçti (pass^3: %100)Durum: YAYINLA

Product Eval'ları (v1.8)

Davranış kalitesi sadece birim testlerle yakalanamadığında product eval'ları kullan.

Grader Tipleri

1. Code grader (deterministik assertion'lar)
2. Rule grader (regex/şema kısıtlamaları)
3. Model grader (LLM-as-judge rubric)
4. Human grader (belirsiz çıktılar için manuel karar)

pass@k Kılavuzu

• pass@1: doğrudan güvenilirlik
• pass@3: kontrollü yeniden denemeler altında pratik güvenilirlik
• pass^3: kararlılık testi (3 çalıştırmanın tümü geçmeli)

Önerilen eşikler:

• Capability eval'ları: pass@3 >= 0.90
• Regression eval'ları: yayın-kritik yollar için pass^3 = 1.00

Eval Anti-Kalıpları

• Prompt'ları bilinen eval örneklerine overfitting yapmak
• Sadece mutlu-yol çıktılarını ölçmek
• Geçme oranlarını kovalamken maliyet ve gecikme kaymasını görmezden gelmek
• Yayın kapılarında kararsız grader'lara izin vermek

Minimal Eval Artifact Düzeni

• .claude/evals/<feature>.md tanımı
• .claude/evals/<feature>.log çalıştırma geçmişi
• docs/releases/<version>/eval-summary.md yayın snapshot'ı