uzysjung/uzys-agent-harness

Eval Harness Skill

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

Wann aktivieren

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

Philosophie

Eval-Getriebene Entwicklung betrachtet Evals als die „Unit-Tests der KI-Entwicklung“:

• Definiere das erwartete Verhalten VOR der Implementierung
• Führe Evals kontinuierlich während der Entwicklung aus
• Verfolge Regressionen bei jeder Änderung
• Verwende pass@k-Metriken zur Zuverlässigkeitsmessung

Eval-Typen

Capability-Evals

Testen, ob Claude etwas kann, was es vorher nicht konnte:

[CAPABILITY EVAL: feature-name]
Aufgabe: Beschreibung, was Claude erreichen soll
Erfolgskriterien:
  - [ ] Kriterium 1
  - [ ] Kriterium 2
  - [ ] Kriterium 3
Erwartetes Ergebnis: Beschreibung des erwarteten Ergebnisses

Regression-Evals

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

[REGRESSION EVAL: feature-name]
Basislinie: SHA oder Checkpoint-Name
Tests:
  - existing-test-1: BESTANDEN/FEHLGESCHLAGEN
  - existing-test-2: BESTANDEN/FEHLGESCHLAGEN
  - existing-test-3: BESTANDEN/FEHLGESCHLAGEN
Ergebnis: X/Y bestanden (vorher Y/Y)

Bewertungstypen

1. Codebasierte Bewertung

Deterministische Überprüfungen mit Code:

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

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

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

2. Modellbasierte Bewertung

Claude zur Bewertung offener Ergebnisse verwenden:

[MODEL GRADER PROMPT]
Bewerte 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=hervorragend)
Begründung: [Erklärung]

3. Manuelle Bewertung

Zur manuellen Überprüfung kennzeichnen:

[MANUELLE ÜBERPRÜFUNG ERFORDERLICH]
Änderung: Beschreibung der Änderung
Grund: Warum eine manuelle Überprüfung nötig ist
Risikostufe: NIEDRIG/MITTEL/HOCH

Metriken

pass@k

„Mindestens ein Erfolg in k Versuchen“

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

pass^k

„Alle k Versuche erfolgreich“

• Höhere Anforderungen an 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 noch
2. Sitzungsverwaltung unverändert
3. Logout-Ablauf intakt

### Erfolgsmetriken
- pass@3 > 90 % für Capability-Evals
- pass^3 = 100 % für Regression-Evals

2. Implementieren

Code schreiben, der die definierten Evals besteht.

3. Evaluieren

# Capability-Evals ausführen
[Jedes Capability-Eval ausführen, BESTANDEN/FEHLGESCHLAGEN notieren]

# Regression-Evals ausführen
npm test -- --testPathPattern="existing"

# Bericht erstellen

4. Berichten

EVAL-BERICHT: feature-xyz
========================

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

Regression-Evals:
  login-flow:      BESTANDEN
  session-mgmt:    BESTANDEN
  logout-flow:     BESTANDEN
  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 eine Eval-Definitionsdatei unter .claude/evals/feature-name.md

Während der Implementierung

/eval check feature-name

Führt aktuelle Evals aus und meldet den Status

Nach der Implementierung

/eval report feature-name

Erstellt einen vollständigen Eval-Bericht

Eval-Speicherung

Evals im Projekt speichern:

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

Best Practices

1. Definiere Evals VOR dem Codieren – Erzwingt klares Denken über Erfolgskriterien
2. Führe Evals häufig aus – Erkenne Regressionen frühzeitig
3. Verfolge pass@k über die Zeit – Überwache Zuverlässigkeitstrends
4. Verwende nach Möglichkeit Code-Bewertungen – Deterministisch > probabilistisch
5. Manuelle Überprüfung für Sicherheit – Automatisiere Sicherheitschecks niemals vollständig
6. Halte Evals schnell – Langsame Evals werden nicht ausgeführt
7. Versioniere Evals mit dem Code – Evals sind erstklassige Artefakte

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 passendem Fehler abgelehnt
- [ ] Sitzungen bleiben über Seitenneuladungen hinweg bestehen
- [ ] Logout löscht die Sitzung

Regression-Evals:
- [ ] Öffentliche Routen 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-BERICHT: add-authentication
==============================
Capability: 5/5 bestanden (pass@3: 100 %)
Regression: 3/3 bestanden (pass^3: 100 %)
Status: VERSAND BEREIT