AI Forge Eval

Was macht AI Forge Eval?

Verhaltensvalidierung für Skills und Agents. Rubrikbewertung (ai-forge-judge) gibt dir eine Rückmeldung, ob ein Artefakt gut geschrieben ist. Eval sagt dir, ob es funktioniert.

Funktioniert für SKILL.md (Skills) und .agent.md (Agents). Gleicher 5-Phasen-Ablauf; Phase 2 Setup unterscheidet sich nach Artefakttyp.

---

Phase 0 — Suite laden oder schreiben

VERPFLICHTEND — LIES references/eval-suite.md für das Dateiformat, das Trigger-Protokoll und die Assertions-Diskriminierungstabelle.

Prüfe auf evals/evals.json neben dem Artefakt.

• Vorhanden — lade es und springe zu Phase 2. Füge Fälle hinzu, wenn die Abdeckung dünn ist; überschreibe niemals stillschweigend vorhandene Fälle, sonst ist der Trend kaputt.
• Nicht vorhanden — erstelle es in Phase 1 und schreibe es als evals/evals.json, bevor du irgendwas startest.

Eine Suite, die nur in dieser Konversation lebt, kann nächsten Monat keine Regression erkennen. Sie zu persistieren macht den Unterschied zwischen einer Meinung und einem Test.

---

Phase 1 — Evals schreiben

Schreibe 2–3 Evaluierungsfälle. Jeder Eval besteht aus einem realistischen Prompt plus 3–5 Assertions.

Bevorzuge Prompts aus einer Basisprobe (ai-forge-create Phase 1b) gegenüber den eigenen Triggern des Artefakts — Assertions, die aus dem Artefakt geschrieben wurden, können nur bestätigen, dass es das tut, was es behauptet. Trage jede Aufnahme in das baseline_failure-Feld des Szenarios ein.

Für Skills: Prompts, die den Skill natürlicherweise aktivieren sollten. Assertions prüfen skill-spezifisches Verhalten (z.B. „Ausgabe enthält eine Phase 1 Zusammenfassung”, „NEVER-Regelformat hat WHY und INSTEAD”).

Für Agents: Prompts, die den angegebenen Umfang des Agenten abdecken. Assertions prüfen beobachtbares Verhalten — erstellte Dateien, aufgerufene Tools, Toneinschränkungen, Umfangsgrenzen (z.B. „hat keine Dateien außerhalb von src/lib/ geändert”, „hat einen PR erstellt”, „Commit-Nachricht beginnt mit 'refactor:'”).

Assertionsregeln:

• Überprüfbar: der Prüfer kann anhand der Ausgabe allein verifizieren
• Spezifisch: „Ausgabe enthält 'Phase 1'-Überschrift” schlägt „Ausgabe ist gut strukturiert”
• Falsifizierbar: muss scheitern können

Aufzeichnen der Evals:

Eval 1: <Prompt>
Erwartungen:
- <Assertion 1>
- <Assertion 2>
- <Assertion 3>

---

Phase 2 — Parallel ausführen

Starte für jeden Eval die Mit-Artefakt- und Baseline-Durchläufe in derselben Nachricht (niemals sequenziell). Im Benchmark-Modus werden daraus N Versuchspaare pro Eval — siehe Benchmark-Modus unten.

Mit-Artefakt-Durchlauf: Gib ihm den Eval-Prompt. Bei Skills: Füge „Verwende den Skill <skill-name> für diese Aufgabe” hinzu. Bei Agents: Füge die vollständigen Anweisungen des Agenten als Systemkontext ein.

Baseline-Durchlauf: Hängt davon ab, was gemessen wird.

• Neues Artefakt — gleicher Eval-Prompt, keine Skill-Anweisung, kein Agentenkontext. Normale Assistentenantwort.
• Verbesserung eines bestehenden Artefakts — erstelle zuerst einen Schnappschuss der aktuellen Version (cp -r <pfad> <scratch>/snapshot/), dann weise den Baseline-Durchlauf auf den Schnappschuss. „Kein Artefakt” ist die falsche Kontrolle, wenn die Frage ist, ob die Änderung geholfen hat; es misst die Existenz des Artefakts, nicht die Bearbeitung.

Sofort bei Abschluss erfassen: Wenn jede Aufgabenbenachrichtigung eintrifft, notiere, welcher Durchlauf es war (plus Versuchsindex im Benchmark-Modus) und lies duration_ms und subagent_tokens aus seinem <usage>-Block — exakt, nicht geschätzt. Kein <usage>-Block bedeutet null notieren; niemals eine Wanduhr-Schätzung einsetzen. Diese Daten existieren nur zum Zeitpunkt der Benachrichtigung und können anschließend nicht rekonstruiert werden.

Speichere pro Eval: with_artifact- und baseline-Ausgabetext sowie duration_ms und tokens für jeden Arm.

---

Phase 3 — Bewerten

VERPFLICHTEND LESEN: agents/assayer.md

Rufe für jeden Eval den Assayer für beide Ausgaben auf. Übergib:

Ausgabe: <Ausgabetext>
Erwartungen:
- <Assertion 1>
- <Assertion 2>

Assayer gibt pro Erwartung zurück:

{ "text": "...", "passed": true, "evidence": "..." }

Berechne pass_rate = bestanden / gesamt pro Durchlauf. Berechne delta = with_artifact.pass_rate - baseline.pass_rate.

Klassifiziere dann jede Assertion danach, wie sie sich über beide Arme verhält — besteht in beiden (misst das Modell, nicht das Artefakt), scheitert in beiden (kaputt oder unerreichbar), besteht mit und scheitert ohne (echtes Signal), scheitert mit und besteht ohne (das Artefakt schadet), oder hohe Varianz (flaky). Siehe die Tabelle in references/eval-suite.md. Eine Suite, deren Assertions alle in beiden Armen bestehen, meldet eine gesunde Bestehensrate und sagt dir nichts.

Lies auch das Transkript, nicht nur die Ausgabe: Hat der Durchlauf tatsächlich dem Artefakt gefolgt oder die richtige Antwort trotzdem erreicht? Arbeit, die das Artefakt verursacht hat, aber nichts hervorgebracht hat, ist ein Kandidat für Streichung.

---

Phase 3b — Menschliche Überprüfung

Bevor du selbst etwas analysierst, lege die Rohausgaben dem Benutzer vor.

Fülle assets/eval-review.html aus — ersetze __ARTIFACT_NAME__ und __EVAL_DATA__ (ein JSON-Array von {id, name, prompt, with_artifact, baseline, assertions}) und schreibe es neben die Evaluierungssuite. Präsentiere es mit einem Dateiübergabe-Tool, falls verfügbar; andernfalls gib dem Benutzer den Pfad an. Lies das exportierte feedback.json, wenn der Benutzer fertig ist.

Die Modellbewertung der eigenen Artefaktausgabe ist das schwächste Signal hier — ein menschlicher Blick erfasst, wofür keine Assertion geschrieben wurde. Überspringe dies nur, wenn der Benutzer ablehnt.

---

Phase 4 — Vergleichen (optional)

VERPFLICHTEND LESEN: agents/arbiter.md — lade nur, wenn Phase 4 läuft.

Führe Phase 4 aus, wenn: Delta > 0,1 bei irgendeinem Eval oder pass_rates widersprüchlich über Evals hinweg.

Überspringe, wenn: pass_rates identisch sind oder der Benutzer nur Noten angefordert hat.

Arbiter-Eingabe: Ausgabe A (unbeschriftet), Ausgabe B (unbeschriftet), Erwartungsliste. Notiere, was was war, für Phase 5.

Arbiter gibt zurück: Inhaltsnote (1–5), Strukturnote (1–5), Gewinner (A/B/unentschieden), Begründung, Stärken/Schwächen pro Seite.

Release-Gate beim Vergleich zweier Versionen: veröffentliche nur, wenn die neue Version jedes Szenario gewinnt oder unentschieden spielt und mindestens eines gewinnt. Eine Version, die in einem Fall groß gewinnt und in einem anderen verliert, hat einen Fehler gegen einen anderen getauscht — das ist keine Verbesserung, und das aggregierte Delta wird es verbergen.

---

Phase 5 — Analysieren + Berichten

VERPFLICHTEND LESEN: agents/refiner.md — lade nur, wenn Phase 4 gelaufen ist.

Wenn Phase 4 übersprungen wurde: gehe direkt zur Benchmark-Tabelle.

Refiner-Eingabe: Arbiter-Ausgabe + Label-Mapping { "A": "with_artifact", "B": "baseline" } (oder umgekehrt). Refiner erklärt, warum der Gewinner den Verlierer geschlagen hat, und zeigt 1–3 priorisierte Verbesserungen auf.

Benchmark-Tabelle rendern — eine Zeile pro Eval plus eine Zeile „Durchschnitt”, Spalten Eval | with_artifact | baseline | delta | duration_ms (mit / base), Bestehensanzahlen und -prozentsätze pro Arm. Füge alle in Phase 3 markierten nicht diskriminierenden oder schädigenden Assertions hinzu, dann die Verbesserungsvorschläge des Refiners, falls er gelaufen ist.

Wenn das Delta bei irgendeinem Eval negativ ist, kennzeichne: „Artefakt könnte die Leistung beeinträchtigen — überprüfe Trigger-Formulierung oder Umfangsbeschränkungen.”

---

Phase 6 — Trigger-Prüfung

Verhaltensevaluierungen beantworten die Frage „funktioniert es, wenn es aufgerufen wird”. Dies beantwortet die Frage „wird es aufgerufen” — der häufigere Fehler, und unsichtbar für alle obigen Phasen.

Führe aus, wenn die Suite einen triggers-Block hat, oder biete es nach Phase 5 an. VERPFLICHTEND — LIES references/eval-suite.md für das Protokoll, den 60/40-Holdout-Split und die Abfragequalitätsanforderung. Lade es NICHT für einen reinen Verhaltensdurchlauf.

Berichte Recall und Precision pro Split (Train und gehalten) sowie die spezifischen Fehltreffer und Fehlalarme. Niedriger Recall bei hoher Precision bedeutet, dass die Beschreibung zu eng ist — erweitere sie. Das Gegenteil bedeutet, dass sie benachbarte Aufgaben abgreift — füge negative Trigger hinzu.

---

Benchmark-Modus

Auslösen, wenn der Benutzer bittet zu benchmarken, Regression zu verfolgen oder auf Trend zu kontrollieren. Der Benchmark-Modus erweitert das Fünf-Phasen-Modell um wiederholte Versuche und einen persistierten Trendspeicher.

VERPFLICHTEND LESEN: references/benchmarking.md vor der Ausführung — Versuchsprotokoll, Aggregationsformeln, Gate-Schwellenwerte und die Schemata für Versuchsergebnisse + benchmark.json leben dort. Lade es NICHT für einen einfachen Einzeldurchlauf.

• Versuche — jeder Eval läuft N-mal (Standard 3). Pro Eval starte alle N Versuchspaare (2N Subagenten) in EINER Nachricht, verarbeite die Benachrichtigungen dieses Evals mit Erfassung von <usage> gemäß Phase 2, dann gehe zum nächsten Eval. Starte niemals alle Versuche aller Evals auf einmal.
• Aggregieren — node scripts/aggregate-benchmark.cjs --trials <scratch.json> --prior benchmarks/<artefaktname>.json --artifact <pfad> gibt pro Eval Mittelwert/Standardabweichung, Flaky- und Diskriminierungsflags, Deltas zum vorherigen Durchlauf und ein Gate-Urteil zurück. Wenn es nicht ausgeführt werden kann (kein node, Skript fehlt, Nutzungsfehler), melde die rohen Versuchsergebnisse mit ⚠ keine Aggregation — Validator nicht verfügbar: <Grund> und berechne kein Gate-Urteil manuell; ein Gate-Urteil ist eine Behauptung über statistische Signifikanz und darf nicht geschätzt werden. Ein Urteil von FAIL blockiert immer.
• Persistieren — speichere die zurückgegebene Nutzlast in benchmarks/<artefaktname>.json (versioniert) als neue Trend-Baseline.
• Berichten — Phase 5 Tabelle mit Mittelwert±Standardabweichung-Spalten plus dem Gate-Urteil. Bei Gate-Fehler lautet das Urteil „regrediert — nicht bereit”.

---

NIEMALS

• NIEMALS die with_artifact- und baseline-Durchläufe eines Versuchs sequenziell ausführen Stattdessen: Beide Arme jedes Versuchs in derselben Nachricht. Im Benchmark-Modus alle N Versuchspaare für einen Eval in eine Nachricht; verschiedene Evals dürfen sequenziell gebündelt werden. Warum: Sequenzielle Arme serialisieren paralleles Feedback; aber das gleichzeitige Starten aller Versuche aller Evals überflutet die Benachrichtigungen und macht die Erfassung von <usage> pro Eintreffen unzuverlässig.

• NIEMALS die Nutzdatenerfassung verschieben, bis andere Durchläufe abgeschlossen sind Stattdessen: Lies den <usage>-Block jeder Benachrichtigung (duration_ms, subagent_tokens) in dem Moment, in dem sie eintrifft. Warum: Die <usage>-Daten existieren nur zum Zeitpunkt der Benachrichtigung und können danach nicht rekonstruiert werden.

• NIEMALS einen einzelnen Versuch als Benchmark melden Stattdessen: Führe mindestens N=3 Versuche durch, damit Mittelwert und Standardabweichung aussagekräftig sind. Warum: Eine einzelne pass_rate sieht präzise aus, verbirgt aber Flakiness — ein Skill, der wirklich ein Drittel der Zeit besteht, kann bei einem Versuch als 100% oder 0% gelesen werden.

• NIEMALS ein Szenario abschwächen, bei dem ein with_artifact-Durchlauf gescheitert ist Stattdessen: Stärke den Körper, bis der Durchlauf das Szenario wie geschrieben besteht. Warum: Das Szenario ist die Aufzeichnung eines echten Fehlers. Es abzuschwächen macht den Eval grün, während der Fehler, den es abfangen sollte, unberührt überlebt.

• NIEMALS eine Beschreibung gegen die gehaltenen Trigger-Abfragen optimieren Stattdessen: Iteriere auf dem Train-Split; betrachte den gehaltenen Split nur, um die endgültige Version auszuwählen. Warum: Eine Beschreibung, die gegen ihren eigenen Testsatz optimiert wurde, erzielt gute Werte und generalisiert schlechter — du verlierst die einzige unverzerrte Schätzung, die du hattest.

• NIEMALS subjektive Assertions schreiben („Ausgabe ist klar”, „gut formatiert”, „gründlich”) Stattdessen: Überprüfbar am Text: „Ausgabe enthält 'Phase 1'-Überschrift”, „keine NEVER-Regel ohne WHY-Klausel” Warum: Subjektive Assertions geben dem Prüfer keine Grundwahrheit; bestanden/nicht bestanden wird willkürlich und nicht wiederholbar.

• NIEMALS unterschiedliche Prompts für die with- und baseline-Durchläufe verwenden Stattdessen: Identischer Prompt — nur die Artefakt-Anweisung unterscheidet sich. Warum: Prompt-Variation verfälscht das Delta; es misst Prompt-Qualität, nicht Artefakt-Effekt.

• NIEMALS Assayer-Ausgabe mit nicht standardmäßigen Feldnamen akzeptieren Stattdessen: Fordere exakt text, passed, evidence — lehne name, met, details oder andere ab. Warum: Die Aggregation in Phase 5 hängt von exakten Feldnamen ab; stillschweigend falsche Namen erzeugen falsche pass_rates.