ultraeval: Bewertung eines Skills oder Codebase → fundierte, KI-nutzbare Fehlerbehebungsdokumente
Das Markdown ist das Programm. Eine kleine deterministische Engine erstellt das Grundgerüst für den Durchlauf, generiert den Multi-Agenten-Workflow und erzwingt eine Grounding-Gate; Sie (mit ausgelagerten Subagenten) führen die Recherche, die Beurteilung und das Schreiben durch. Jeder Befund muss in eine reale datei:zeile im Zielobjekt aufgelöst werden – die Gate weist halluzinierte zurück – und die Ausgabe ist eine priorisierte Liste sowie pro Fehlerbehebung eine TDD-Karte, die ein Modell rot→grün→refaktorieren umsetzen kann.
Wann verwenden
- „Diesen Skill (oder dieses Repo) evaluieren / auditieren / bewerten / benoten“; „Ist es produktionsreif / erfüllt es die Erwartungen?“
- „Diese Codebase überprüfen und mir einen Fehlerbehebungsplan / eine TDD-Liste geben.“
- Regression eigener Skills nach Änderungen oder Überprüfung eines Drittanbieter-Skills vor der Nutzung.
Nicht für: eine schnelle Einzeldatei-Codeüberprüfung (einfach lesen); das Ausführen der eigenen Testsuite des Ziels (das direkt tun).
Der Ablauf
init → plan → run(recherche → test-plan → ausführung+gates → beurteilung → ergebnisse) → verify → backlog(TDD) → score → render
Alles ist ein einfacher node <skill-verzeichnis>/scripts/ultraeval.mjs <cmd>-Aufruf. Das Auslagern von Subagenten ist eine Optimierung, die der generierte Workflow kodiert – niemals eine Anforderung.
Eingaben bestätigen
- Ziel – ein Pfad zum zu bewertenden Skill/Repo (oder eine Git-URL, die der Benutzer bereits lokal geklont hat).
- Art –
skillodercodebase(automatisch erkannt: eine SKILL.md ⇒ skill). Mit--kindüberschreiben. - Kategorie – z. B. „Agenten-Skill“, „CLI“, „Bibliothek“, „Web-App“, „Sicherheitstool“. Steuert die Startbewertungsmatrix.
- Modus –
audit(Fehler, Standard) ·improve(fundierte Verbesserungsmöglichkeiten) ·deep(beides). Mit--modesetzen.
Modi & Verbesserungsfindung
ultraeval findet zwei Arten von Befunden, beide fundiert und durch Gates geprüft:
- Fehler (
audit,deep) – etwas stimmt nicht; jeder zitiert eine realedatei:zeile. - Verbesserungsmöglichkeiten (
improve,deep) – eine fundierte Verbesserungsrichtung (interne Gesundheit und Produkt/Fähigkeit), bewertet nach Einfluss × Aufwand. Entdeckt durchanalyze(deterministische Hotspots/Abhängigkeiten/Churn/Testlücken) →brainstorm(divergente Perspektiven) →brainstorm --rank(faltet gereihte Möglichkeiten infindings.jsonalskind:"opportunity"). Die gleiche Gate gilt – eine Möglichkeit muss an echtem Code/Metriken verankert sein, damit sie nie zu vager „Alles umschreiben“ wird. Siehereferences/analysis-playbook.md.
Für improve/deep fügt plan die Phasen Analyze und Brainstorm zum generierten Workflow hinzu.
Vorgehen
1. Grundgerüst des Durchlaufs erstellen.
node <skill-verzeichnis>/scripts/ultraeval.mjs init --target <PFAD> --out <LAUF> [--kind skill|codebase] [--category "<k>"]
Schreibt eval.config.json mit Startdimensionen (siehe references/rubric-library.md).
2. Workflow + Subagenten-Verträge generieren.
node <skill-verzeichnis>/scripts/ultraeval.mjs plan --run <LAUF>
Erzeugt <LAUF>/eval.workflow.mjs (einen startbereiten Multi-Agenten-Workflow mit eingebauten absoluten Engine- und Zielpfaden), <LAUF>/agents/*.md (die Auslagerungsverträge), TEST-PLAN.template.md, dimensions.json, findings.schema.json.
3. Evaluierung ausführen. Starten Sie den generierten Workflow mit dem Workflow-Tool Ihrer Umgebung:
Workflow({ scriptPath: "<LAUF>/eval.workflow.mjs" }). Er verarbeitet Recherche → TestPlan → Ausführung → Befunde → Gate → Bewertung → Ergebnisse und ruft selbst die Engine-Gates auf. Wenn Sie kein Workflow-Tool haben, führen Sie die Phasen manuell aus: Lesen Sie jedes agents/<phase>.md und senden Sie einen Subagenten gemäß dem Vertrag. Siehe references/orchestration.md. **Jeder Subagent erhält den ABSOLUTEN Pfad <skill-verzeichnis>/scripts/ultraeval.mjs** – er hat sein eigenes Arbeitsverzeichnis und kann keinen relativen Pfad auflösen (plan` hat den absoluten Pfad bereits in den Workflow eingebaut).
4. Jeden Befund fundieren. Konsolidieren Sie die Ergebnisse in <LAUF>/findings.json (Schema: references/gate-contract.md). Jeder Befund zitiert evidence[].ref als pfad:zeile im Ziel oder lauf:relativer Pfad#Lnn in einem erstellten Log. Dann:
node <skill-verzeichnis>/scripts/ultraeval.mjs check --run <LAUF>
Korrigieren Sie findings.json, bis es mit Exit 0 beendet wird – ungegründete Befunde reparieren oder löschen; die Gate niemals abschwächen.
5. Verifizieren (adversarielle Exit-Gate).
node <skill-verzeichnis>/scripts/ultraeval.mjs verify --run <LAUF> # schreibt VERIFY.todo.json
# Füllen Sie jedes Urteil: supported | partial | refuted | unsupported (skeptische Subagenten verwenden; --shards N --shard i für Parallelisierung)
node <skill-verzeichnis>/scripts/ultraeval.mjs verify --run <LAUF> --apply <urteile.json>
node <skill-verzeichnis>/scripts/ultraeval.mjs check --run <LAUF> --semantic --require-verify # Exit-Gate – niemals vor Bestehen dieses Schritts präsentieren
Ein als refuted eingestufter Befund muss auf dismissed gesetzt werden. Ein als supported/partial eingestufter bleibt bestehen.
6. Beheben – das Ergebnis.
node <skill-verzeichnis>/scripts/ultraeval.mjs backlog --run <LAUF> --tdd
Erzeugt BACKLOG.json (eine maschinenlesbare, priorisierte Aufgabenliste, die ein nachgeschalteter Agent ausführen kann), REMEDIATION.md und pro bestätigtem Befund eine fixes/FIX-*.md TDD-Karte – jede mit einer roten fehlschlagenden Test-first-Spezifikation, der grünen Änderung und einem VERIFY-Befehl. Siehe references/tdd-remediation.md.
7. Bewerten + rendern + präsentieren.
node <skill-verzeichnis>/scripts/ultraeval.mjs score --run <LAUF> # judges.jsonl + dimensionen -> scorecard.json (0-100 + erwartungserfüllt)
node <skill-verzeichnis>/scripts/ultraeval.mjs render --run <LAUF> # index.html + index.md Dashboard (zeigt das Urteil)
score reduziert das Bewertungspanel judges.jsonl und die Konfigurationsdimensionen zu einem gewichteten Urteil; ein aktiver P0-Befund (oder ein mit „Nein“ stimmender Bewerter, oder eine Punktzahl unter dem Schwellwert) setzt meets-expectations auf false. Präsentieren Sie das Urteil, die P0/P1-Backlog-Überschrift und die Pfade (RESULTS.md, BACKLOG.json, fixes/), die ein Fix-Agent konsumieren soll.
Exit-Codes über die CLI: 0 ok / Gate bestanden · 1 Gate nicht bestanden (check/verify) · 2 Verwendungs- oder Laufzeitfehler.
8. (optional) Fehlerbehebungen ausführen. Übergeben Sie jede fixes/FIX-*.md an einen Build-Agenten, der TDD implementiert – die Karte ist so geschrieben, dass sie rot→grün→refaktorieren kann, ohne das Problem neu herleiten zu müssen.
Der Grounding-Vertrag
Ein Befund ist nur vertrauenswürdig, wenn seine Belege aufgelöst werden können. check öffnet jedes pfad:zeile im Ziel und bestätigt, dass die Zeile existiert und im Bereich liegt; eine veraltete/erfundene Zeile ist ein harter Fehler. verify fragt dann einen Skeptiker, ob der zitierte Inhalt die Behauptung tatsächlich stützt. Diese zweistufige Gate (strukturell + semantisch) ist der Kern – vollständige Grammatik und Bestehen/Nichtbestehen-Regeln in references/gate-contract.md.
Methode & Bewertungsmatrizen
references/eval-playbook.md– die Methode Recherche→Testplan→Ausführung→Bewertung→Ergebnisse und wie man eine bewertete Matrix pro Dimension erstellt.references/orchestration.md– der generierte Workflow, die Subagenten-Auslagerungsverträge und die absolute<skill-verzeichnis>-Invariante für die Aufteilung.references/gate-contract.md–findings.json-Schema, Belegreferenz-Grammatik und genau, wascheck/verifybestehen oder nicht bestehen lässt.references/tdd-remediation.md– dieBACKLOG.json-Struktur und das Format derfixes/FIX-*.mdTDD-Karten.references/rubric-library.md– Startdimensionen pro Zielkategorie.references/analysis-playbook.md– dieanalyze-Signale, die Brainstorm-Perspektiven und wie Möglichkeiten fundiert bleiben.
Sicherheit
- ultraeval liest nur das Ziel und schreibt unter
<LAUF>. Es führt niemals den Code des Ziels aus; der Ausführende Subagent kann die eigenen Befehle des Ziels (Tests, Gates) ausführen – vertrauenswürdige Repos in einer Sandbox ausführen. clean --run <LAUF>entfernt nur abgeleitete Gate-/Render-Artefakte und behält die Ergebnisse;--allentfernt den gesamten Durchlauf.