Artefakte in der Spec-Driven Development verwalten: der Model Atlas

Artefakte in der Spec-Driven Development verwalten: der Model Atlas

Teil der Serie Domain-Driven Design Meets AI.

Im Spec-Driven Development ist die Spezifikation kein einzelnes Dokument. Sie besteht aus allen Artefakten, die ein Team auf dem Weg erstellt, vom ersten Brainstorming bis zu den API-Verträgen. Dieser Beitrag zeigt, wie ein Domain Knowledge Graph diese Artefakte samt ihrer Historie zusammenhält und wie der Model Atlas sie sichtbar macht.

Wo Modellierungswissen verloren geht

Jede kollaborative Modellierung hinterlässt eine Spur von Artefakten. Ein Brainstorming, ein Business Model Canvas, eine Impact Map, eine Capability Map, eine Handvoll Domain Stories, ein EventStorming-Board, eine Context Map, Visual Glossaries, API Product Canvases und schließlich OpenAPI- und AsyncAPI-Spezifikationen.

Die meisten davon landen als Bilder in einem gemeinsamen Ordner. Verschiedene Personen erstellen sie in verschiedenen Workshops, oft mit Wochen Abstand. Wenn eine Entwicklerin den ersten API-Vertrag schreibt, weiß niemand mehr, warum das Notification-Aggregat sein Feld status verloren hat oder welcher Sticky auf welchem Board den Notification-Kontext zuerst benannt hat.

Domain-Driven Design beruht auf einer gemeinsamen Ubiquitous Language (Evans, 2003). Ist diese Sprache über Fotos, Screenshots und Erinnerungen verstreut, ist sie nicht geteilt. Sie ist lediglich abgelegt.

In unserem Buch DDD Meets AI begleiten wir die fiktive Community-Kochplattform Larder durch den Synergetic Blueprint: eine geführte Abfolge kollaborativer Modellierungsschritte vom ersten Brainstorming bis zur Implementierung. Jedes akzeptierte Artefakt jeden Schritts fließt in einen einzigen Domain Knowledge Graph und der Model Atlas zeigt, wie die Artefakte zusammenhängen. Gemeinsam bilden diese Artefakte die Spezifikation.

Ein Graph für alle Artefakte

Der Domain Knowledge Graph ist ein einzelner Graph im Resource Description Framework (RDF), geschrieben in Turtle (Beckett et al., 2014). Er folgt der allgemeinen Idee eines Knowledge Graphen: Entitäten und ihre Beziehungen sowie der Kontext, der nötig ist, um sie zu interpretieren (Hogan et al., 2021). Ein AI-Skill nimmt die Artefakte einzeln auf, und jede Aufnahme wird in den bestehenden Graphen eingefügt, statt einen neuen anzulegen.

Bei Larder wuchs der Graph in 62 Aufnahmeschritten: vom Brainstorming über Impact Maps, Capability Maps, Domain Stories, EventStorming-Boards und Context Maps bis zu API Product Canvases, Visual Glossaries je Aggregat und schließlich den OpenAPI- und AsyncAPI-Verträgen.

Drei Designentscheidungen machen den Graphen vertrauenswürdig statt nur groß:

• Herkunft an jedem Knoten. Jeder Begriff, jede Beziehung und jede Nachricht hält fest, aus welchem Artefakt sie stammt und von welcher Stelle darauf (zum Beispiel „Shopping branch, sticky 3 (yellow)“).
• Ehrliche Konfidenz. Jede Aussage ist markiert: direkt vom Artefakt abgelesen, vom Artefakt impliziert oder von der KI erschlossen. Im Larder-Graphen stehen 863 Aussagen auf den Artefakten, 73 sind impliziert und 35 erschlossen.
• Originalschreibweise bleibt erhalten. Begriffe werden mit SKOS-Labels gespeichert (Miles & Bechhofer, 2009). So bleibt „re ceiver“ aus einem handgezeichneten Glossar als alternatives Label von „receiver“ sichtbar, statt stillschweigend zu verschwinden.

Ein typischer Knoten sieht so aus:

Der Graph hält auch fest, was er nicht weiß. Als die erste Context Map die Kontexte Consent Management und Notification einführte, hatte keine Story, kein Board-Event, kein Glossarbegriff und keine Capability sie zuvor erwähnt. Die Aufnahme hat das nicht überdeckt, sondern eine offene Frage im Graphen angelegt. Der Larder-Graph enthält 86 solcher Fragen.

Historie statt Überschreiben

Der Graph überschreibt nie. Kommt ein neues Bild hinzu, entscheidet die Aufnahme zuerst, ob es das Modell erweitert oder ein früheres Artefakt überarbeitet. Dazu vergleicht sie das neue Artefakt mit den vorhandenen: Wie viel des neuen Inhalts ist bereits bekannt, und wie viel des alten Inhalts deckt das neue noch ab? Als die zweite Capability Map kam, teilte sie 95 % ihres Inhalts mit der ersten und deckte 90 % davon ab, also wurde sie als Überarbeitung erfasst. In unklaren Fällen fragt der Skill nach, statt zu raten.

Eine Überarbeitung behält die alten Aussagen und verknüpft die neuen mit ihnen:

• dkg:revisionOf verbindet das neue Artefakt mit seinem Vorgänger.
• dkg:supersedes verbindet eine geänderte Aussage, etwa eine neu klassifizierte Capability oder eine neu gezeichnete Kardinalität, mit der Aussage, die sie ersetzt.
• dkg:absentFrom hält fest, dass etwas weggefallen ist, statt es zu löschen.

Das Notification-Aggregat zeigt, warum das wichtig ist. In Version 1 seines Visual Glossary hingen receiver und status direkt an der Notification. In Version 2 führte das Team das Value Object delivery ein: Eine Notification enthält eine oder mehrere Deliveries, und jede Delivery trägt ihre Empfänger und einen Zustellstatus (NEW oder READ). Außerdem kam in Version 2 ein Zielgruppentyp hinzu (single oder community).

In einem Ordner voller Fotos verschwindet Version 1 einfach, oder sie ist zwar noch vorhanden, aber ein Vergleich ist kaum möglich. Im Graphen bleiben beide Versionen erhalten, und die Verschiebung von status nach delivery ist eine explizite, abfragbare Tatsache:

So kann ein Team frühere Entscheidungen mit dem heutigen Wissen hinterfragen, statt sie aus der Erinnerung neu zu verhandeln. Das ist eine Form von Living Documentation: Wissen, das als Nebenprodukt der Arbeit entsteht und nicht nachträglich aufgeschrieben wird (Martraire, 2019).

Der Model Atlas: den Graphen sehen

Eine Turtle-Datei mit fast 6.000 Zeilen ist vollständig, aber niemand liest sie. Der Model Atlas ist eine einzelne HTML-Seite, die jeden Graphen dieser Art lädt (einfach eine .ttl-Datei hineinziehen, z. B. Larder). Er zeigt ihn als Landkarte von Artefakten statt als Knäuel von Knoten, an dem nur eine Katze ihre Freude hätte.

Der Atlas gruppiert Artefakte nach ihrer Art: Workshop-Artefakte (Brainstorming, Canvases, Maps, Stories, Boards), Design-Artefakte (Aggregat-Glossare, Bounded Context Canvases, ADR-Logs) und Spezifikationen (OpenAPI und AsyncAPI). Für jeden Bounded Context zeichnet er dann eine Bahn von links nach rechts: den Kontext, seine API Product Canvases, seine Aggregat-Glossare und die daraus abgeleiteten API-Spezifikationen.

Drei Dinge werden auf einen Blick sichtbar:

• Abhängigkeiten. Man sieht, welcher Canvas in welches Glossar eingeflossen ist und welches Glossar in welchen Vertrag. Der Notification-Kontext hat zum Beispiel einen asynchronen und einen synchronen Canvas, die beide auf das Notification-Modell v2 verweisen; dieses wiederum speist die AsyncAPI- und die OpenAPI-Spezifikation.
• Versionen. Abgelöste Artefakte bleiben auf der Karte, abgeblendet und gestrichelt. Beim Vergleich zweier Versionen unterscheidet der Atlas, was in der neueren Version hinzugekommen ist, was nur in der älteren existiert und was ausdrücklich als weggefallen erfasst wurde.
• Lücken. Eine Bahn ohne Glossar oder ohne Vertrag fällt sofort auf. Im Ausschnitt geht der Kontext Grandma Avatar AI direkt von seinem Canvas zur AsyncAPI-Spezifikation, ohne Aggregat-Glossar dazwischen.

Der Atlas kann den Graphen auch abspielen. Ein Schieberegler geht die Aufnahmeschritte der Reihe nach durch, sodass man das Modell wachsen sieht: zuerst das Brainstorming, dann die Strategie-Artefakte mit ihren Überarbeitungen, dann die Stories und die Sprache.

Die Wiedergabe macht aus dem Graphen die Geschichte des Projekts. Neue Teammitglieder können nachvollziehen, wie das Modell entstanden ist, und das Team kann bei jedem Schritt anhalten und fragen, ob eine damals getroffene Entscheidung heute noch trägt.

Warum das für API-Verträge wichtig ist

Der Graph zahlt sich in jedem Schritt des Blueprints aus, und bei den API-Verträgen wird das am greifbarsten. In unserem Buch haben wir OpenAPI- und AsyncAPI-Spezifikationen zweimal generiert: einmal aus den API Product Canvases und einmal aus dem Domänenmodell. Beide Varianten landen im selben Graphen wie die Artefakte, aus denen sie abgeleitet wurden.

Dadurch werden Konsistenzprüfungen günstig. Ein AI-Skill kann einen Vertrag mit dem gültigen Visual Glossary seines Bounded Context vergleichen und jeden Begriff markieren, der von der Ubiquitous Language abweicht: ein Feld, das an einer Stelle receiver und an einer anderen recipient heißt, ein Statuswert, den das Glossar nie erwähnt, oder eine Eigenschaft, die noch die abgelöste Version 1 eines Aggregats widerspiegelt.

Nach Böckeler gehören Schnittstellendefinitionen in die Spezifikation und nicht in den Code (Böckeler, 2025). Die Spezifikationen gehören in den Domain Knowledge Graph, neben die Workshop-Artefakte, die sie begründen. Erst nach einer solchen Prüfung werden die API-Definitionen zu echten Verträgen zwischen Anbieter und Konsumenten (Junker & Lazzaretti, 2025).

Selbst ausprobieren

Alles ist öffentlich im Beispiel-Repository von DDD Meets AI:

• Model Atlas: die HTML-Datei herunterladen und im Browser öffnen. Man kann eine eigene .ttl-Datei laden.
• Domain Knowledge Graph für Larder: der vollständige Graph einschließlich seiner Historie.
• Quell-Artefakte: die Bilder aller aufgenommenen Artefakte, nummeriert in Aufnahmereihenfolge.

Am besten mit der Wiedergabe beginnen. Die Impact Maps durchgehen und beobachten, wie sich die Zielmetrik von Version zu Version ändert. Dann zur Notification-Bahn springen und die beiden Aggregatmodelle vergleichen.

Der ganze Blueprint ist die Spezifikation

Spec-Driven Development beginnt oft mit einem Anforderungsdokument oder einem API-Vertrag. Entlang des Synergetic Blueprint beginnt die Spezifikation viel früher: mit dem Brainstorming, den Canvases, den Maps, den Stories und den Glossaren, die jede spätere Entscheidung begründen.

Ein Domain Knowledge Graph hält all das an einem Ort zusammen, mit Quellen, Unsicherheiten und Historie. Der Model Atlas macht diese Historie sichtbar. So sieht ein Team, woher eine Entscheidung stammt, bevor es sie ändert, und kann jedes neue Artefakt gegen alles prüfen, was es bisher gelernt hat.

Dieser Beitrag basiert auf Kapitel 14, „AI-Enhanced REST API and Event Design“, des kommenden Buchs DDD Meets AI von Annegret Junker.

Literatur

References

Beckett, D., Berners-Lee, T., Prud’hommeaux, E., & Carothers, G. (2014). RDF 1.1 turtle: Terse RDF triple language [W3C Recommendation]. World Wide Web Consortium. https://www.w3.org/TR/turtle/

Böckeler, B. (2025). Understanding spec-driven-development: Kiro, spec-kit, and Tessl. martinfowler.com, “Exploring Gen AI” series. https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html

Evans, E. (2003). Domain-driven design: Tackling complexity in the heart of software. Addison-Wesley.

Hogan, A., Blomqvist, E., Cochez, M., d’Amato, C., Melo, G. de, Gutierrez, C., Kirrane, S., Labra Gayo, J. E., Navigli, R., Neumaier, S., Ngonga Ngomo, A.-C., Polleres, A., Rashid, S. M., Rula, A., Schmelzeisen, L., Sequeda, J., Staab, S., & Zimmermann, A. (2021). Knowledge graphs. ACM Computing Surveys, 54(4), 71:1–71:37. https://doi.org/10.1145/3447772

Junker, A., & Lazzaretti, F. (2025). Crafting great APIs with Domain-Driven Design: Collaborative craftsmanship of asynchronous and synchronous APIs. Apress. https://doi.org/10.1007/979-8-8688-1457-0

Martraire, C. (2019). Living documentation: Continuous knowledge sharing by design. Addison-Wesley.

Miles, A., & Bechhofer, S. (Eds.). (2009). SKOS simple knowledge organization system reference. W3C Recommendation. https://www.w3.org/TR/skos-reference/