Thema: Praxis-Teil 6. Auswahl von Schattenspezifikationen
Schwierigkeitsgrad: Mittelstufe
Geschätzte Lernzeit: 4-6 Stunden (einschließlich Arbeit mit Lernskripten und Kalibrierung)
Voraussetzungen: Verständnis der Prinzipien des Incident-Managements (Triage, Post-Mortem, MTTR)
Grundlegende Kenntnisse im Umgang mit der Kommandozeile (CLI) und Python
Allgemeines Verständnis des Konzepts von LLM-Agenten und Prompt-Engineering (Few-Shot-Beispiele)
Vertrautheit mit den Datenformaten YAML und JSON
Lernziele: Informelle Beobachtungen und Betriebsfolklore in das strukturierte Format 'Kontext → Merkmal → beobachtete Wirkung' übersetzen.
Den Vorhersagewert (Score) von Heuristiken auf der Grundlage historischer Vorfälle mit einer vorgegebenen Formel berechnen.
Eine automatisierte 'Auktion' zur Auswahl von Gewinnern unter einem begrenzten Token-Budget (Few-Shot-Slots) durchführen.
Versionsverwaltete Blöcke für QWEN.md und Quarantäne-Einträge mit Ablehnungsgründen erstellen.
Den Einfluss von Gewichtungskoeffizienten (insbesondere der Strafe für falsche Eskalationen) auf die Auktionsergebnisse analysieren.
Übersicht: Dieser Abschnitt widmet sich dem Umgang mit informellen Beobachtungen, die beim Support von Softwaresystemen entstehen. Häufig verwenden Ingenieure nützliche Heuristiken (z. B. 'nachts kürzer antworten' oder 'bei wiederkehrenden Symptomen die Historie anfordern'), die sich nur schwer als strenge Systemanforderungen formalisieren lassen. Hier wird der Begriff der Schattenspezifikationen (Shadow Specs) eingeführt — überprüfbare Heuristiken, die in der Triage-Phase helfen. Sie erfahren, wie Sie diese Beobachtungen in messbare Slots verwandeln, sie anhand historischer Daten bewerten (Auktion) und eine fundierte Entscheidung treffen: die Heuristik als versionierten Few-Shot-Hinweis in QWEN.md aufnehmen oder sie wegen des hohen Risikos von Fehlalarmen in Quarantäne schicken.
Schlüsselkonzepte: Schattenspezifikation (Shadow Spec): Eine überprüfbare Heuristik aus der Betriebspraxis. Sie ist keine verbindliche Systemanforderung, hilft aber dem Agenten oder Ingenieur, in der Triage-Phase schneller Entscheidungen zu treffen.
Few-Shot-Beispiel: Ein kurzes Beispiel im Prompt, das das gewünschte Antwortformat oder die Verhaltenslogik zeigt. Im Kontext von Schattenspezifikationen ist dies eine nützliche Heuristik, die für die Aufnahme in QWEN.md aufbereitet wurde.
Bewertungsjournal (Scorebook): Das Journal zur Wirtschaftlichkeit von Schattenspezifikationen. Es speichert Rohdaten, Bewertungsformel, Schwellenwerte, Budget, Kandidatenversionen und das Entscheidungsprotokoll. Schützt vor 'Autoritätsstreitigkeiten' und der Goodhart-Falle.
Auktion: Verfahren zur rangbasierten Auswahl von Heuristiken unter einem streng begrenzten Kontextbudget (in Tokens oder Slots).
Quarantäne: Status, den eine Heuristik erhält, die den Qualitätsschwellenwert nicht besteht. Der Kandidat wird nicht spurenlos gelöscht, sondern mit Ablehnungsgrund (z. B. high_false_escalation) und Überprüfungsdatum aufbewahrt.
Bewertungsformel: Mathematischer Ausdruck zur Berechnung des Werts einer Heuristik. Basislernvariante: score = 0.5mttr_gain + 0.3early_signal + 0.2coverage - 0.4false_escalation.
Daten-Drift: Synchronisationsverlust zwischen Zeitachsen und Identifikatoren in Incident-Quellen. Erfordert eine Deduplizierung und Normalisierung vor der Bewertung, um falsche Frühsignale zu vermeiden.
Übungsaufgaben: Name: Bewertung von Schattenkandidaten starten
Problem: Sie müssen die Bewertung (Score) für eine Liste von Schattenspezifikationen auf der Grundlage simulierter historischer Vorfälle berechnen. Verwenden Sie die Basisgewichtungen der Formel. Ziel ist es, ein korrektes Bewertungsjournal (scorebook.json) für die anschließende Entscheidungsfindung zu erhalten.
Lösung: 1. Öffnen Sie das Terminal und wechseln Sie in das Beispielverzeichnis: cd book2/examples/shadow-auction. 2. Führen Sie das Bewertungsskript aus: python3 scripts/score.py --candidates candidates/candidates.yaml --incidents data/incidents.jsonl --weights 0.5,0.3,0.2,0.4 --out out/scorebook.json. 3. Vergleichen Sie das Ergebnis mit der Referenz: diff -u outputs/scorebook.example.json out/scorebook.json.
Komplexität: beginner
Name: Auktion: Auswahl der Gewinner und Aussortieren von Rauschen
Problem: Führen Sie auf Basis der berechneten scorebook.json eine Auktion durch. Setzen Sie das Budget auf 2000 Tokens, die Annahmeschwelle auf 0.70 und die Ablehnungsschwelle auf 0.40. Die Kandidaten müssen in Gewinner (keep) und in Quarantäne (quarantine) aufgeteilt werden.
Lösung: 1. Bleiben Sie im Verzeichnis shadow-auction und führen Sie aus: python3 scripts/decide.py --scorebook out/scorebook.json --budget-tokens 2000 --keep-threshold 0.70 --reject-threshold 0.40 --out-auction out/auction.json --out-quarantine out/quarantine.json. 2. Überprüfen Sie den Inhalt von out/quarantine.json: Stellen Sie sicher, dass mindestens ein Eintrag vorhanden ist (z. B. shadow.alert.red_color_urgency) mit einem expliziten Ablehnungsgrund.
Komplexität: intermediate
Name: Kalibrierung der Strafe für falsche Eskalationen
Problem: In Ihrem Team sind die Kosten für falsche P1-Eskalationen deutlich höher als in der Basiskonfiguration. Verdoppeln Sie das Gewicht der Strafe (false_escalation) und beobachten Sie, wie sich die Zusammensetzung der Gewinner ändert.
Lösung: 1. Führen Sie score.py mit geänderten Gewichten aus: python3 scripts/score.py --candidates candidates/candidates.yaml --incidents data/incidents.jsonl --weights 0.5,0.3,0.2,0.8 --out out/scorebook_strict.json. 2. Führen Sie decide.py mit dem neuen Scorebook aus. 3. Halten Sie die Beobachtung fest: 'Bei verdoppelter Strafe fiel Kandidat X aufgrund des hohen Anteils falscher Eskalationen in die Quarantäne'.
Komplexität: advanced
Fallstudien: Name: Kampf gegen falsche Dringlichkeit: die rote Farbe des Dashboards
Szenario: Im Projekt zur automatischen Triage für den Dienst appointments-api schlug das Ingenieurteam folgende Heuristik vor: Wenn die Anzeige auf dem Dashboard rot leuchtet, soll der Agent die Severity des Vorfalls automatisch auf P1 hochstufen, da dies 'visuell Aufmerksamkeit erregt'.
Aufgabe: Intuitiv schien die Regel für schnelles Reagieren nützlich. Bei der Überprüfung stellte sich jedoch heraus, dass die rote Farbe häufig als visueller Akzent in unkritischen Situationen verwendet wurde und nicht dem tatsächlichen Tragweitenradius entsprach.
Lösung: Die Heuristik wurde als Schattenspezifikation shadow.alert.red_color_urgency formuliert und durch die Auktion geschickt. Die Bewertungsformel zeigte einen schwachen Anstieg von mttr_gain und einen hohen Anteil von false_escalation. Der Endscore rutschte ins Minus (-0.3081). Der Kandidat wurde mit dem Grund high_false_escalation in Quarantäne geschickt.
Ergebnis: Das System vermied toxisches Rauschen. Die Spezifikation gelangte nicht in QWEN.md, was eine Überlastung der Bereitschaftsingenieure durch falsche P1-Eskalationen verhinderte und das Vertrauen in die automatischen Empfehlungen des Agenten bewahrte.
Gewonnene Erkenntnisse: Intuitiv überzeugende Heuristiken ('Betriebsfolklore') können dem Triage-Prozess ernsthaften Schaden zufügen.
Es ist wichtig, nicht nur die Beschleunigung der Lösung (MTTR) zu bewerten, sondern auch den Preis eines Fehlers (Strafe für falsche Eskalationen).
Die Quarantäne muss den Ablehnungsgrund und die Bedingungen für eine Rückkehr enthalten (z. B. nach Änderung der UI-Richtlinien).
Verwandte Konzepte: Bewertungsjournal (Scorebook)
Falsche Eskalationen
Quarantäne
Name: Sprachumgehung bei Kaskadenausfällen
Szenario: Bei der Analyse von Post-Mortems bemerkte das Team ein Muster: Bei bestätigten P0-Vorfällen in kritischen Diensten übersprangen Bereitschaftsingenieure manchmal die Standard-Textvorlage und leiteten sofort eine Sprachkonferenz (Voice Handoff) ein, um das Problem an die zweite Eskalationsstufe zu übergeben.
Aufgabe: Diese informelle Beobachtung musste für den LLM-Agenten formalisiert werden, durfte aber nicht als universelle Regel gelten (P2-Vorfälle erforderten weiterhin eine asynchrone Textdokumentation). Ihr Wert musste unter einem begrenzten Budget an Few-Shot-Slots nachgewiesen werden.
Lösung: Die Beobachtung wurde in das Format 'Kontext → Merkmal → Wirkung' unter dem Namen shadow.p0.voice_handoff umgewandelt. In einer Stichprobe von 20 Vorfällen erreichte sie einen Score von 0.727 (starkes Frühsignal, null falsche Eskalationen, allerdings enge Abdeckung).
Ergebnis: Die Spezifikation gewann die Auktion und wurde als versioniertes Few-Shot-Beispiel mit striktem Kontext (nur für P0) in QWEN.md aufgenommen. Der Agent begann, den Sprachkanal nur dort zu empfehlen, wo die Verzögerung der Übergabe teurer ist als der Verlust des schriftlichen Kontexts.
Gewonnene Erkenntnisse: Seltene, aber präzise Signale haben einen hohen Wert, wenn ihr Kontext streng begrenzt ist.
Der Auktionsgewinner darf die formale Spezifikation nicht ersetzen — er wird als Few-Shot mit begrenzter TTL (Lebensdauer) eingeführt.
Das Format Kontext→Merkmal→Wirkung macht aus 'magischem Wissen' einen reproduzierbaren Slot.
Verwandte Konzepte: Few-Shot-Beispiel
Auktion
Normalisierung von Beobachtungen
Lerntipps: Überspringen Sie den Praxisteil nicht: Die Theorie der Auktion lässt sich am besten durch das Ausführen der Skripte score.py und decide.py im Verzeichnis examples/shadow-auction/ verinnerlichen.
Achten Sie auf die Formel score = 0.5mttr_gain + 0.3early_signal + 0.2coverage - 0.4false_escalation. Versuchen Sie, die Prioritäten gedanklich zu verändern — welchen Koeffizienten würden Sie in einem medizinischen Projekt erhöhen? Im E-Commerce?
Das wichtigste disziplinarische Prinzip dieses Abschnitts ist, leuchtenden Geschichten ohne Bewertungsjournal (Scorebook) nicht zu vertrauen. Verlangen Sie stets die Reproduzierbarkeit der Berechnungen.
Merken Sie sich den Unterschied: Eine formale Anforderung (requirements.md) erweitert den Systemvertrag, während eine Schattenspezifikation (Shadow Spec in QWEN.md) nur eine temporäre Erweiterung des Agentengedächtnisses mit einer angegebenen Überprüfungsfrist (TTL) ist.
Zusätzliche Ressourcen: Lernskripte und Daten: book2/examples/shadow-auction/ (enthält candidates.yaml, incidents.jsonl und Skripte zur Berechnung)
Vorherige Kursthemen: Teil 6 des ersten Bandes (Trennung von Wünschen und Anforderungen) und Teil 19 des ersten Bandes (Agentengedächtnis)
Anhang d (Kalibrierung): appendix-d-threshold-calibration.md — Abschnitt D.2 zur detaillierten Abstimmung der Gewichtungen im Produktions-Track
Github spec kit: https://github.com/github/spec-kit — Verwendung von .specify/memory/constitution.md als Schutzschicht gegen Drift
Zusammenfassung: Die Auktion der Schattenspezifikationen ist ein Mechanismus, um Betriebsfolklore und informelle Beobachtungen von Ingenieuren in eine verwaltbare und messbare Schicht von Heuristiken zu verwandeln. Sie übersetzen eine Beobachtung in das Format 'Kontext → Merkmal → Wirkung', bewerten sie anhand der Vorfallshistorie mit einer transparenten Formel und konkurrieren um ein begrenztes Kontextbudget. Die gewinnenden Spezifikationen gelangen als versionierte Few-Shot-Beispiele mit Lebensdauer und strengem Kontext in QWEN.md. Die Verlierer verschwinden nicht, sondern werden mit einem klar dokumentierten Grund (z. B. Risiko falscher Eskalationen) in Quarantäne geschickt, was den Entscheidungsprozess reproduzierbar und anfechtbar macht.