Thema: Praxis Teil 7. Specification CI: Spezifikation als ausführbares Artefakt
Schwierigkeitsgrad: Mittel
Geschätzte Lernzeit: 3-4 Stunden
Voraussetzungen: Verständnis der Funktionsprinzipien von CI/CD (z. B. GitHub Actions)
Erfahrung im Umgang mit Markdown und JSON
Grundkenntnisse in Python zur Modifikation von Prüfskripten
Vertrautheit mit den Konzepten Anforderungen (requirements) und Pläne (plans) in der Entwicklung
Lernziele: Eine CI-Pipeline zur automatischen Validierung von Spezifikationen (requirements.md, plan.md) einrichten.
Eine Abdeckungsprüfung (Coverage Check) für die Verknüpfung von Anforderungen (REQ-*) mit Planausgaben implementieren.
Eine JSON-Schema-Validierung für Fixtures erstellen, die aus validation.md extrahiert wurden, einschließlich der Prüfung negativer Tests.
Verständliche diagnostische Fehlermeldungen für CI erzeugen, die auf Datei, Zeile und Korrekturmaßnahme hinweisen.
Spec CI zur Validierung atomarer Pläne agentenbasierter Systeme (AoT-Gateway) anwenden.
Übersicht: Dieser Lernleitfaden widmet sich der Umwandlung statischer Dokumentation (Spezifikationen) in ausführbare Artefakte, die im Rahmen von CI/CD geprüft werden. Wir betrachten, wie sich mit GitHub Actions und Python-Skripten die Qualitätsprüfung von Spezifikationen automatisieren lässt. Die Kernidee besteht darin, ein „Spezifikations-Gateway“ (Spec Gate) zu schaffen, das das Zusammenführen (Merge) eines Pull Requests blockiert, wenn Verstöße vorliegen: nicht abgedeckte Anforderungen, Überschreitung des Domänenbereichs (Scope) oder Fehler in JSON-Fixtures. Der Ansatz basiert auf dem Prinzip: Eine Spezifikation ist nur dann nützlich, wenn sie automatisch abgelehnt werden kann.
Schlüsselkonzepte: Spezifikations-Gateway (spec gate): Ein obligatorischer Schritt in der CI, der die Spezifikation ebenso streng prüft wie gewöhnliche Tests den Code. Es blockiert das Zusammenführen eines PR, sobald semantische oder strukturelle Fehler in der Dokumentation erkannt werden.
Abdeckungsprüfung (coverage check): Verfahren zur Validierung des Verknüpfungsgraphen zwischen requirements.md und plan.md. Jede Anforderung (REQ-) muss eine implementierende Aufgabe im Plan haben (implements: [REQ-]), und jede Aufgabe muss mit einer Anforderung verknüpft sein (keine „rogue tasks“).
Bereichsprüfung (scope check): Validierung, dass die Aktionen in plan.md den zulässigen Operationen des Domänenmodells entsprechen (z. B. incident-response.yaml). Sie blockiert „fremde“ Szenarien, wie das nicht autorisierte automatische Schließen eines Vorfalls.
Schema-Prüfung (schema check): Extraktion von JSON-Beispielen (Fixtures) aus validation.md und deren Prüfung gegen ein JSON-Schema. Dies umfasst sowohl positive (müssen bestehen) als auch negative (müssen vorhersagbar fehlschlagen) Szenarien.
Aot-Gateway (atom of thought gate): Spezifische Prüfung für Pläne, die von KI-Agenten erzeugt werden. Der Plan wird als Graph atomarer Aktionen dargestellt und vor der Ausführung auf unbekannte Werkzeuge, Abhängigkeitszyklen und Bereichsüberschreitungen geprüft.
Übungsaufgaben: Name: Lokale Prüfung der Anforderungsabdeckung
Problem: Es liegen die Dateien requirements.md und plan.md vor. Es ist sicherzustellen, dass alle Anforderungen aus requirements.md entsprechende Aufgaben in plan.md haben und dass keine „verwaisten“ (rogue) Aufgaben existieren. Führen Sie einen lokalen Lauf des Skripts zur Abdeckungsprüfung aus.
Lösung: 1. Wechseln Sie in das Beispielverzeichnis: cd book2/examples/spec-ci. 2. Starten Sie das Skript: python3 scripts/check_coverage.py --requirements requirements.md --plan plan.md. 3. Stellen Sie sicher, dass das Skript den Rückgabecode 0 (Erfolg) liefert und eine Meldung über die erfolgreiche Abdeckung aller REQ-*-Kennungen ausgibt.
Komplexität: beginner
Name: JSON-Schema-Validierung und negative Tests
Problem: JSON-Fixtures für Vorfälle sind gegen das Schema incident_payload.schema.json zu prüfen. Eine der Fixtures ist absichtlich fehlerhaft (es fehlt incident_id). Es ist sicherzustellen, dass das Skript sie korrekt zurückweist.
Lösung: 1. Wechseln Sie in book2/examples/spec-ci und führen Sie aus: python3 scripts/validate_schema.py --schema schemas/incident_payload.schema.json --fixtures fixtures. 2. Überprüfen Sie die Ausgabe: Das gültige Fixture muss bestehen, für das ungültige muss eine Fehlermeldung erscheinen (z. B. „missing required property incident_id“). 3. Stellen Sie sicher, dass der Prozess korrekt beendet wird und die gefundene Abweichung signalisiert.
Komplexität: intermediate
Name: Formatierung einer diagnostischen CI-Meldung
Problem: Das Skript check_scope.py hat festgestellt, dass in plan.md die Aktion „force_resolve“ verwendet wird, die im Domänenmodell nicht zulässig ist. Erstellen Sie ein JSON-Fehlerobjekt, das den Anforderungen an eine gute Diagnose entspricht: verständlicher Grund, Dateiverweis, Regelkennung und Korrekturmaßnahme.
Lösung: Die JSON-Antwort sollte in etwa so aussehen: { "status": "failed", "check": "scope", "file": "plan.md", "line": 48, "rule": "IR-SCOPE-007", "reason": "Autonomous force resolve is outside the incident-response domain model", "action": "Replace with POST /incidents/{id}/ack or add an approved requirement and domain rule" }
Komplexität: intermediate
Name: Validierung eines agentenbasierten Plans (AoT)
Problem: Ein Agent hat einen Plan im JSON-Format erzeugt, der ein Array von atoms enthält. Erstellen Sie eine Regel (oder ein Skriptkonzept), die den Plan ablehnt, wenn ein Atom auf ein nicht existierendes Werkzeug „delete_database“ verweist.
Lösung: Das Skript soll das Feld „name“ jedes Atoms lesen und mit der Liste zulässiger Werkzeuge (Whitelist) aus dem Domänenmodell vergleichen. Fehlt „delete_database“ in der Whitelist, soll das Skript einen Fehler.fail und eine JSON-Diagnose der Form {'reason': 'Unknown tool', 'action': 'Remove atom or update domain model'} zurückgeben.
Komplexität: advanced
Fallstudien: Name: Blockieren des unautorisierten Schließens eines Vorfalls
Szenario: Ein Team entwickelt Automatisierung für das Incident-Management. Ein Entwickler erstellt einen Pull Request und fügt einen neuen Schritt in plan.md hinzu, um einen Vorfall automatisch aufzulösen (force-resolve) – ohne Bestätigung des diensthabenden Engineers, um den Vorgang zu „beschleunigen“.
Aufgabe: Ein textbasiertes Review kann diese Änderung übersehen, wenn sie formal an eine Anforderung gebunden ist. Eine solche Aktion verletzt jedoch die Geschäftslogik und die Sicherheit des Prozesses (ein kritischer Fehler könnte verschleiert werden).
Lösung: Es wurde ein Spec-Gateway mit Bereichsprüfung (Scope Check) eingeführt. Das Skript check_scope.py glich die Aktion „force_resolve“ mit dem Domänenmodell incident-response.yaml ab und stellte fest, dass diese Operation für autonome Systeme nicht zulässig ist.
Ergebnis: GitHub Actions blockierte das Zusammenführen des PR. Der Entwickler erhielt einen automatischen Kommentar mit Angabe der Datei (plan.md), der Zeile und der Regel, die das autonome Schließen untersagt. Die gefährliche Logik gelangte nicht in die Produktion.
Gewonnene Erkenntnisse: Die Prüfung des Anforderungstextes allein reicht nicht aus; es muss die Semantik der Aktionen geprüft werden.
Die Automatisierung des Spezifikations-Reviews entlastet das Team und verhindert den „menschlichen Faktor“.
Das Gateway muss nicht nur das Vorhandensein einer Referenz (coverage) prüfen, sondern auch den Inhalt (scope).
Verwandte Konzepte: Scope Check
Domain Model
Pull Request Protection
Name: Integration mit Grafana: Absicherung des Payload-Vertrags
Szenario: Ein Projekt integriert sich über Webhooks in ein Monitoringsystem (z. B. Grafana). In validation.md werden JSON-Payload-Beispiele aufbewahrt, die zum Testen der Integration dienen.
Aufgabe: Bei einer Aktualisierung des API-Vertrags änderte Grafana das Format des Felds „source“ oder entfernte „incident_id“. Der Entwickler aktualisierte den Code, vergaß jedoch, die Dokumentation und die Testbeispiele anzupassen. Dies hätte zu einer „stillen“ Regression führen können, bei der ein Alert eintrifft, aber nicht verarbeitet wird.
Lösung: Einsatz der Schema-Prüfung (Schema Check). Das Skript extract_fixtures.py extrahierte die JSON-Blöcke aus validation.md, und validate_schema.py prüfte sie gegen das aktuelle Schema incident_payload.schema.json.
Ergebnis: Die CI schlug in der Spec-Gate-Phase fehl. Das Team sah die Fehlermeldung: „validation.md:72 missing required property incident_id“. Dokumentation und Fixtures wurden vor dem Zusammenführen des Codes aktualisiert, was einen Integrationsausfall in der Produktion verhinderte.
Gewonnene Erkenntnisse: Eine Spezifikation muss „ausführbar“ sein – bei jeder Änderung automatisch geprüft.
Negative Beispiele (Gegenbeispiele) sind ebenso wichtig wie positive, um die Strenge eines Schemas zu prüfen.
Integrationsverträge dürfen keine „Vereinbarung“ sein, sie müssen maschinell validiert werden.
Verwandte Konzepte: JSON Schema Validation
Fixtures
Negative Testing
Lerntipps: Beginnen Sie mit einem lokalen Lauf: Bevor Sie einen komplexen GitHub-Actions-Workflow einrichten, stellen Sie sicher, dass die Skripte check_coverage.py und validate_schema.py in Ihrer lokalen Umgebung korrekt funktionieren (cd book2/examples/spec-ci).
Fokus auf Diagnose: Widmen Sie dem Format der Fehlerausgaben besondere Aufmerksamkeit. Der eigentliche Wert von Spec CI liegt nicht darin, „auf einen Fehler hinzuweisen“, sondern darin, einen Hinweis zu geben, wie er behoben werden kann (Datei, Zeile, Regel, Aktion).
Verwenden Sie negative Fixtures: Üben Sie sich darin, Schemas zu erstellen, die fehlerhafte Daten strikt zurückweisen. Wenn eine fehlerhafte Payload das Schema passiert, ist das Schema zu lasch.
Verknüpfen Sie die Dokumentationsebenen: Denken Sie daran, dass Anforderungen, Plan und Validierung miteinander verbundene Schichten sind. Eine Änderung in requirements.md sollte eine Prüfung auslösen, ob sie in plan.md abgedeckt ist.
Zusätzliche Ressourcen: Github spec kit: Ein GitHub-Repository, das den SDD-Ansatz (Specification-Driven Development) demonstriert, bei dem Anforderungen und Pläne zu prüfbaren Schichten werden.
Json schema documentation: Die offizielle Dokumentation von JSON Schema, die notwendig ist, um zu verstehen, wie man strenge Verträge für die Validierung von Fixtures erstellt.
Course materials part 9 & 16: Die ursprünglichen Kursteile (Feature Validation und Team Code Review), die die manuellen Prozesse beschreiben, die in diesem Kapitel automatisiert werden.
Zusammenfassung: Specification CI (Spec CI) verwandelt Dokumentation in ein ausführbares Artefakt, das ebenso streng geprüft wird wie Code. Die Einführung eines automatischen Gateways (Spec Gate) in CI/CD blockiert das Zusammenführen von Änderungen, wenn Verknüpfungen zwischen Anforderungen und Plan fehlen, der Domänenbereich verlassen wird oder die JSON-Payload nicht dem Schema entspricht. Dadurch verlagert sich der Fokus von einer subjektiven Textprüfung hin zu einer maschinellen Validierung von Struktur und Semantik, was Reproduzierbarkeit und Sicherheit der Incident-Pipeline gewährleistet.