eval-harness

Eval-Harness-Fertigkeit

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

Wann aktivieren

• Einrichtung der eval-gesteuerten Entwicklung (EDD) für KI-gestützte Arbeitsabläufe
• Definieren von Bestehen/Nichtbestehen-Kriterien für den Aufgabenabschluss von Claude Code
• Messen der Agentenzuverlässigkeit mit pass@k-Metriken
• Erstellen von Regressionstestsuiten für Prompt- oder Agentenänderungen
• Benchmarking der Agentenleistung über verschiedene Modellversionen hinweg

Philosophie

Eval-gesteuerte Entwicklung betrachtet Evaluierungen als die "Unit-Tests der KI-Entwicklung":

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

Evaluierungsarten

Fähigkeitsevaluierungen

Testen, ob Claude etwas tun kann, was 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

Regressionsevaluierungen

Sicherstellen, dass Änderungen keine bestehenden Funktionen beeinträchtigen:

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

Bewertungstypen

1. Codebasierte Bewertung

Deterministische Prüfungen mit Code:

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

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

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

2. Modellbasierte Bewertung

Claude verwenden, um offene Ergebnisse zu bewerten:

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

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

3. Menschliche Bewertung

Zur manuellen Überprüfung markieren:

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

Metriken

pass@k

"Mindestens ein Erfolg in k Versuchen"

• pass@1: Erfolgsrate im 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

Evaluierungs-Workflow

1. Definieren (vor dem Codieren)

## EVAL DEFINITION: feature-xyz

### Fähigkeitsevaluierungen
1. Kann neues Benutzerkonto erstellen
2. Kann E-Mail-Format validieren
3. Kann Passwort sicher hashen

### Regressionsevaluierungen
1. Bestehender Login funktioniert noch
2. Sitzungsverwaltung unverändert
3. Logout-Ablauf intakt

### Erfolgsmetriken
- pass@3 > 90% für Fähigkeitsevaluierungen
- pass^3 = 100% für Regressionsevaluierungen

2. Implementieren

Code schreiben, um die definierten Evaluierungen zu bestehen.

3. Evaluieren

# Fähigkeitsevaluierungen ausführen
[Jede Fähigkeitsevaluierung ausführen, PASS/FAIL aufzeichnen]

# Regressionsevaluierungen ausführen
npm test -- --testPathPattern="existing"

# Bericht erstellen

4. Berichten

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

Fähigkeitsevaluierungen:
  create-user:     PASS (pass@1)
  validate-email:  PASS (pass@2)
  hash-password:   PASS (pass@1)
  Gesamt:          3/3 bestanden

Regressionsevaluierungen:
  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 Evaluierungsdefinitionsdatei 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 Evaluierungsbericht

Evaluierungsspeicherung

Evaluierungen im Projekt speichern:

.claude/
  evals/
    feature-xyz.md      # Evaluierungsdefinition
    feature-xyz.log     # Evaluierungsverlauf
    baseline.json       # Regressionsbaselines

Best Practices

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

Beispiel: Authentifizierung hinzufügen

## EVAL: add-authentication

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

Regressionsevaluierungen:
- [ ] Öffentliche Routen weiterhin erreichbar
- [ ] 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
==============================
Fähigkeitsevaluierung: 5/5 bestanden (pass@3: 100%)
Regressionsevaluierung: 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

• Kapsel: hash-verknüpftes Journal mit fünf Abstammungslinien und lokalen Integritätsprüfungen.
• Inspektion: Quell-Digests, validierte Variantenpfade und syntaktische Warnungen.
• Wiedergabe: deklarierte Werkzeuge und inhaltsadressierte Fixtures. Fehlende Fixtures schlagen geschlossen fehl; SE3 und höher werden bei der Wiedergabe verweigert. Der Aufzeichnungsmodus ruft die registrierte Implementierung auf, daher nur vertrauenswürdige Funktionen registrieren.
• Beleg: Offline-Überprüfung von Kapsel- und Artefakt-Bytes mit benannten Prüfungen.
• Retrospektivenvorbereitung: node scripts/eval-harness.js capsule group <dir> [<dir> ...] gruppiert 1 bis 100 explizit ausgewählte, verifizierte lokale Kapsel-Snapshots aus einer Aufgabenfamilie nach deklarierter Harness-Version. Wiederholte Snapshots zählen einmal; widersprüchliche Identitäten oder ungültige Kapseln lehnen den gesamten Bericht ab. Dies ist ein schreibgeschützter Datensatzzähler, ohne neue Rollouts, Punktzahlen oder Promotion. Verwenden Sie kleine, ruhende Kapseln. Payloads, Verzeichnisargumente und rohe Lauf-/Kapsel-IDs werden weggelassen, aber Aufgabenfamilien-/Versionsbezeichnungen sind wörtlich und Digest-Referenzen sind verlinkbar; überprüfen Sie sie vor dem Teilen. Die operative Validierung bleibt ausstehend.

Die Ausführung von Kandidaten ist auf jedem Betriebssystem deaktiviert, da keine verifizierte Betriebssystem-Containment-Implementierung vorhanden ist. gate run, runGate, runVariant, direkte Kind-Prozess-Starts und der entfernte Effect-Preload verweigern mit gate.isolation_required. Kein Vertrauens-Flag 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 Kapsel-Beleg oder erfolgreiche Dienstprogrammtests als Kandidaten-Containment- oder Promotionsnachweis dar. Ein zukünftiges Gate erfordert eine unabhängig überprüfte Betriebssystemgrenze, geschützte Prüf- und Audit-Kanäle und 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.

Bewertungstypen

1. Code-Bewertung (deterministische Behauptungen)
2. Regel-Bewertung (Regex-/Schema-Einschränkungen)
3. Modell-Bewertung (LLM-als-Richter-Rubrik)
4. Menschliche Bewertung (manuelle Entscheidung für mehrdeutige Ausgaben)

pass@k-Leitfaden

• 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ähigkeitsevaluierungen: pass@3 >= 0,90
• Regressionsevaluierungen: pass^3 = 1,00 für release-kritische Pfade

Evaluierungs-Anti-Patterns

• Prompts an bekannte Evaluierungsbeispiele anpassen
• Nur Happy-Path-Ausgaben messen
• Kosten- und Latenz-Drift ignorieren, während Bestehensraten gejagt werden
• Flakige Bewertungen in Release-Gates zulassen

Minimales Evaluierungs-Artefakt-Layout

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