ubiquitous-language
von mattpocockubiquitous-language verwandelt Fachdiskussionen in ein Glossar im DDD-Stil, markiert Mehrdeutigkeiten und Synonyme, schlägt kanonische Begriffe vor und erstellt `UBIQUITOUS_LANGUAGE.md`. Nützlich, um Terminologie in Doku, APIs, Produktsprachgebrauch und ubiquitous-language für Technical Writing abzustimmen.
Diese Skill erreicht 78/100 und ist damit ein überzeugender Verzeichniseintrag für Nutzer, die einen schlanken, klar auslösbaren DDD-Glossar-Workflow suchen. Das Repository zeigt genug operative Klarheit, damit ein Agent Terminologie aus Gesprächen extrahieren und in einer strukturierten Glossardatei speichern kann. Nutzer sollten jedoch eine reine Dokumentations-Skill ohne weitergehende Implementierungshilfen oder Hinweise zu Sonderfällen erwarten.
- Das Frontmatter liefert starke Auslöser und Signale, darunter DDD-/Domain-Model-Begriffe und explizite Nutzerintentionen.
- `SKILL.md` beschreibt einen konkreten 5-Schritte-Prozess sowie ein klar definiertes Ergebnisartefakt: `UBIQUITOUS_LANGUAGE.md`.
- Gegenüber einem generischen Prompt bietet die Skill echten Mehrwert, weil sie Mehrdeutigkeiten, Synonymkonflikte und die Wahl kanonischer Begriffe gezielt sichtbar macht.
- Es gibt keinen Installationsbefehl, keine Support-Dateien und keine begleitenden Regeln oder Ressourcen; die Einführung stützt sich daher fast vollständig auf `SKILL.md`.
- Der Workflow konzentriert sich im Wesentlichen auf die Erzeugung eines Glossars aus Gesprächen; es gibt keine Hinweise auf Validierungsschritte, Edge-Case-Behandlung oder Beispiele über die Ausgabevorlage hinaus.
Überblick über den Skill ubiquitous-language
Der Skill ubiquitous-language verwandelt eine unstrukturierte Fachdiskussion in ein strukturiertes Glossar im DDD-Stil – mit kanonischen Begriffen, Definitionen und zu vermeidenden Aliasen. Seine eigentliche Aufgabe ist nicht einfach nur „ein Glossar schreiben“. Er hilft Teams dabei, ihre Sprache zu vereinheitlichen, wenn Produkt, Engineering und technische Redaktion für dieselben Konzepte überlappende oder inkonsistente Begriffe verwenden.
Wofür sich ubiquitous-language am besten eignet
Nutzen Sie den ubiquitous-language skill, wenn in der laufenden Diskussion bereits Fachbegriffe vorkommen und Sie diese in etwas Wiederverwendbares überführen möchten. Besonders gut passt er für:
- Domain-Driven-Design-Arbeit
- Bereinigung von API- und Produktterminologie
- Abstimmung von Benennungen auf internen Plattformen
- Onboarding-Dokumentation
- Content-Modellierung
- ubiquitous-language für Technical Writing, wenn in der Dokumentation konsequent ein kanonischer Begriff verwendet werden muss
Die eigentliche Aufgabe, die der Skill löst
Die meisten Nutzer versuchen, eines dieser Probleme zu lösen:
- „Wir verwenden ständig mehrere Namen für dasselbe.“
- „Ein Begriff bedeutet je nach Kontext etwas anderes.“
- „Unsere Doku, die Produkt-UI und technische Diskussionen driften sprachlich auseinander.“
- „Wir brauchen ein erstes Domain-Glossar auf Basis bestehender Diskussionen, nicht bei null auf einem leeren Blatt.“
Der Skill analysiert die aktuelle Unterhaltung, erkennt mehrdeutige oder doppelte Terminologie, schlägt bewusst gewählte kanonische Begriffe vor und schreibt das Ergebnis in UBIQUITOUS_LANGUAGE.md.
Was ubiquitous-language von einem normalen Prompt unterscheidet
Ein normaler Prompt kann nach einem Glossar fragen. Der Workflow von ubiquitous-language ist deutlich konkreter und damit für Installations- und Adoptionsentscheidungen nützlicher:
- er sucht gezielt nach Mehrdeutigkeiten, Synonymen und überladenen Begriffen
- er drängt auf kanonische Benennungen statt nur auf Extraktion
- er erzeugt ein wiederverwendbares Markdown-Artefakt
- er folgt einer vorhersehbaren tabellenbasierten Struktur, die sich leicht prüfen und bearbeiten lässt
Dadurch eignet er sich besser zur terminologischen Schärfung als eine generische Anfrage wie „Fasse unsere Domain-Begriffe zusammen“.
Wie die Ausgabe aussieht
Der Skill schreibt UBIQUITOUS_LANGUAGE.md mit thematischen Abschnitten wie Auftragslebenszyklus oder Personen und darin Tabellen mit:
- kanonischem Begriff
- Definition
- zu vermeidenden Aliasen
Dieses Format ist besonders für Reviews nützlich, weil Meinungsverschiedenheiten schnell sichtbar werden.
Wann dieser Skill nicht gut passt
Überspringen Sie diesen Skill, wenn:
- in der Unterhaltung noch nicht genug Domain-Material vorhanden ist
- Sie eine vollständige Ontologie, ein Datenmodell oder Event-Storming-Ergebnisse brauchen
- Ihr Ziel eher Brand Naming als fachliche Klarheit ist
- die Domain noch zu spekulativ ist, um kanonische Begriffe festzulegen
Sammeln Sie in diesen Fällen zuerst Beispiele und führen Sie den Skill später aus.
So verwenden Sie den Skill ubiquitous-language
Installationskontext für ubiquitous-language
Wenn Sie das Skill-Ökosystem aus mattpocock/skills verwenden, installieren Sie den ubiquitous-language skill über Ihren üblichen Skill-Loader. Ein typisches Muster ist:
npx skills add mattpocock/skills --skill ubiquitous-language
Wenn Ihre Umgebung Skills auf andere Weise lädt, verwenden Sie stattdessen diesen Weg. Entscheidend ist, dass der Agent auf die Definition des Skills ubiquitous-language zugreifen und UBIQUITOUS_LANGUAGE.md im Arbeitsverzeichnis schreiben kann.
Diese Datei sollten Sie zuerst lesen
Starten Sie mit:
SKILL.md
Der Repository-Pfad ist hier ungewöhnlich einfach: Die zentrale Nutzungslogik steckt in genau dieser einen Datei. Sie müssen sich nicht erst durch Hilfsskripte oder tief verschachtelte Verweise arbeiten, bevor Sie entscheiden können, ob sich ein Test lohnt.
Welche Eingaben der Skill tatsächlich braucht
Der Skill funktioniert am besten, wenn die aktuelle Unterhaltung bereits Folgendes enthält:
- Domain-Nomen:
order,invoice,account,shipment - Prozessverben:
approve,fulfill,cancel - Rollennamen:
customer,operator,reviewer - Beispiele für verwirrende Verwendung: „we sometimes say subscription, sometimes contract“
- Kontext zu Abgrenzungen: Produktbereich, Zielgruppe, System oder Geschäftsprozess
Ohne dieses Material wird die Ausgabe dünn oder zu spekulativ.
So lösen Sie ubiquitous-language sinnvoll aus
Eine schwache Anfrage wäre:
- „Make a glossary.”
Eine deutlich bessere Anfrage wäre:
- “Use the ubiquitous-language skill on this discussion. Extract domain terms, identify synonyms and overloaded words, propose canonical terms, and write
UBIQUITOUS_LANGUAGE.md. Group terms by business area.”
Diese Formulierung signalisiert dem Agenten, den Skill so zu verwenden, wie er gedacht ist, statt einfach ein Glossar zu improvisieren.
Aus einem groben Ziel einen hochwertigen Prompt machen
Ein guter Prompt für die ubiquitous-language usage enthält in der Regel vier Teile:
- die Domain
- das Ausgangsmaterial
- die Konflikte oder Schmerzpunkte
- die Erwartung an die Ausgabe
Beispiel:
“Use the ubiquitous-language skill for our order-management domain. Based on the conversation so far, extract core terms, flag where we use the same word for different concepts, and propose canonical terms with aliases to avoid. Separate customer-facing terms from internal operational terms where needed. Save the result to UBIQUITOUS_LANGUAGE.md.”
Empfohlener Workflow in der Praxis
Ein verlässlicher Workflow sieht so aus:
- die Domain zunächst natürlich besprechen
- Begriffe in der Unterhaltung bewusst aufeinanderprallen lassen
- ubiquitous-language ausführen
- die vorgeschlagenen kanonischen Begriffe prüfen
- fachliche Fehler korrigieren
- das freigegebene Glossar in Doku, APIs, UI-Texten und Issue-Templates verwenden
Der Skill ist nach echter Diskussion am wertvollsten, nicht davor.
Praktische Tipps für bessere Ergebnisse
Für bessere Resultate:
- konkrete Beispiele statt nur abstrakter Kategorien einbringen
- Begriffskonflikte ausdrücklich nennen
- angeben, welche Zielgruppe am wichtigsten ist: Engineers, Nutzer, Support, Autoren
- markieren, ob ein Begriff nur intern oder öffentlich verwendet wird
- das Modell ausdrücklich bitten, sinnvolle Unterschiede zu erhalten, statt alles unter einem Label zusammenzufassen
Diese Details verbessern das Glossar spürbar, weil sie falsches Zusammenführen von Synonymen reduzieren.
Was Technical Writers anders machen sollten
Für ubiquitous-language für Technical Writing sollten Sie zusätzliche Vorgaben ergänzen, etwa:
- bevorzugten Wortschatz der Leser
- verbotenen internen Jargon
- Einschränkungen bei UI-Labels
- Vorgaben zu API-Begriffen
- ob die Doku die Produktsprache spiegeln oder vereinheitlichen soll
Beispiel:
“Use the ubiquitous-language skill, but optimize for external documentation. Prefer terms users will recognize, keep internal code names in aliases to avoid, and note any term that should not appear in public docs.”
So wird die Ausgabe redaktionell deutlich besser nutzbar.
Erwartete Ausgabedatei und typisches Review-Muster
Die erzeugte Datei ist UBIQUITOUS_LANGUAGE.md. Prüfen Sie sie mit diesen Fragen:
- Hat der Skill versehentlich unterschiedliche Konzepte zusammengeführt?
- Hat er mehrdeutige Begriffe ohne Warnung stehen gelassen?
- Sind die „aliases to avoid“ realistisch?
- Spiegeln die Definitionen das tatsächliche Systemverhalten wider und nicht nur eine sprachliche Vorliebe?
Behandeln Sie die erste Ausgabe als Entscheidungsentwurf, nicht als endgültige Wahrheit.
FAQ zum Skill ubiquitous-language
Ist ubiquitous-language anfängerfreundlich?
Ja – sofern bereits eine Unterhaltung über die Domain existiert. Sie brauchen kein tiefes DDD-Know-how, um davon zu profitieren. Die Ausgabe ist gut lesbares Markdown, und die Tabellen machen Unstimmigkeiten sichtbar. Was Einsteiger oft unterschätzen: Die Qualität hängt stark von der Konkretheit der Ausgangsdiskussion ab.
Warum ist das besser, als direkt nach einem Glossar zu fragen?
Der ubiquitous-language skill ist enger zugeschnitten und deshalb für die Terminologieabstimmung verlässlicher. Er ist darauf ausgelegt, Mehrdeutigkeiten, Synonyme und überladene Begriffe zu erkennen und dann kanonische Entscheidungen zu erzwingen. Ein generischer Glossar-Prompt listet Begriffe oft nur auf, ohne Konflikte aufzulösen.
Hilft das nur DDD-Teams?
Nein. DDD liefert den Rahmen, aber der Skill ist überall nützlich, wo terminologische Drift Reibung erzeugt: in technischer Dokumentation, APIs, Support-Prozessen, Produktdesign oder internen Tools. Besonders hilfreich ist er, wenn mehrere Teams denselben Workflow unterschiedlich beschreiben.
Wann sollte ich ubiquitous-language nicht installieren?
Priorisieren Sie die ubiquitous-language install nicht, wenn Ihr Hauptbedarf eher in einem dieser Bereiche liegt:
- Produktnamen brainstormen
- Endnutzerdokumentation von Grund auf erstellen
- ein Datenbankschema entwerfen
- jede Geschäftsregel im Detail abbilden
Dieser Skill dient der sprachlichen Normalisierung, nicht dem vollständigen Domain-Modelling.
Funktioniert das auch mit einer kurzen Unterhaltung?
Ja, aber die Ergebnisse sind schwächer. Der Skill extrahiert aus der aktuellen Unterhaltung; spärlicher Input führt daher zu generischen Definitionen und weniger aussagekräftigen Konflikterkennungen. Wenn Sie nur einen kurzen Chat haben, ergänzen Sie zuerst Beispiele, Randfälle und konkurrierende Begriffe.
Passt das in Dokumentations-Workflows?
Ja. Die Ausgabedatei lässt sich leicht versionieren, in Pull Requests prüfen und in Styleguides, Architektur-Dokumenten, Onboarding-Materialien und API-Referenzen wiederverwenden. Genau das macht die ubiquitous-language usage für Teams praktikabel, die Terminologieentscheidungen neben Code und Doku pflegen möchten.
So verbessern Sie den Skill ubiquitous-language
Geben Sie dem Skill mehr fachliche Evidenz
Der größte Hebel für bessere Ausgabequalität ist besseres Ausgangsmaterial. Bevor Sie ubiquitous-language ausführen, sollten Sie Folgendes einbringen:
- echte nutzerseitige Begriffe
- interne Kurzformen
- Prozessschritte
- Randfälle
- Beispiele, in denen zwei Personen unterschiedliche Wörter für dieselbe Sache verwendet haben
Der Skill kann nur das vereinheitlichen, was er auch sehen kann.
Trennen Sie echte Synonyme von wichtigen Unterschieden
Ein häufiger Fehler ist, zwei verwandte, aber unterschiedliche Konzepte zusammenzuziehen. Verhindern Sie das, indem Sie Unterschiede direkt benennen, zum Beispiel:
- “Order is the customer request; invoice is the billing artifact.”
- “Account is the legal entity; workspace is the product container.”
Das hilft dem Skill, Domain-Grenzen zu erhalten, statt sie zu stark zu vereinfachen.
Sagen Sie, welche Sprache gewinnen soll
Kanonische Benennung ist nie neutral. Wenn Sie keine Präferenz angeben, wählt der Skill womöglich Begriffe, die technisch korrekt sind, aber nicht zu Ihrem Workflow passen. Bessere Ergebnisse erhalten Sie, wenn Sie Folgendes klar benennen:
- externe vs. interne Terminologie
- Engineering- vs. Business-Begriffe
- UI-Labels vs. Backoffice-Bezeichnungen
- Begriffe, die aus Kompatibilitätsgründen erhalten bleiben müssen
Diese Leitplanken machen das Glossar nach der Generierung deutlich brauchbarer.
Verwenden Sie stärkere Prompts für mehrdeutige Domains
Wenn Ihre Domain besonders überladen ist, fordern Sie die Mehrdeutigkeitsanalyse ausdrücklich ein. Beispiel:
“Use the ubiquitous-language skill and be strict about ambiguity. If the same term refers to multiple concepts, split them into separate entries and call out the conflict clearly instead of picking one silently.”
So sinkt das Risiko einer trügerischen Klarheit.
Prüfen Sie „aliases to avoid“ besonders sorgfältig
Die Spalte „aliases to avoid“ ist für viele Teams der wertvollste Teil – zugleich aber auch der Bereich, in dem Fehler leicht Verwirrung stiften. Prüfen Sie, ob die verbotenen Aliasnamen:
- tatsächlich irreführend sind
- in Legacy-Dokumentation weiterhin gebraucht werden
- für eine Zielgruppe akzeptabel, für eine andere aber ungeeignet sind
Ein besserer zweiter Durchgang behält oft den kanonischen Begriff bei, formuliert die Alias-Empfehlung aber weicher.
Iterieren Sie nach dem ersten Entwurf
Der beste ubiquitous-language guide entsteht iterativ:
- den Skill ausführen
- umstrittene Begriffe markieren
- klärende Beispiele in die Unterhaltung ergänzen
- den Skill erneut ausführen
- das Glossar freigeben
- es in Doku und Produktsprache anwenden
Erwarten Sie nicht, dass der erste Durchlauf jede Benennungsfrage abschließend löst.
In Ihr Dokumentationssystem überführen
Sobald UBIQUITOUS_LANGUAGE.md stabil ist, steigern Sie den Nutzen des ubiquitous-language skill, indem Sie das Ergebnis in echte redaktionelle Arbeit überführen:
- aus dem Doku-Styleguide darauf verlinken
- es bei PR-Reviews verwenden
- Überschriften und UI-Referenzen auf kanonische Begriffe abstimmen
- alte Dokumentation auf verbotene Aliasnamen prüfen
So wird aus dem Glossar ein operatives Arbeitsmittel statt bloßer Dekoration.