Thema: Anhang C. Checklisten für angewandtes SDD
Schwierigkeitsgrad: Mittelstufe
Geschätzte Lernzeit: 4-6 Stunden
Voraussetzungen: Studium der grundlegenden Checklisten für Spezifikation, Implementierung und Zusammenführung aus dem ersten SDD-Band.
Verständnis der Konzepte von CI/CD und Validierungsautomatisierung.
Vertrautheit mit der grundlegenden Struktur von Artefakten: requirements.md, plan.md, validation.md, QWEN.md.
Erfahrung im Umgang mit Markdown und Versionskontrollsystemen.
Lernziele: Lernen, spezialisierte Checklisten in jeder Phase des angewandten SDD-Zyklus anzuwenden.
Mechanismen für den Umgang mit Legacy-Systemen und die Beilegung strittiger Änderungen durch Datei-Schiedsverfahren beherrschen.
Die Prinzipien der sicheren Konfiguration von Auto-Remediation und des Schutzes vor dem Goodhart-Gesetz bei der Metrikoptimierung verstehen.
Die Methodik der 'vergifteten Spezifikation' zur Überprüfung der Robustheit von Validierungsprozessen verstehen.
Ein Projektpaket im Verzeichnis capstone/ erfolgreich für die abschließende Production-Prüfung vorbereiten.
Übersicht: Dieser Lernleitfaden ist ein detailliertes Handbuch zur Verwendung von Anhang C während des angewandten Software Design Document (SDD)-Zyklus. Das Material baut auf den grundlegenden Konzepten des ersten Bandes auf und konzentriert sich auf fortgeschrittene Szenarien: die Arbeit mit Legacy-Systemen, die Einführung von Delta-Schiedsverfahren, den Schutz von Metriken vor Manipulation und die Vorbereitung auf das finale Audit. Der Leitfaden beschreibt strenge Kriterien für Spezifikations-Gates (Spec CI), Anforderungen an die Beweisbasis und Regeln zum Stoppen der Automatisierung bei Erkennung von Antimustern.
Schlüsselkonzepte: Vergiftete Spezifikation (poisoned spec): Ein absichtlich in das System eingebrachter, genau ein Defekt zur Überprüfung der Wirksamkeit der Qualitätskontrollprozesse. Das erwartete Fehlersymptom muss im Voraus beschrieben werden, und eine erfolgreiche Korrektur muss die Artefakte (spec/plan/validation) betreffen, nicht nur textliche Erklärungen.
Datei-Schiedsverfahren (file arbitration): Eine Methode zur Beilegung von Streitigkeiten im Team, bei der der Fokus von textuellen Chat-Diskussionen auf die Analyse von Unterschieden (diff) in den eigentlichen Dateien verlagert wird. Erfordert eine strikte Rollenverteilung (Koordinator, Implementer, Verifizierer).
Goodhart-Gesetz und Anti-Goodhart-Metriken: Das Prinzip, dass eine Metrik aufhört nützlich zu sein, sobald sie zum Ziel wird. Zum Schutz des Systems muss jede Zielmetrik eine gepaarte Schutzmetrik (Anti-Goodhart) und eine 'Notaus-Regel' haben.
Auto-Remediation (auto-remediation): Ein automatisierter Prozess zur Wiederherstellung des Systems nach einem Ausfall. Erfordert die vorherige Festlegung des Auswirkungsradius, einen obligatorischen Dry-Run (Testlauf) und strenge Rollback-Bedingungen, die vor Beginn der Ausführung dokumentiert werden.
Spezifikations-Gate (spec ci): Continuous Integration für Anforderungen. Überprüft das Vorhandensein stabiler REQ-*-Identifikatoren, die Verknüpfung des Plans mit den Anforderungen und die Gültigkeit von JSON-Beispielen. Ein Fehler im CI muss umfassende Informationen enthalten: Datei, Zeile, Regel, Grund und Aktion.
Genealogie- und Traceability-Artefakte (genealogy & evidence): Das Prinzip, dass jede Entscheidung, Metrik oder jeder Eintrag in QWEN.md einen Autor, eine Entscheidungsquelle (Hash des Prompts/der Policy), einen Beweis und ein Konfidenzniveau haben muss.
Übungsaufgaben: Name: Einrichtung des Spezifikations-Gates (Spec CI)
Problem: Ihnen wird eine Liste unzusammenhängender Anforderungen an eine API zur Verfügung gestellt. Sie müssen diese für die Durchführung durch Spec CI vorbereiten und dabei die Verknüpfung von Plan und Validierung sicherstellen.
Lösung: 1. Weisen Sie jeder Anforderung eine eindeutige Kennung im Format REQ-01, REQ-02 usw. zu. 2. Erstellen Sie in plan.md Planpunkte, die direkte Verweise auf die entsprechenden REQ-*-Identifikatoren enthalten. 3. Beschreiben Sie die Verträge im Domainmodell. 4. Erstellen Sie JSON-Beispiele in validation.md und stellen Sie sicher, dass diese erfolgreich durch JSON Schema validiert werden. 5. Konfigurieren Sie die CI-Fehlerausgabe so, dass sie Datei, Zeile und Grund enthält.
Komplexität: mittel
Name: Einführung der 'vergifteten Spezifikation'
Problem: Das Team ist überzeugt, dass sein Validierungsprozess perfekt ist. Ihre Aufgabe ist es, dies zu beweisen oder zu widerlegen, indem Sie eine vergiftete Spezifikation in den Testsatz der Anforderungen einführen.
Lösung: 1. Wählen Sie einen konkreten Defekt (z. B. Änderung des Datentyps in einer API-Antwort). 2. Fügen Sie ihn in validation.md ein. 3. Dokumentieren Sie in einem separaten Dokument das erwartete Fehlersymptom. 4. Starten Sie die CI/Validierung. 5. Wird der Fehler nicht erkannt, aktualisieren Sie die Anforderungen (requirements.md) so, dass dieser Fehlertyp unmöglich wird (durch Änderung des Schemas oder der Spezifikation).
Komplexität: fortgeschritten
Name: Analyse von Antimustern im angewandten Zyklus
Problem: Das Projekt fällt in der Produktion ständig aus, weil das Team validation.md bei CI-Fehlern ständig aufweicht und keine Beschränkungen für mutable_rules hat. Führen Sie ein Audit anhand der Checkliste durch.
Lösung: 1. Führen Sie ein striktes Verbot der Bearbeitung von validation.md bei Testfehlern ein (der Code muss repariert werden). 2. Finden Sie alle Regeln in mutable_rules ohne TTL oder mit TTL > 90 Tagen und entfernen/aktualisieren Sie diese. 3. Konfigurieren Sie die Notaus-Regel (Veto von Safety) im governance_protocol. 4. Stellen Sie sicher, dass fallende CI durch Code behoben wird, nicht durch Validierung.
Komplexität: mittel
Fallstudien: Name: Krise der Auto-Remediation im Zahlungsgateway
Szenario: Das Team führte ein Auto-Remediation-Skript zum Neustart hängender Zahlungsabwicklungsdienste basierend auf CPU-Metriken ein. Die Automatisierung sollte die MTTD (Mean Time To Detect) und MTTR (Mean Time To Resolve) senken.
Aufgabe: Bei einem weiteren Ausfall begann das Skript, die Dienste in einer Endlosschleife neu zu starten, was zu doppelten Transaktionen und einer Datenbanksperre führte. Der Auswirkungsradius war nicht im Voraus festgelegt, und das Skript hatte keine Stopp-Bedingung für ein manuelles Review.
Lösung: Das Team stoppte das Skript umgehend und wandte die Checkliste 'Vor der Auto-Remediation' an. Es wurden eingeführt: ein Testlauf (Dry-Run) in einer isolierten Umgebung, eine vor der Ausführung fest dokumentierte Rollback-Bedingung und ein Schwellenwert für manuelle Bestätigung bei wiederholtem Fehlschlag. Für das Monitoring wurde eine gepaarte Anti-Goodhart-Metrik (Anzahl doppelter Transaktionen) hinzugefügt, um eine blinde Jagd nach der Uptime-Zeit zu verhindern.
Ergebnis: Der Vorfall wurde lokalisiert. Die Auto-Remediation löst sich nun korrekt nur bei einem isolierten Ausfall aus; bei Erweiterung des Auswirkungsradius wechselt das System in den Wartemodus für manuelle Bestätigung (manual_review_floor).
Gewonnene Erkenntnisse: Führen Sie niemals eine Auto-Remediation ohne vorab dokumentierte Rollback-Bedingung ein.
Der Auswirkungsradius muss strikt dokumentiert werden.
Aggressive Automatisierung ohne Schutz (Anti-Goodhart-Metriken) führt zu Katastrophen.
Verwandte Konzepte: Auto-Remediation
Goodhart-Gesetz
Auswirkungsradius
Lerntipps: Erstellen Sie eine physische oder digitale Checklistenvorlage für jede Phase (Spec CI, Auto-Remediation usw.) und verwenden Sie diese in Ihrem aktuellen Projekt.
Achten Sie besonders auf den Unterschied zwischen '[runnable]' und '[project script]' — dies ist eine häufige Ursache für Verwirrung bei der Implementierung.
Verwenden Sie die 'Drei-Nein-Antwort'-Regel: Wenn drei Punkte des Antimustern-Audits verneint werden, stoppen Sie sofort das Hinzufügen neuer Automatisierung und korrigieren Sie den aktuellen Kreislauf.
Verknüpfen Sie praktische Aufgaben immer mit Artefakten (requirements.md, validation.md, genealogy.md) — im angewandten SDD ist die Beweisbasis wichtiger als der Code.
Zusätzliche Ressourcen: Teil 0 (Production Lab): Ausgangstext zur Auswahl des Lernvorfalls (incident-case) und zum Verständnis der capstone-Struktur.
Teil 12 (Antimustern-Audit): Detaillierte Analyse von Symptomen und Ursachen von Fehlern im angewandten Zyklus, die die Schnellcheckliste erweitert.
Ordner examples/templates/: Enthält zu studierende Pflichtvorlagen: pr-template.md, retrospective.md, clear-prompt.md, replan-prompt.md.
Anhang C des ersten Bandes: Grundlegende Checklisten, die das Fundament für den aktuellen fortgeschrittenen Leitfaden bilden.
Zusammenfassung: Anhang C stellt eine strenge Reihe von Validierungsbarrieren für den fortgeschrittenen angewandten SDD-Zyklus dar. Die Hauptregel des Leitfadens lautet: Automatisierung und Optimierung sind ohne strenge Kontrolle (Spec CI, Anti-Goodhart-Metriken, Dry-Run) unzulässig. Die erfolgreiche Absolvierung der abschließenden Production-Prüfung erfordert eine einwandfreie Traceability (genealogy.md, evidence_ref), die Fähigkeit, Vorfälle über Datei-Diffs zu bearbeiten, und die Fähigkeit des Systems, 'vergiftete Spezifikationen' zu erkennen. Wenn die grundlegenden Prozesse versagen, muss die Entwicklung bis zu deren Behebung pausiert werden.