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 3
Beklenen Çı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/FAIL
Sonuç: 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 et
grep -q "export function handleAuth" src/auth.ts && echo "PASS" || echo "FAIL"

# Testlerin geçip geçmediğini kontrol et
npm test -- --testPathPattern="auth" && echo "PASS" || echo "FAIL"

# Build'in başarılı olup olmadığını kontrol et
npm 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 gerekli
Risk 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şturabilir
2. Email formatını doğrulayabilir
3. Şifreyi güvenli şekilde hash'leyebilir

### Regression Eval'ları
1. Mevcut login hala çalışıyor
2. Oturum yönetimi değişmedi
3. 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ır
npm 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: Raporla
EVAL 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'ı