Thema: Anhang B. Domain Map AgentClinic
Schwierigkeitsgrad: Mittelstufe
Geschätzte Studienzeit: 6-8 Stunden (Theorie + Praxis)
Voraussetzungen: Grundlegendes Verständnis der Webentwicklung (HTTP, Routen, Anfragen)
Vertrautheit mit relationalen Datenbanken (SQL, Tabellen, Beziehungen)
Verständnis des MVP-Konzepts (Minimum Viable Product)
Grundkenntnisse in TypeScript/JavaScript
Verständnis von Testprinzipien (überprüfbare Fakten, Assertions)
Lernziele: Selbstständig ein Domainmodell für ein Lernprojekt entwerfen, das Entitäten, deren Attribute und Beziehungen definiert, analog zu AgentClinic
Die vollständige Projektfunktionalität in SDD-Zyklenphasen unterteilen, die Reihenfolge der Hinzufügung von Routen erklären und die Priorität jeder Phase begründen
Minimale überprüfbare Fakten für jede Phase formulieren und eine Validierungs-Checkliste erstellen, die automatisiert werden kann
Den Domain-Wortschatz konsequent in allen Spezifikationen anwenden, terminologische Inkonsistenzen erkennen und korrigieren
Elemente des Lern-Domains von solchen unterscheiden, die eine separate Spezifikation erfordern, und diese Entscheidung begründen
Überblick: AgentClinic ist ein satirisches Lernprojekt, das den SDD-Zyklus (Specification-Driven Development) am Beispiel einer „Klinik für Software-Agenten“ demonstriert. Die Domain Map beschreibt die Struktur dieses Projekts: welche Entitäten existieren (Agenten, Leiden, Therapien, Terminbuchungen, Bewertungen), wie sie miteinander verbunden sind, welche Routen die Nutzerszenarien bedienen und wie die gesamte Funktionalität auf die Entwicklungsphasen verteilt wird. Die Kernidee ist, dass der Domain absichtlich einfach bleibt, aber ausreichend reichhaltig ist, um alle Aspekte des SDD zu demonstrieren: vom ersten „Hello Hono“ bis zum Admin-Panel mit Zählerprüfung. Dabei schließt das Projekt bewusst komplexe reale Szenarien aus (Zahlungen, Autorisierung, externe Integrationen), um den Fokus auf dem Prozess der entwicklungsgestützten Spezifikation zu halten.
Kernkonzepte: Domain Map: Eine visuelle und textuelle Beschreibung des Problembereichs eines Projekts, einschließlich Entitäten, deren Attribute, Beziehungen und Grenzen. In AgentClinic dient die Domain Map als gemeinsame Sprache zwischen Entwicklern, Testern und Spezifikationen. Sie schreibt keine konkrete Implementierung vor, sondern setzt den Rahmen, in dem sich das Projekt bewegt.
Entität: Ein Schlüsselobjekt des Problembereichs mit klarer Semantik. In AgentClinic gibt es fünf Hauptentitäten: Agent (Software-Assistent), Leiden (wiederkehrendes Problem eines Agenten), Therapie (Hilfsmethode für einen Agenten), Terminbuchung (Nutzeranfrage), Bewertung (Rückmeldung). Jede Entität hat eine Reihe von Attributen und Regeln für die Verwendung in Spezifikationen.
SDD-Zyklus (Specification-Driven Development): Ein Entwicklungsprozess, in dem Spezifikationen (requirements.md, plan.md, validation.md) die Implementierung leiten. Anstatt alles auf einmal zu bauen, entwickelt sich das Projekt phasenweise, wobei jede Phase mit klaren überprüfbaren Fakten beginnt und mit deren Bestätigung endet.
Überprüfbare Fakten: Konkrete, objektiv messbare Aussagen über das Systemverhalten, die automatisiert werden können. Zum Beispiel: „GET / gibt 200 zurück“ oder „eine ungültige Formular wird abgelehnt“. Fakten ersetzen vage Anforderungen wie „die Anwendung sollte schnell funktionieren“.
Entwicklungsphase: Ein zeitlich und inhaltlich begrenzter Abschnitt, der ein konkretes lieferbares Ergebnis liefert. In AgentClinic gibt es sechs Phasen: Hello Hono → Agenten und Leiden → Therapien → Terminbuchung → Rückmeldung → Admin-Panel. Jede Phase fügt neue Routen und Prüffakten hinzu, ohne die vorherigen zu zerstören.
Minimale Routen: Eine Reihe von URL-Pfaden, die ausreichen, um den Domain zu demonstrieren. Nicht alle Routen werden in der ersten Phase benötigt – dies ist das Prinzip der Iterativität des SDD. Routen verwenden technische englische Namen (/agents, /ailments), während Nutzerszenarien auf Deutsch mit Anwendung des Domain-Wortschatzes beschrieben werden.
Domain-Wortschatz: Eine Vereinbarung über einheitliche Terminologie in allen Spezifikationen. Verbietet Synonyme wie „Bot/Assistent/Modell“ für die Entität „Agent“. Technische Namen (Routen, Tabellen, Dateien) bleiben auf Englisch, Nutzerszenarien auf Deutsch mit einheitlichen Begriffen.
Grenzen des Lern-Domains: Eine explizite Aufzählung dessen, was NICHT in das Projekt ohne separate Spezifikation eingeht: echte medizinische Terminologie, echte personenbezogene Daten, Zahlungsszenarien, Autorisierung mit Rollen, externer E-Mail-Versand, komplexe Diagramme, Integrationen mit realen Diensten. Diese Einschränkung hält den Fokus auf dem SDD-Prozess.
Praxisübungen: Titel: Domainmodell für ein neues Projekt entwerfen
Problem: Stellen Sie sich vor, Sie müssen ein Lernprojekt „AgentLibrary“ erstellen – eine Bibliothek für Software-Agenten. Definieren Sie mindestens 4 Entitäten, deren Attribute und Beispiele, analog zur Entitätentabelle von AgentClinic. Beschreiben Sie dann, welche Routen benötigt werden und wie sie auf SDD-Zyklenphasen verteilt werden.
Lösung: Schritt 1: Entitäten definieren. Zum Beispiel: Buch (Titel, Autor, Beschreibung), Agent-Leser (Name, bevorzugte Genres), Bewertung (Bewertung, Text, Datum), Regal (Name, öffentlich/privat). Schritt 2: Attribute im Tabellenformat mit Beispielen festlegen. Schritt 3: Routen entwerfen: /, /books, /books/:id, /agents, /reviews, /shelves. Schritt 4: In Phasen aufteilen: (1) Hello Hono – GET / gibt 200 zurück; (2) Bücher – Liste und Karte; (3) Agenten und Bewertungen – verknüpfte Buchbewertungen; (4) Regale – Erstellung und Verwaltung von Sammlungen. Schritt 5: Für jede Phase 2-3 überprüfbare Fakten formulieren.
Schwierigkeit: mittel
Titel: Terminologie-Audit in Spezifikationen
Problem: Ihnen liegen drei Fragmente aus verschiedenen Dateien des AgentClinic-Projekts vor: (1) requirements.md: „Der Bot soll eine Liste seiner Probleme anzeigen“; (2) plan.md: „Tabelle symptoms erstellen zur Speicherung wiederkehrender Störungen des Assistenten“; (3) validation.md: „GET /agents/:id gibt eine verknüpfte Liste von ailments zurück“. Finden Sie alle Verstöße gegen den Domain-Wortschatz, erklären Sie, warum sie problematisch sind, und schreiben Sie die Fragmente korrekt um.
Lösung: Verstöße: „Bot“ statt „Agent“, „Probleme“ statt „Leiden“, „symptoms“ statt „ailments“, „Assistent“ statt „Agent“. Problem: Unterschiedliche Begriffe für dieselbe Entität erzeugen Verwirrung im Team, erschweren die Dokumentensuche und führen zu Inkonsistenzen zwischen Code (Tabelle ailments) und Spezifikationen (symptoms). Korrekte Version: (1) „Der Agent soll eine Liste seiner Leiden anzeigen“; (2) „Tabelle ailments erstellen zur Speicherung wiederkehrender Leiden des Agenten“; (3) unverändert – bereits korrekt.
Schwierigkeit: mittel
Titel: Domain-Erweiterung: Grenzen-Analyse
Problem: Das Team schlägt vor, in AgentClinic ein Klinik-Bewertungssystem (analog zu Google Reviews) mit kostenpflichtigem Abonnement für prioritäre Terminbuchung hinzuzufügen. Analysieren Sie diesen Vorschlag anhand der Kriterien aus dem Abschnitt „Was nicht in den Lern-Domain eingeht“. Beschreiben Sie, welche Komponenten die Grenzen verletzen, und schlagen Sie eine Alternative vor, die den Bildungswert bewahrt.
Lösung: Grenzverletzungen: Kostenpflichtiges Abonnement – Zahlungsszenarien (explizit verboten); Bewertungssystem mit regionaler Aggregation – komplexe Diagramme und potenziell echte personenbezogene Daten; prioritäre Buchung – implizite Autorisierung mit Rollen (normaler vs. Premium-Nutzer). Alternative: Einfache Zufriedenheitsskala (1-5 Sterne) in der bestehenden Entität „Bewertung“ ohne Nutzerbindung, ohne Aggregation und ohne Zahlungen. Als separate Phase hinzufügen: „Erweiterte Bewertungen“ mit den Fakten „Bewertung enthält eine Bewertung von 1-5“, „durchschnittliche Bewertung ist auf der Seite /feedback sichtbar“.
Schwierigkeit: fortgeschritten
Titel: Datenbankschema entwerfen
Problem: Entwerfen Sie auf Basis der beschriebenen AgentClinic-Entitäten und minimalen Routen ein vollständiges SQL-Schema unter Berücksichtigung aller Beziehungen. Erklären Sie, warum agent_ailments eine Verknüpfungstabelle ist und kein Feld in agents. Beschreiben Sie, wie sich das Schema ändert, wenn die Anforderung hinzugefügt wird: „Eine Therapie behandelt ein bestimmtes Leiden eines bestimmten Agenten“.
Lösung: Basisschema: agents(id, name, description); ailments(id, title, description); therapies(id, title, description); agent_ailments(agent_id, ailment_id) – Many-to-Many-Beziehung: Ein Agent kann mehrere Leiden haben, ein Leiden kann bei mehreren Agenten auftreten. Die Verknüpfungstabelle ist nötig, weil ein Array im agents-Feld die erste Normalform verletzt und Abfragen erschwert. appointments(id, name, message, ailment_id, created_at); feedback(id, name, message, created_at). Bei der neuen Anforderung wird agent_ailment_therapies(agent_ailment_id, therapy_id, effectiveness_rating) hinzugefügt, wobei agent_ailment_id ein zusammengesetzter Schlüssel oder eine separate ID der agent_ailments-Tabelle ist. Dies verwandelt die Beziehung in eine Dreifachbeziehung: Agent-Leiden-Therapie.
Schwierigkeit: mittel
Titel: Überprüfbare Fakten für die Phase „Terminbuchung“ formulieren
Problem: Formulieren Sie für die Phase „Terminbuchung“ in AgentClinic mindestens 5 überprüfbare Fakten, die abdecken: erfolgreiche Erstellung, Validierung Pflichtfelder, Behandlung nicht existierender Leiden, Anzeige gespeicherter Buchungen, Zeitstempel. Geben Sie an, welche Fakten mit Unit-Tests und welche mit Integrationstests überprüft werden können.
Lösung: Fakten: (1) POST /appointments mit gültigen Daten gibt 201 und Redirect zurück – Integrationstest; (2) POST /appointments ohne Name-Feld gibt 400 mit Fehlermeldung zurück – Unit (Formularvalidierung) + Integrationstest; (3) POST /appointments mit ailment_id=999 gibt 400 oder 404 zurück – Integrationstest (erfordert Datenbank); (4) GET /appointments nach erfolgreichem POST enthält die erstellte Buchung – Integrationstest; (5) created_at der Buchung liegt innerhalb der letzten Minute der Testzeit – Integrationstest. Unit-Tests sind für (2) auf Ebene der Eingabevalidierung ohne Datenbank möglich. Die übrigen erfordern den vollen Stack.
Schwierigkeit: mittel
Fallstudien: Titel: Migration eines monolithischen Prototyps auf SDD-Phasen in einem EdTech-Startup
Szenario: Ein Startup entwickelte in 3 Monaten „auf die Schnelle“ einen Prototyp einer Bildungsplattform: Kurse, Lektionen, Hausaufgaben, Chats, Zahlungen, Analytik – alles in einem Repository ohne Tests. Bei der Einstellung neuer Entwickler stellte sich heraus, dass niemand verstand, welche Funktionalität funktionierte und welche „Demo-Attrappe“ war. Investoren verlangten Nachweise der Funktionsfähigkeit.
Herausforderung: Ein Team von 8 Personen konnte nicht parallel arbeiten aufgrund ständiger Code-Konflikte. Es war unmöglich, den Investoren konkreten Fortschritt zu zeigen: „fast fertig“ klang bereits seit einem halben Jahr. Das Zahlungssystem zerstörte die Chats, und die Analytik zeigte zufällige Zahlen. Ein Übergang zu transparenter, überprüfbarer Entwicklung ohne Neuschreiben von Grund auf war erforderlich.
Lösung: Der Tech Lead adaptierte den AgentClinic-Ansatz: Domain-Entitäten definiert (Kurs, Lektion, Schüler, Aufgabe, Versuch, Bewertung) und Domain-Wortschatz fixiert. Der Monolith wurde in Phasen analog zum SDD-Zyklus aufgeteilt: (1) „Hello Framework“ – Basisantwort; (2) „Kurse und Lektionen“ – Inhaltsanzeige; (3) „Aufgaben“ – Erstellung und Prüfung; (4) „Versuche“ – Speicherung der Schülerantworten; (5) „Bewertungen“ – Rückmeldung. Zahlungen und Analytik wurden in separate Spezifikationen mit dem Status „außerhalb des Lern-Domain MVP“ ausgelagert. Für jede Phase wurden requirements.md, plan.md, validation.md mit überprüfbaren Fakten erstellt.
Ergebnis: Innerhalb von 6 Wochen stabilisierte das Team den Plattform-Kern (Phasen 1-4). Den Investoren wurde eine konkrete Checkliste vorgelegt: 47 überprüfbare Fakten, von denen 43 automatisch bestanden wurden. Neue Entwickler stiegen in 2 Tagen statt 2 Wochen dank des Domain-Wortschatzes in das Projekt ein. Das Zahlungssystem wurde später als separate Phase mit eigener Spezifikation hinzugefügt, ohne bestehende Funktionalität zu zerstören. Das Team reduzierte die Anzahl kritischer Bugs von 15 pro Woche auf 2.
Erkenntnisse: Domain Map und einheitlicher Wortschatz eliminieren „folkloristisches Wissen“ – Informationen, die nur in den Köpfen einzelner Entwickler existieren
Überprüfbare Fakten verwandeln Gespräche mit Investoren aus „fast fertig“ in konkrete Fertigstellungsmetriken
Explizite Definition der Domain-Grenzen schützt das Team vor vorzeitiger Komplexität und ermöglicht Fokussierung auf den Wert
Verwandte Konzepte: Domain Map
SDD-Zyklus
Überprüfbare Fakten
Grenzen des Lern-Domains
Domain-Wortschatz
Titel: Integrationsversagen aufgrund von Domain-Wortschatz-Verletzung in einem Unternehmensprojekt
Szenario: Eine Großbank entwickelte ein internes System für Kreditantragsmanagement. Das Projekt wurde zwischen drei Teams aufgeteilt: Frontend (Mobile App), Backend (API), Analytik (Berichte). Jedes Team arbeitete in eigener Dokumentation ohne einheitlichen Domain-Wortschatz.
Herausforderung: In der Mobile App bedeutete „Kunde“ eine natürliche Person, die einen Antrag gestellt hatte. In der API war „Kunde“ die interne Kennung einer juristischen Person – Partners. In der Analytik bezeichnete „Kunde“ jedes Objekt im CRM. Bei der Integration vermischten sich die Daten: Anträge natürlicher Personen wurden juristischen Personen zugeschrieben, Berichte zeigten unmögliche Zahlen. Die Korrektur erforderte 3 Wochen Audit von 200+ Endpunkten und 15 Konfigurationsdateien.
Lösung: Nach dem Vorfall wurde ein AgentClinic-Domain-Wortschatz-ähnlicher Ansatz eingeführt: feste Begriffe mit Definitionen in einem gemeinsamen Repository. „Antragsteller“ – natürliche Person, die einen Kreditantrag gestellt hat. „Partner“ – juristische Person mit Bankvertrag. „Antrag“ – einheitliches Dokument im System. Technische Feldnamen in der API blieben auf Englisch (applicant, partner, application), Nutzerszenarien wurden auf Deutsch mit einheitlicher Terminologie übersetzt. Ein automatischer Dokumentations-Linter zur Wortschatz-Überprüfung wurde eingeführt.
Ergebnis: Die Onboarding-Zeit neuer Analysten verkürzte sich von 3 Wochen auf 4 Tage. Die Anzahl integrationsbedingter Semantikfehler sank um 80%. Bei der Systemerweiterung auf Hypothekenanträge wurde der Begriff „Immobilienobjekt“ ohne Konflikte mit bestehenden Entitäten hinzugefügt. Das Projekt wurde zum Vorbild für andere Bankabteilungen.
Erkenntnisse: Domain-Wortschatz-Verletzung ist kein „Stilproblem“, sondern eine Quelle kostspieliger Integrationsbugs
Die Trennung technischer Namen (Englisch, für Code) und Nutzerbegriffe (Deutsch, für Spezifikationen) löst das Problem mehrsprachiger Teams
Automatisierung der Wortschatz-Überprüfung (Linter, CI-Pipelines) ist wichtiger als manuelle Anweisungen
Verwandte Konzepte: Domain-Wortschatz
Entität
Grenzen des Lern-Domains
Studientipps: Erstellen Sie eine physische oder digitale „Wandkarte“: Drucken Sie die AgentClinic-Entitäten auf Karten und verbinden Sie sie mit Beziehungslinien. Die visuelle räumliche Anordnung hilft, die Struktur besser zu merken als tabellarisches Lesen
Üben Sie die „Rückübersetzung“: Nehmen Sie technische Begriffe aus dem Code (Tabelle agent_ailments, Route /appointments) und formulieren Sie deren Nutzersemantik auf Deutsch mit Anwendung des Domain-Wortschatzes. Dies trainiert den Wechsel zwischen technischem und Nutzerkontext
Entwickeln Sie für jede SDD-Phase selbstständig einen „leicht vergessenen Fakt“. Zum Beispiel für die Phase „Terminbuchung“ – XSS-Prüfung im message-Feld. Vergleichen Sie mit den im Material vorgeschlagenen – dies entwickelt kritisches Denken über die Vollständigkeit von Spezifikationen
Nutzen Sie die „Lehrmethode“: Erklären Sie die AgentClinic-Domain Map einem Kollegen oder sogar einem imaginären Zuhörer. Der Versuch, in einfacher Sprache zu erklären, warum agent_ailments eine Verknüpfungstabelle und kein Feld ist, deckt schnell Verständnislücken auf
Führen Sie „Grenzen-Audits“ für Ihre aktuellen Projekte durch: Welche Funktionen „gehören nicht zum Domain“ ohne separate Spezifikation? Diese Übung überträgt AgentClinic-Konzepte auf die reale Praxis
Erstellen Sie eine validation.md-Vorlage für eine der Phasen im Given-When-Then-Format oder als einfache Faktenliste. Versuchen Sie, einen Test zu schreiben, der einen der Fakten implementiert – auch nur gedanklich stärkt dies die Verbindung zwischen Spezifikation und Code
Zusätzliche Ressourcen: Originaldokument „Anhang B. Domain Map AgentClinic“: Ausgangsmaterial des Kurses, auf dem dieser Handbuch basiert
Buch „Domain-Driven Design“ von Eric Evans: Grundlegendes Werk über domänenorientiertes Design – Domain Maps, begrenzte Kontexte, einheitliche Sprache
Buch „Implementing Domain-Driven Design“ von Vaughn Vernon: Praktischer Leitfaden zur DDD-Implementierung mit Codebeispielen und Mustern
Artikel „Specification by Example“ von Gojko Adzic: Methodologie zur Formulierung von Anforderungen durch überprüfbare Beispiele, verwandt mit dem SDD-Zyklus
Werkzeug „Event Storming“: Technik zur gruppenbasierten Domain-Modellierung durch Ereignisse – nützlich zur Erweiterung von Domain Maps im Team
SQLite-Dokumentation (sqlite.org/lang.html): Offizielle SQL-Dokumentation zum selbstständigen Entwurf von Schemas, analog zu den in AgentClinic vorgeschlagenen
Framework Hono (hono.dev): Dokumentation des leichten Web-Frameworks, das in der Phase „Hello Hono“ verwendet wird – für die praktische Implementierung von Routen
Artikel „The C4 Model for Software Architecture“ von Simon Brown: Methode zur Visualisierung von Softwarearchitektur, einschließlich Kontext- und Container-Diagrammen – nützlich zur Erweiterung von Domain Maps
Zusammenfassung: Die Domain Map von AgentClinic ist nicht nur eine scherzhafte Metapher, sondern ein sorgfältig entworfenes Lernwerkzeug zur Beherrschung des SDD-Zyklus. Ihre Kernprinzipien: ein satirischer, aber semantisch präziser Domain; fünf klar definierte Entitäten mit Attributen und Beispielen; iterativer Aufbau der Funktionalität durch sechs Phasen mit überprüfbaren Fakten; einheitlicher Domain-Wortschatz, der technische englische Namen und Nutzerbegriffe auf Deutsch trennt; explizite Grenzen, die vor vorzeitiger Komplexität schützen. Wer diese Map beherrscht, lernt, Problembereiche zu entwerfen, die ausreichend reichhaltig sind, um reale Muster zu demonstrieren, aber ausreichend einfach für kontrolliertes Lernen. Die Hauptfähigkeit ist die Übersetzung vager Wünsche („machen Sie eine Klinik für Agenten“) in konkrete Entitäten, Routen, Tabellen und Fakten, die automatisch überprüft werden können.