Thema: Anwendungsteil 8. Datei-Schiedsverfahren bei strittigen Änderungen: Rollen, Urteile und Präzedenzfälle
Schwierigkeitsgrad: Mittelstufe
Geschätzte Lernzeit: 2-3 Stunden
Voraussetzungen: Kenntnisse der Prinzipien des Code-Reviews im Team (Teil 16 des ersten Bands)
Verständnis der Mechanismen von LLM-Duellen und der Arbeit mit Gegenbeispielen
Grundkenntnisse im Umgang mit der CLI (Ausführen von Python-Skripten)
Verständnis der Datenstrukturen YAML und JSON
Lernziele: Den Unterschied zwischen einem LLM-Duell und dem Datei-Schiedsverfahren verstehen (Fragen der Fehlersuche vs. offizielle Urteilsfindung).
Ein minimales Lernszenario für ein Schiedsverfahren einrichten und ausführen, das die Skripte run_duel.py, check_invariants.py und write_judgment.py verwendet.
Korrekte Einträge in judgment.md unter Verwendung strenger Beweise (evidence_ref) erstellen.
Einträge in precedents.md anlegen, um wiederkehrende Streitfälle zu dokumentieren.
Die Anti-Goodhart-Regel anwenden, um das System vor der Optimierung von Metriken auf Kosten versteckter Risiken (silent failures, rollback-flapping) zu schützen.
Übersicht: Das Datei-Schiedsverfahren verwandelt die Beilegung von Streitigkeiten über Code-Änderungen von einem subjektiven Meinungsaustausch im Chat in eine formalisierte, reproduzierbare Beweiskette. In diesem System arbeiten klar definierte Rollen: Der Koordinator steuert den Prozess, der Implementierer schlägt Änderungen vor, der Verifizierer prüft sie anhand formaler Kriterien, und Safety legt bei kritischen Risiken ein Veto ein. Das Ergebnis des Schiedsverfahrens sind Projektartefakte: judgment.md (Entscheidungslogbuch mit Beweisen) und precedents.md (Wissensdatenbank für wiederkehrende Streitfälle). Der Ansatz ist so konzipiert, dass das Urteil nicht von einem bestimmten KI-Modell abhängt (was durch Stufenrotation überprüft wird), und die Spezifikation bleibt die wichtigste Quelle der Wahrheit.
Schlüsselkonzepte: Datei-Schiedsverfahren: Kollektive Prüfung einer strittigen Änderung durch mehrere Rollen, wobei das Ergebnis in Form von Dateien (Artefakten) und nicht im Chatverlauf festgehalten wird.
Rollen im Schiedsverfahren: Koordinator (führt das Protokoll, stimmt nicht ab), Implementierer (schlägt Änderungen vor), Verifizierer (prüft formale Kriterien), Safety (blockiert kritische Risiken durch ein Veto).
Judgment.md: Logbuch der Entscheidungen zu Streitfällen. Muss das Urteil (APPROVE/DENY/DEFERRED), die Begründung und evidence_ref enthalten – einen Beweis aus einer Datei, nicht eine Nacherzählung aus dem Chat.
Precedents.md: Präzedenzlogbuch für wiederkehrende Streitfälle. Enthält eine stabile Kennung, das Urteil, den Beweis, die Anwendungsgrenzen und die Bedingung für eine Überprüfung (next_check).
Evidence ref: Strenger Verweis auf einen Beweis (Hook-Log, Diff-Unterschied, JSON-Schema, Given/When/Then-Szenario). Der Verifizierer akzeptiert keine Argumente ohne evidence_ref.
Stufenrotation (tier rotation): Testen derselben Spezifikation an verschiedenen Agentenpaaren (z. B. günstiges lokales Modell + teures Cloud-Modell). Zeigt die Abhängigkeit des Urteils von einer bestimmten KI auf.
Anti-Goodhart-Invarianten: Schutzmechanismus des Schiedsverfahrens, der verbietet, eine Metrik (z. B. MTTR) auf Kosten der Verschlechterung anderer zu verbessern (Anstieg von false_escalation_rate, rollback-flapping, silent_p0).
Decision trace: Reproduzierbares Phasenprotokoll einer Entscheidung, das die extrahierten Fakten, die Prüfungen roter Flaggen, die angewandte Richtlinie und das endgültige Urteil beschreibt.
Übungsaufgaben: Name: Ausführen des Lern-Runnable-Cases autoscale_200pct
Problem: Es muss ein Datei-Schiedsverfahren für die Spezifikation autoscale_spec.yaml durchgeführt werden. Dazu sind ein Duell zu starten, die Anti-Goodhart-Invarianten zu prüfen und das abschließende Entscheidungslogbuch zu erzeugen.
Lösung: 1. Wechseln Sie in das Beispielverzeichnis: cd book2/examples/tribunal. 2. Starten Sie das Duell-Skript: python3 scripts/run_duel.py --spec specs/autoscale_spec.yaml --cases cases/ --out out/duel.json. 3. Starten Sie die Invariantenprüfung: python3 scripts/check_invariants.py --metrics metrics/validation_metrics.json --out out/invariants.json. 4. Erzeugen Sie das Urteil: python3 scripts/write_judgment.py --duel-out out/duel.json --invariants-out out/invariants.json --to out/judgment.md.
Komplexität: beginner
Name: Übertragung eines Konflikts in die Präzedenzdatenbank
Problem: Im Verlauf der Bearbeitung von autoscale_200pct wurde ein wiederkehrender Konflikt aufgedeckt: Der automatische Modus erfordert audit_trace_coverage=1.0, aber der aktuelle Wert liegt bei 0.7. Dieser Präzedenzfall muss dokumentiert werden.
Lösung: Öffnen Sie die Datei precedents.md und fügen Sie eine YAML-Struktur hinzu: case_id: PREC-001, verdict: DENY, evidence_ref: tests/regression_001.json, applies_to: auto-remediation ohne vollständigen audit_trace, next_check: Duell bei Änderung von manual_review_floor wiederholen. Verweisen Sie im nächsten Streitfall auf PREC-001.
Komplexität: intermediate
Name: Verifizierung des Schutzes vor der Goodhart-Falle
Problem: Der Implementierer hat einen Plan vorgeschlagen, der die MTTR von 6 auf 2 Minuten senken soll, indem er aggressive Auto-Eskalation einsetzt. Sie müssen als Verifizierer den Plan ablehnen, falls er die Invarianten verletzt.
Lösung: Überprüfen Sie die Logik anhand der harten Stopp-Bedingungen in validation.md. Stellen Sie sicher, dass false_escalation_rate <= 0.05, rollback_flapping < 3/h und silent_p0_ratio == 0 gilt. Verletzt der Plan auch nur eine Bedingung, hält der Koordinator FAIL(reason=metric corruption) in judgment.md fest.
Komplexität: advanced
Fallstudien: Name: Schiedsverfahren bei einer Streitigkeit zur Ratenbegrenzung (Rate Limiting) im API-Gateway
Szenario: Die Spezifikation verlangt, bei einem Anfragen-Burst vorübergehend einen bestimmten Mandanten (tenant) zu drosseln, ohne den gesamten Dienst zu blockieren. Der Implementierer schlägt einen Patch vor, der tenant_id zum Deduplizierungsschlüssel hinzufügt, sowie burst_window_sec=60.
Aufgabe: Es muss sichergestellt werden, dass der Patch die Mandanten tatsächlich isoliert und nicht zu einer globalen Sperre führt. Wichtig ist, nicht nur die technische Plausibilität des Textes zu prüfen, sondern auch das Vorhandensein strenger Beweise.
Lösung: Der Verifizierer verlangt drei Beweise (evidence_ref): 1) Ein JSON-Schema, das tenant_id, limit_reason, expires_at vorschreibt; 2) Ein PreToolUse-Log, das die Änderung des globalen Limits verbietet; 3) Ein Given/When/Then-Szenario, das beweist, dass ein Burst von Mandant A das Kontingent von Mandant B nicht reduziert.
Ergebnis: Bei A/B-Tests stellte sich heraus, dass beim Paar „starker Implementierer + schwacher Verifizierer" der Patch abgelehnt wird, da die Beweise in einem langen Text versteckt sind und nicht in einem formalisierten Diff herausgestellt werden. In die Spezifikation wurde ein explizites Tenant-Isolationsszenario in Gherkin aufgenommen.
Gewonnene Erkenntnisse: Das Urteil muss sich auf formalisierte Beweise stützen, nicht auf die Autorität des Modells oder die Überzeugungskraft des Textes.
Eine Abweichung der Urteile bei der Stufenrotation bedeutet, dass die Anforderungen der Spezifikation nicht ausreichend portabel sind und durch einen Diff in validation.md verstärkt werden müssen.
Verwandte Konzepte: Stufenrotation
evidence_ref
JSON-Schema
Given/When/Then-Szenarien
Lerntipps: Achten Sie besonders auf den Unterschied der Beweisformate: schwache Modelle (local-coder) verstehen nur die minimal_form (kurzer diagnostic_code), während starke (frontier-reviewer) mit der extended_form (evidence_by_invariant-Struktur) arbeiten können.
Merken Sie sich die goldene Regel des Schiedsverfahrens: Ein Streit wird nur durch Unterschiede (diff) in requirements.md, hooks.md oder validation.md beigelegt. Chat-Korrespondenz ist kein Beweis.
Verwenden Sie beim Selbststudium das Skript matrix.py, um zu prüfen, wie sich das Urteil beim Wechsel der KI-Agentenpaare (C1-C4) verändert.
Lernen Sie das Format decision_trace kennen – es hilft, Fakten von Bewertungen zu trennen und macht das Entscheidungsprotokoll für andere Verifizierer reproduzierbar.
Zusätzliche Ressourcen: Beispiel eines Datei-Schiedsverfahrens (runnable): book2/examples/tribunal/ und book2/examples/tribunal/matrix/
Projektcharta und Stimmgewichtung: Teil 3 (part-03-project-constitution.md#ключевые-идеи)
Feature-Validierungsartefakt: Teil 9 (part-09-feature-validation.md) – hier wird validation.md beschrieben
Kompatibilität mit qwen code cli: appendix-b-qwen-code-compatibility.md
Zusammenfassung: Das Datei-Schiedsverfahren verwandelt den Prozess der Code-Überprüfung von einer chaotischen Diskussion in ein strenges Verfahrensprotokoll. Die wichtigsten Werkzeuge sind dabei die Logbücher judgment.md und precedents.md; die Grundlage für Entscheidungen bilden formale Beweise (evidence_ref) wie Hook-Logs, JSON-Schemata und Given/When/Then-Testszenarien. Der Ansatz ist durch Anti-Goodhart-Invarianten vor Metrikverzerrung und durch Stufenrotation vor der Voreingenommenheit bestimmter KI-Modelle geschützt. Die wichtigste Regel lautet: Wenn ein Beweis nicht in einer Datei vorliegt, darf der Koordinator den Eindruck eines Agenten nicht in ein offizielles Urteil umwandeln.