Eval-Harness

Eval-Harness-Skill

Ein formales Evaluierungs-Framework für Claude Code-Sitzungen, das die Prinzipien der eval-gesteuerten Entwicklung (EDD) umsetzt.

Wann aktivieren

• Einrichtung der eval-gesteuerten Entwicklung (EDD) für KI-gestützte Workflows
• Definition von Bestehens-/Nichtbestehenskriterien für den Abschluss von Claude Code-Aufgaben
• Messung der Agentenzuverlässigkeit mit pass@k-Metriken
• Erstellung von Regressionstestsuiten für Prompt- oder Agentenänderungen
• Benchmarking der Agentenleistung über verschiedene Modellversionen hinweg

Philosophie

Eval-gesteuerte Entwicklung behandelt Evaluierungen als die „Unit-Tests der KI-Entwicklung“:

• Erwartetes Verhalten VOR der Implementierung definieren
• Evaluierungen während der Entwicklung kontinuierlich durchführen
• Regressionen bei jeder Änderung verfolgen
• pass@k-Metriken für die Zuverlässigkeitsmessung verwenden

Eval-Typen

Fähigkeits-Evaluierungen (Capability Evals)

Testen, ob Claude etwas tun kann, das es vorher nicht konnte:

[CAPABILITY EVAL: feature-name]
Task: Beschreibung dessen, was Claude erreichen soll
Success Criteria:
  - [ ] Kriterium 1
  - [ ] Kriterium 2
  - [ ] Kriterium 3
Expected Output: Beschreibung des erwarteten Ergebnisses

Regressions-Evaluierungen (Regression Evals)

Stellen sicher, dass Änderungen keine vorhandenen Funktionen beeinträchtigen:

[REGRESSION EVAL: feature-name]
Baseline: SHA oder Prüfpunktname
Tests:
  - existing-test-1: PASS/FAIL
  - existing-test-2: PASS/FAIL
  - existing-test-3: PASS/FAIL
Result: X/Y bestanden (vorher Y/Y)

Bewerter-Typen (Grader Types)

1. Code-basierter Bewerter

Deterministische Prüfungen mit Code:

# Prüfen, ob Datei erwartetes Muster enthält
grep -q "export function handleAuth" src/auth.ts && echo "PASS" || echo "FAIL"

# Prüfen, ob Tests bestehen
npm test -- --testPathPattern="auth" && echo "PASS" || echo "FAIL"

# Prüfen, ob Build erfolgreich ist
npm run build && echo "PASS" || echo "FAIL"

2. Modellbasierter Bewerter

Verwende Claude zur Bewertung offener Ergebnisse:

[MODEL GRADER PROMPT]
Bewerten Sie die folgende Codeänderung:
1. Löst sie das beschriebene Problem?
2. Ist sie gut strukturiert?
3. Werden Randfälle behandelt?
4. Ist die Fehlerbehandlung angemessen?

Score: 1-5 (1=schlecht, 5=ausgezeichnet)
Begründung: [Erklärung]

3. Menschlicher Bewerter

Zur manuellen Überprüfung markieren:

[HUMAN REVIEW REQUIRED]
Change: Beschreibung der Änderung
Reason: Warum eine manuelle Überprüfung erforderlich ist
Risk Level: NIEDRIG/MITTEL/HOCH

Metriken

pass@k

„Mindestens ein Erfolg in k Versuchen“

• pass@1: Erfolgsquote beim ersten Versuch
• pass@3: Erfolg innerhalb von 3 Versuchen
• Typisches Ziel: pass@3 > 90 %

pass^k

„Alle k Versuche erfolgreich“

• Höhere Messlatte für Zuverlässigkeit
• pass^3: 3 aufeinanderfolgende Erfolge
• Für kritische Pfade verwenden

Eval-Workflow

1. Definieren (vor dem Codieren)

## EVAL DEFINITION: feature-xyz

### Capability Evals
1. Kann neuen Benutzeraccount erstellen
2. Kann E-Mail-Format validieren
3. Kann Passwort sicher hashen

### Regression Evals
1. Vorhandener Login funktioniert weiterhin
2. Sitzungsverwaltung unverändert
3. Logout-Ablauf intakt

### Erfolgsmetriken
- pass@3 > 90 % für Fähigkeits-Evaluierungen
- pass^3 = 100 % für Regressions-Evaluierungen

2. Implementieren

Code schreiben, der die definierten Evaluierungen besteht.

3. Evaluieren

# Fähigkeits-Evaluierungen ausführen
[Jede Fähigkeits-Evaluierung ausführen, PASS/FAIL notieren]

# Regressions-Evaluierungen ausführen
npm test -- --testPathPattern="existing"

# Bericht erstellen

4. Berichten

EVAL REPORT: feature-xyz
========================

Capability Evals:
  create-user:     PASS (pass@1)
  validate-email:  PASS (pass@2)
  hash-password:   PASS (pass@1)
  Gesamt:          3/3 bestanden

Regression Evals:
  login-flow:      PASS
  session-mgmt:    PASS
  logout-flow:     PASS
  Gesamt:          3/3 bestanden

Metriken:
  pass@1: 67 % (2/3)
  pass@3: 100 % (3/3)

Status: BEREIT ZUR ÜBERPRÜFUNG

Integrationsmuster

Vor der Implementierung

/eval define feature-name

Erstellt Eval-Definitionsdatei unter .claude/evals/feature-name.md

Während der Implementierung

/eval check feature-name

Führt aktuelle Evaluierungen aus und meldet Status

Nach der Implementierung

/eval report feature-name

Erstellt vollständigen Eval-Bericht

Eval-Speicherung

Evaluierungen im Projekt speichern:

.claude/
  evals/
    feature-xyz.md      # Eval-Definition
    feature-xyz.log     # Eval-Ausführungsverlauf
    baseline.json       # Regressions-Baselines

Best Practices

1. Evaluierungen VOR dem Codieren definieren - Erzwingt klares Denken über Erfolgskriterien
2. Evaluierungen häufig ausführen - Regressionen früh erkennen
3. pass@k im Laufe der Zeit verfolgen - Zuverlässigkeitstrends überwachen
4. Nach Möglichkeit Code-Bewerter verwenden - Deterministisch > probabilistisch
5. Manuelle Überprüfung für Sicherheit - Sicherheitsprüfungen niemals vollständig automatisieren
6. Evaluierungen schnell halten - Langsame Evaluierungen werden nicht ausgeführt
7. Evaluierungen mit Code versionieren - Evaluierungen sind Artefakte erster Klasse

Beispiel: Authentifizierung hinzufügen

## EVAL: add-authentication

### Phase 1: Definieren (10 Min.)
Capability Evals:
- [ ] Benutzer kann sich mit E-Mail/Passwort registrieren
- [ ] Benutzer kann sich mit gültigen Anmeldedaten anmelden
- [ ] Ungültige Anmeldedaten werden mit entsprechendem Fehler abgelehnt
- [ ] Sitzungen bleiben über Seitenneuladungen hinweg bestehen
- [ ] Logout löscht die Sitzung

Regression Evals:
- [ ] Öffentliche Routen sind weiterhin zugänglich
- [ ] API-Antworten unverändert
- [ ] Datenbankschema kompatibel

### Phase 2: Implementieren (variiert)
[Code schreiben]

### Phase 3: Evaluieren
Ausführen: /eval check add-authentication

### Phase 4: Berichten
EVAL REPORT: add-authentication
==============================
Capability: 5/5 bestanden (pass@3: 100 %)
Regression: 3/3 bestanden (pass^3: 100 %)
Status: AUSLIEFERN

Lokale Framework-Dienstprogramme

Die mechanischen Dienstprogramme befinden sich in scripts/lib/eval-harness/:

node scripts/eval-harness.js example

• Capsule: Hash-verknüpftes Journal mit fünf Abstammungslinien und lokalen Integritätsprüfungen.
• Inspection: Quell-Digests, validierte Variantenpfade und syntaktische Warnungen.
• Replay: Deklarierte Tools und inhaltsadressierte Fixtures. Fehlende Fixtures führen zu einem geschlossenen Fehler; SE3 und höher werden im Replay abgelehnt. Der Aufzeichnungsmodus ruft die registrierte Implementierung auf, daher nur vertrauenswürdige Funktionen registrieren.
• Receipt: Offline-Verifizierung von Capsule- und Artefakt-Bytes mit benannten Prüfungen.
• Retrospektive Vorbereitung: node scripts/eval-harness.js capsule group <dir> [<dir> ...] gruppiert 1 bis 100 explizit ausgewählte, verifizierte lokale Capsule-Snapshots aus einer Aufgabenfamilie nach deklarierter Harness-Version. Wiederholte Snapshots werden einmal gezählt; widersprüchliche Identitäten oder ungültige Capsules lehnen den gesamten Bericht ab. Dies ist eine reine Lese-Zählung ohne neue Rollouts, Bewertungen oder Beförderungen. Verwenden Sie kleine, ruhende Capsules. Payloads, Verzeichnisargumente und rohe Ausführungs-/Capsule-IDs werden weggelassen, aber Aufgabenfamilien-/Versionsbezeichnungen sind wörtlich und Digest-Referenzen sind verlinkbar; überprüfen Sie diese vor dem Teilen. Die operationelle Validierung bleibt ausstehend.

Die Kandidatenausführung ist auf jedem Betriebssystem deaktiviert, da kein verifiziertes OS-Containment-Backend implementiert ist. gate run, runGate, runVariant, der direkte Kindprozessstart und der zurückgezogene Effekt-Preload verweigern mit gate.isolation_required. Kein Vertrauensflag oder vom Aufrufer bereitgestellter Executor kann die Verweigerung umgehen. Das Beispiel zeichnet diese Verweigerung auf und inspiziert die Quelle, ohne sie auszuführen oder zu bewerten.

Stellen Sie keine statischen Warnungen, einen Capsule-Beleg oder erfolgreiche Utility-Tests als Kandidaten-Containment- oder Beförderungsnachweis dar. Ein zukünftiges Gate erfordert eine unabhängig überprüfte OS-Grenze, einen geschützten Prüfer und Audit-Kanäle sowie eine fatale Baseline-Ablehnung. Siehe docs/architecture/eval-harness-frameworks.md.

Produkt-Evaluierungen (v1.8)

Verwenden Sie Produkt-Evaluierungen, wenn die Verhaltensqualität nicht allein durch Unit-Tests erfasst werden kann.

Bewerter-Typen

1. Code-Bewerter (deterministische Zusicherungen)
2. Regel-Bewerter (Regex/Schema-Einschränkungen)
3. Modell-Bewerter (LLM-als-Richter-Bewertungsraster)
4. Menschlicher Bewerter (manuelle Entscheidung für mehrdeutige Ausgaben)

pass@k-Richtlinien

• pass@1: direkte Zuverlässigkeit
• pass@3: praktische Zuverlässigkeit unter kontrollierten Wiederholungen
• pass^3: Stabilitätstest (alle 3 Läufe müssen bestehen)

Empfohlene Schwellenwerte:

• Fähigkeits-Evaluierungen: pass@3 >= 0,90
• Regressions-Evaluierungen: pass^3 = 1,00 für releases-kritische Pfade

Eval-Anti-Patterns

• Prompts übermäßig an bekannte Eval-Beispiele anpassen
• Nur Happy-Path-Ausgaben messen
• Kosten- und Latenzdrift ignorieren, während Bestehensquoten gejagt werden
• Unzuverlässige Bewerter in Release-Gates zulassen

Minimales Eval-Artefakt-Layout

• .claude/evals/<feature>.md Definition
• .claude/evals/<feature>.log Ausführungsverlauf
• docs/releases/<version>/eval-summary.md Release-Snapshot