Lernleitfaden: Anwendungsteil 1. Wiederherstellung von Spezifikationen aus Legacy

Thema: Praxis-Teil 1. Wiederherstellung von Spezifikationen aus Legacy

Schwierigkeitsgrad: Mittel (Mittel)

Geschätzte Lernzeit: 4-5 Stunden

Voraussetzungen: Kenntnisse des Materials aus Teil 13 des ersten Bandes (Wiederherstellung der Konstitution eines bestehenden Projekts).

Verständnis der Prinzipien der Arbeit mit Cloud-Infrastruktur (Kubernetes, Monitoring, Alerts).

Grundlegende Fähigkeiten im Umgang mit den Formaten JSON, YAML und Markdown.

Allgemeines Verständnis des Konzepts SDD (Specification-Driven Development).

Lernziele: Lernen, faktische Anforderungen (Kontrakte) und Hintergrund-Infrastrukturkontext (Memory Bank) klar voneinander zu trennen.

Die Sammlung und Normalisierung von Beweisen (evidence_ref) aus verteilten Quellen (Logs, Slack, Post-Mortems) in eine einheitliche Zeitskala beherrschen.

Fähigkeiten zur Extraktion impliziter Regeln und deren Umwandlung in überprüfbare Aussagen (Claims) unter Verwendung von KI (Qwen Code) erwerben.

Wiederhergestellte Anforderungen in der Verhaltenssprache (Given/When/Then) beschreiben und maschinenlesbare Kontrakte (JSON Schema) dafür entwerfen können.

Lernen, ein Register der Anforderungsherkunft (genealogy.md) zu führen, um Transparenz und Auditierbarkeit der Spezifikationen sicherzustellen.

Überblick: In diesem Lernmodul wird der Prozess der Wiederherstellung einer engineeringstauglichen Spezifikation (SDD) aus verstreuten Artefakten von Legacy-Systemen behandelt, etwa aus unstrukturierten Logs, Operator-Chats und Post-Mortems. Am Beispiel des Lehr-Produktionsmodells AgentClinic erfahren Sie, wie man Datenchaos in einen strengen, überprüfbaren Kontrakt verwandelt. Sie werden Methoden zur Normalisierung von Zeitskalen, zum Einsatz von KI zur Anforderungsextraktion mit Beweisbasis und zur Trennung von Geschäftslogik und Infrastrukturkontext (Memory Bank) beherrschen. Der Kurs betont, dass jede wiederhergestellte Anforderung auf Quellen beruhen muss und nicht auf Vermutungen.

Schlüsselkonzepte: Spec-Nekromantie (Wiederherstellung von Spezifikationen): Eine Engineering-Technik zur Rekonstruktion von Spezifikationen auf Grundlage beobachtbarer Artefakte (Logs, Metriken, Chats). Ermöglicht die Wiederherstellung der Systemlogik nach Teamabwanderung, gestützt auf eine überprüfbare Beweiskette statt auf abstrakte Vermutungen.

Memory Bank (Hintergrundmodell): Eine separate Schicht des Infrastrukturkontexts (historische Vereinbarungen, Cluster-Topologie, Teamnamen). Diese Informationen helfen bei der Interpretation von Fakten, sind aber für sich genommen keine Geschäftsanforderung (Kontrakt) und gehören nicht in die Triage-Logik.

Evidence ref (Beweisreferenz): Ein Verweis auf eine konkrete Stelle im Quell-Artefakt (z. B. eine Zeile im Log, eine Slack-Nachricht), der die Wahrheit einer Aussage belegt. Eine Anforderung ohne evidence_ref gilt lediglich als Hypothese.

Genealogy.md (Provenienz-Register): Eine Datei, die die Herkunft jeder Anforderung beschreibt. Im Gegensatz zu git log zeigt sie nicht nur, wer und wann eine Datei geändert hat, sondern auch, woher die Regel stammt, das Konfidenzniveau (uncertainty), unterstützende Quellen und offene Fragen.

Kandidaten-Aussage (Claim): Ein aus Daten extrahiertes Muster oder eine Regel, versehen mit Beweisen, Gegenbeispielen und einer Konfidenzbewertung. Der Kandidatenstatus kann 'approved', 'needs_clarity' oder 'rejected' sein.

Normalisierte Zeitkette: Eine Folge von Ereignissen, die auf eine einheitliche Zeit (UTC) und ein einheitliches Format gebracht und von Duplikaten bereinigt wurde. Sie verknüpft Logs, Alerts und Operator-Aktionen in chronologischer Reihenfolge.

Übungsaufgaben: Titel: Trennung von Kontrakt und Hintergrundkontext

Problem: Ihnen liegt eine Liste von Auszügen aus dem Post-Mortem eines Vorfalls vor:

1. 'Der Service appointments-api begann, in 10 Minuten >90 % des Speichers zu verbrauchen.'
2. 'Der Bereitschaftsingenieur Iwan meldete im Slack-Kanal #incidents, dass dies kein geplanter Deploy war.'
3. 'Das Deployment erfolgte im canary namespace.'
4. 'Das NOC-Team erhielt den Alert nach 15 Minuten.'

Aufgabe: Teilen Sie diese Fakten in zwei Kategorien: 'Anforderungen (SDD)' und 'Memory Bank'. Begründen Sie Ihre Entscheidung.

Lösung: 1 und 4 — Anforderungen (SDD). Sie beschreiben beobachtbares Systemverhalten und SLA (Speicherverbrauchsauslöser und Reaktionszeit). 2 und 3 — Memory Bank. Der Name des Bereitschaftsingenieurs und die Tatsache, dass der canary namespace verwendet wurde, sind Kontext, der hilft, die Situation zu verstehen, aber nicht fest in die Geschäftslogik der Triage-Pipeline als universelle Regel integriert werden sollte.

Schwierigkeit: Anfänger

Titel: Erstellen eines Eintrags in genealogy.md

Problem: Erstellen Sie auf Grundlage des Lehr-Auszugs einen YAML-Snippet für die Datei genealogy.md. Aussage: 'Bei memory_percent >= 90 % über 10 min für appointments-api wird P1 erstellt'. Setzen Sie den Status auf 'needs_clarity', da keine Daten zu Schließungsbedingungen vorliegen.

Lösung: - claim: "Bei memory_percent >= 90 % über 10 min für appointments-api wird P1 erstellt." status: needs_clarity evidence_ref:

• "grafana:HM-2026-05-17-01"
• "postmortem:api-memory-2026-05"

uncertainty: medium open_questions:

• "Ist das Verbot von auto-resolve ohne stabile Fenster bestätigt?"
• "Welche genaue Schwelle gilt für die Schließung des Vorfalls?"

Schwierigkeit: Mittel

Titel: Doppelschreibung der Spezifikation (Given/When/Then + JSON Schema)

Problem: Überführen Sie die wiederhergestellte Anforderung in das Given/When/Then-Format und schreiben Sie ein minimales JSON Schema zur Validierung der Auslöseschwelle und der SLA. Anforderung: 'Wenn >=3 NodeNotReady innerhalb von 10 Minuten auf einem Knoten erfasst werden, wird ein P1-Vorfall mit einer erwarteten Reaktionszeit von 8 Minuten erstellt.'

Lösung: Given der Cluster befindet sich in einer aktiven Schicht und das Monitoring-System erfasst Metriken; When >=3 NodeNotReady-Ereignisse für einen Knoten innerhalb von 10 Minuten eingehen; Then erstellt das System einen Vorfall mit severity=P1 und legt eine Reaktions-SLA von 8 Minuten fest.

JSON Schema: { "$id": "urn:spec:node-not-ready:v1", "type": "object", "required": ["rule_id", "severity", "sla_minutes", "conditions"], "properties": { "rule_id": {"type": "string"}, "severity": {"type": "string", "enum": ["P0", "P1", "P2", "P3"]}, "sla_minutes": {"type": "integer", "minimum": 1, "maximum": 120}, "conditions": { "type": "object", "required": ["event_code", "count", "window_minutes"], "properties": { "event_code": {"type": "string"}, "count": {"type": "integer", "minimum": 3}, "window_minutes": {"type": "integer", "minimum": 1} } } } }

Schwierigkeit: Fortgeschritten

Fallstudien: Titel: Wiederherstellung der Eskalationslogik nach Abwanderung des SRE-Teams

Szenario: In einem Projekt zur automatischen Verwaltung von Vorfällen kam es zur Abwanderung von Schlüsselpersonal. Als Hinterlassenschaft blieben 47 Seiten ungefilterter Logs, Slack-Threads, Dashboard-Screenshots und textuelle Post-Mortems. Das neue Team soll eine Triage-Pipeline auf Basis von Qwen Code aufbauen, aber ein formales Spezifikationsdokument (SDD) existiert nicht.

Herausforderung: Die Informationen sind chaotisch: Die Logs enthalten über 1200 Ereignisse mit unterschiedlichen Zeitzonen, in den Chats vermischen sich reale Vorfälle mit Diskussionen über geplante Arbeiten. Es besteht ein hohes Risiko, dass das KI-Modell (Qwen Code) eine zufällige Chat-Phrase oder eine clusterspezifische Topologie als universelle Geschäftsregel auffasst.

Lösung: Das Team wendete die Methode der 'Spec-Nekromantie' an:

1. Bestandsaufnahme und Normalisierung der Daten: Überführung aller Zeitstempel in UTC, Filterung von Rauschen, Erstellung einer einheitlichen Zeitskala.
2. Trennung der Schichten: Herauslösung überprüfbarer Anforderungen (Auslöser, SLA, Schließungsbedingungen) und Überführung des Rests in die Memory Bank.
3. Anforderungsextraktion mittels KI: Einsatz von Qwen Code im Analyse-Modus mit der strikten Anforderung, für jede Aussage eine evidence_ref anzugeben.
4. Führung von genealogy.md: Festhalten der Herkunft jeder Regel, um solide durch Post-Mortems belegte Fakten von unbestätigten Hypothesen zu unterscheiden.

Ergebnis: Statt einer Sammlung plausibler Vermutungen erhielt das Team eine engineeringstaugliche Spezifikation. Der abgestimmte Kontrakt wurde im Given/When/Then-Format und als JSON Schema ausgedrückt, wodurch das Verhalten der Triage-Pipeline automatisch validiert werden konnte.

Lernerkenntnisse: Maskieren Sie strittige Hypothesen niemals als genehmigte Kontrakte. Verwenden Sie den Status needs_clarity und das Unsicherheitsniveau.

Der Fensterfilter (z. B. [-15m,+5m] relativ zum Alert) ist entscheidend, um manuelle Aktionen im Chat mit automatischen Ereignissen in den Logs zu verknüpfen.

Ausnahmen (z. B. canary namespace) dürfen nicht als Rauschen entfernt werden; sie weisen oft auf versteckte Spezifikationsbedingungen hin.

Verwandte Konzepte: evidence_ref

memory bank

genealogy.md

Spec-Nekromantie

Qwen Code

Titel: Analyse des Vorfalls node_not_ready: Aufdecken versteckter Schwellenwerte

Szenario: Analysiert wird ein konkreter historischer Vorfall NR-2026-05-17-01. Grafana zeigt 3 NodeNotReady-Ereignisse auf dem Knoten worker-07 innerhalb von 10 Minuten. Das System erstellte eine P1-Eskalation. Im Post-Mortem steht: 'auto-resolve was rejected until two stable OK windows'.

Herausforderung: Es gilt, die genauen Regeln wiederherzustellen: wann genau ein Ereignis zu P1 wird und wann es automatisch geschlossen werden kann. Die Ingenieure müssen verstehen, ob die Schwelle von 3 Ereignissen eine harte Regel oder ein Zufall ist und wie genau 'stable OK windows' im Code geprüft werden.

Lösung: 1. Erstellung einer Verhaltensgeschichte im Given/When/Then-Format.

1. Formulierung einer Kandidaten-Aussage (Claim): 'Bei >=3 NodeNotReady innerhalb von 10 Minuten wird P1 erstellt'.
2. Verknüpfung der Beweise (Verweis auf Grafana und Post-Mortem) über evidence_ref.
3. Festhalten der Schließungsbedingung im JSON Schema, das zwei aufeinanderfolgende OK-Fenster verlangt.
4. Herauslösung des strittigen Fakts (canary namespace) als offene Frage mit der Markierung uncertainty: medium.

Ergebnis: Es wurde eine überprüfbare Spezifikation erstellt, die die Triage-Logik rekonstruiert. Der strittige Punkt zum canary namespace landete nicht als universelle Regel im finalen SDD, sondern blieb im Status einer Hypothese, die anhand historischer Daten geprüft werden muss.

Lernerkenntnisse: Eine glatte textuelle Formulierung einer Anforderung ist weniger nützlich als ein Eintrag, der zeigt, wo die Anforderung belastbar ist und wo sie vom Service-Owner geprüft werden muss.

Die Doppelschreibung (Verhalten + JSON Schema) schließt die Lücke zwischen menschlichem Verständnis und maschineller Prüfung.

Verwandte Konzepte: Kandidaten-Aussage (Claim)

Normalisierte Zeitkette

JSON Schema

Given/When/Then

Lerntipps: Beginnen Sie mit einem engen Fokus: Wählen Sie für den ersten praktischen Schritt einen Claim, zwei Quellen und eine offene Frage. Versuchen Sie nicht, die gesamte Architektur auf einmal wiederherzustellen.

Üben Sie die Schichtentrennung: Stellen Sie sich beim Lesen jedes Post-Mortems die Frage — handelt es sich um beobachtbares Verhalten eines Kontrakts oder einfach um Kontext der Situation?

Üben Sie die Arbeit mit Qwen Code im Headless-Modus (Plan Mode): Verlangen Sie vom Modell nicht fertigen Text, sondern strukturiertes JSON mit den Feldern source, counterexample und missing_context.

Beachten Sie den Unterschied zwischen git blame und genealogy.md. Git zeigt, wer die Zeile im Code hinzugefügt hat, während genealogy.md erklärt, auf Grundlage welcher Logs und Chats genau diese Geschäftsentscheidung getroffen wurde.

Weitere Ressourcen: Teil 13 des ersten Bandes des Lehrbuchs: Basismaterial zur Wiederherstellung der Konstitution eines bestehenden Projekts. Empfohlen vor Beginn dieses Moduls.

Teil 8 (Multi-Agenten-Schiedsverfahren): Fortgeschrittenes Material für den vollständigen Produktions-Track. Beschreibt die Rollen Verifier, Implementor und Safety zur Auflösung strittiger Spezifikationen.

Github spec kit: Externe Ressource, die die Philosophie von SDD 'Spezifikation als ausführbares Artefakt' beschreibt.

Vorlage genealogy.md (book2/examples/templates/): Praktische Vorlage, die zur Bearbeitung der Kursübungen erforderlich ist.

Zusammenfassung: Die Wiederherstellung von Spezifikationen aus Legacy ist ein Prozess der Transformation des Chaos historischer Daten in einen strengen, validierbaren Kontrakt. Der Schlüssel zum Erfolg liegt in der strikten Trennung von faktischen Anforderungen (SDD) und Infrastrukturkontext (Memory Bank). Der Einsatz von KI hilft, Kandidaten für Anforderungen zu extrahieren, aber jede solche Aussage muss durch Beweise (evidence_ref) gestützt sein. Die Doppelschreibung (menschenlesbares Given/When/Then und maschinenlesbares JSON Schema) in Verbindung mit dem Führen eines Herkunftsregisters (genealogy.md) stellt sicher, dass die Spezifikation nicht nur eine Sammlung plausibler Vermutungen ist, sondern ein auditierbares Engineering-Artefakt.