ubiquitous-language

Vue d’ensemble de la skill ubiquitous-language

La skill ubiquitous-language transforme une discussion de domaine brouillonne en glossaire structuré, dans l’esprit DDD, avec des termes canoniques, des définitions et des alias à éviter. Son rôle n’est pas simplement de « rédiger un glossaire » au sens large. Elle aide les équipes à normaliser leur langage quand le produit, l’ingénierie et la rédaction technique emploient des termes qui se recoupent ou divergent pour désigner les mêmes concepts.

À quoi la skill ubiquitous-language sert le mieux

Utilisez la skill ubiquitous-language lorsque la conversation contient déjà du vocabulaire métier et que vous devez le formaliser dans un format réutilisable. Elle est particulièrement adaptée à :

• des travaux de domain-driven design
• l’assainissement de la terminologie API et produit
• l’alignement des conventions de nommage sur une plateforme interne
• la documentation d’onboarding
• la modélisation de contenu
• l’usage de ubiquitous-language pour la rédaction technique lorsque la documentation doit employer un terme canonique unique de façon cohérente

Le vrai besoin auquel elle répond

La plupart des utilisateurs cherchent à résoudre l’un de ces problèmes :

• « On utilise plusieurs noms pour parler de la même chose. »
• « Un même terme veut dire des choses différentes selon le contexte. »
• « Notre documentation, l’interface produit et les échanges d’ingénierie dérivent chacun de leur côté. »
• « On a besoin d’une première version de glossaire métier à partir de discussions existantes, pas d’un exercice page blanche. »

Cette skill analyse la conversation en cours, repère la terminologie ambiguë ou dupliquée, propose des termes canoniques assumés, puis écrit le résultat dans UBIQUITOUS_LANGUAGE.md.

En quoi c’est différent d’un prompt classique

Un prompt standard peut demander un glossaire. Le workflow ubiquitous-language est plus précis, donc plus utile pour décider de l’adopter :

• il recherche les ambiguïtés, les synonymes et les termes surchargés
• il pousse vers une nomenclature canonique, pas seulement vers une extraction
• il produit un artefact markdown réutilisable
• il suit une structure prévisible, basée sur des tableaux, facile à relire et à modifier

C’est donc un meilleur choix qu’une demande générique du type « résume nos termes métier » quand l’enjeu est de durcir la terminologie.

À quoi ressemble la sortie

La skill génère UBIQUITOUS_LANGUAGE.md avec des sections thématiques, par exemple le cycle de vie des commandes ou les rôles métier, puis des tableaux contenant :

• le terme canonique
• la définition
• les alias à éviter

Ce format est particulièrement utile en relecture, car les désaccords apparaissent très vite.

Quand cette skill est un mauvais choix

Évitez cette skill si :

• la conversation ne contient pas encore assez de matière métier
• vous avez besoin d’une ontologie complète, d’un modèle de données ou d’une sortie d’event storming
• votre objectif relève du naming de marque plutôt que de la clarté du domaine
• le domaine est encore trop spéculatif pour arrêter des termes canoniques

Dans ces cas-là, commencez par rassembler des exemples, puis lancez la skill plus tard.

Comment utiliser la skill ubiquitous-language

Contexte d’installation de ubiquitous-language

Si vous utilisez l’écosystème de skills de mattpocock/skills, installez la skill ubiquitous-language via votre chargeur de skills habituel. Un schéma courant est :

npx skills add mattpocock/skills --skill ubiquitous-language

Si votre environnement charge les skills autrement, utilisez cette méthode à la place. L’essentiel est que l’agent puisse accéder à la définition de la skill ubiquitous-language et écrire UBIQUITOUS_LANGUAGE.md dans le répertoire de travail.

Lisez ce fichier en premier avant de l’utiliser

Commencez par :

• SKILL.md

Le chemin dans ce dépôt est particulièrement simple : la logique d’usage principale se trouve dans ce seul fichier. Vous n’avez pas besoin de fouiller des scripts auxiliaires ou des références enfouies pour savoir si la skill vaut le coup d’être testée.

Quelles entrées la skill attend réellement

La skill fonctionne nettement mieux lorsque la conversation en cours contient déjà :

• des noms métier : order, invoice, account, shipment
• des verbes de processus : approve, fulfill, cancel
• des noms de rôles : customer, operator, reviewer
• des exemples d’usage confus : « we sometimes say subscription, sometimes contract »
• du contexte sur les frontières : périmètre produit, audience, système ou processus métier

Sans cette matière, la sortie sera maigre ou trop spéculative.

Comment bien déclencher ubiquitous-language

Une demande faible ressemble à :

• « Make a glossary. »

Une demande plus solide ressemble à :

• « 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. »

Cette formulation indique à l’agent d’utiliser la skill comme prévu, au lieu d’improviser un glossaire générique.

Transformer un objectif flou en prompt de qualité

Un bon prompt d’usage de ubiquitous-language contient généralement quatre éléments :

1. le domaine
2. la matière source
3. les conflits ou points de douleur
4. le format de sortie attendu

Exemple :

« 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. »

Workflow conseillé en pratique

Un workflow fiable ressemble à ceci :

1. discuter naturellement du domaine d’abord
2. laisser les termes entrer en collision dans la conversation
3. lancer ubiquitous-language
4. relire les termes canoniques proposés
5. corriger les erreurs métier
6. réutiliser le glossaire validé dans la documentation, les API, les textes d’interface et les templates d’issues

La skill est la plus utile après un vrai échange, pas avant.

Conseils pratiques pour améliorer la qualité du résultat

Pour obtenir de meilleurs résultats :

• donnez des exemples concrets, pas seulement des catégories abstraites
• signalez explicitement les conflits terminologiques
• précisez quelle audience compte le plus : ingénieurs, utilisateurs, support, rédacteurs
• indiquez si un terme est réservé à l’interne ou destiné au public
• demandez au modèle de préserver les distinctions importantes au lieu de tout rabattre sur une seule étiquette

Ces détails améliorent concrètement le glossaire, car ils réduisent les faux regroupements de synonymes.

Ce que les rédacteurs techniques doivent faire différemment avec ubiquitous-language

Pour ubiquitous-language en rédaction technique, ajoutez des contraintes comme :

• le vocabulaire préféré des lecteurs
• le jargon interne interdit
• les contraintes sur les libellés UI
• les contraintes sur les termes API
• le fait que la documentation doive refléter le langage du produit ou au contraire le normaliser

Exemple :

« 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. »

Vous obtiendrez ainsi une sortie plus exploitable d’un point de vue éditorial.

Fichier de sortie attendu et mode de relecture

Le fichier généré est UBIQUITOUS_LANGUAGE.md. Relisez-le avec ces questions en tête :

• La skill a-t-elle fusionné par erreur des concepts distincts ?
• A-t-elle conservé des termes ambigus sans le signaler ?
• Les “aliases to avoid” sont-ils réalistes ?
• Les définitions reflètent-elles le comportement réel du système, et pas seulement une préférence de formulation ?

Considérez la première version comme un brouillon de décision, pas comme une vérité définitive.

FAQ sur la skill ubiquitous-language

La skill ubiquitous-language est-elle accessible aux débutants ?

Oui, à condition d’avoir déjà une conversation sur le domaine. Vous n’avez pas besoin d’une expertise DDD approfondie pour en tirer de la valeur. La sortie est en markdown lisible, et les tableaux rendent les désaccords visibles. Ce que les débutants sous-estiment souvent, c’est à quel point la qualité dépend de la précision de la discussion source.

En quoi est-ce mieux que de demander directement un glossaire ?

La skill ubiquitous-language est plus ciblée, donc plus fiable pour aligner la terminologie. Elle est conçue pour détecter les ambiguïtés, les synonymes et les termes surchargés, puis forcer des choix canoniques. Un prompt générique de glossaire énumère souvent des termes sans arbitrer les conflits.

Est-ce utile uniquement pour les équipes DDD ?

Non. Le vocabulaire DDD donne le cadre, mais la skill est utile partout où la dérive terminologique crée des frictions : documentation technique, API, opérations de support, conception produit ou outillage interne. Elle est particulièrement pertinente lorsque plusieurs équipes décrivent le même workflow de façon différente.

Quand ne faut-il pas installer ubiquitous-language ?

Ne donnez pas la priorité à l’installation de ubiquitous-language si votre besoin principal relève plutôt de l’un de ces cas :

• brainstorming de noms de produit
• génération de documentation utilisateur à partir de zéro
• construction d’un schéma de base de données
• cartographie détaillée de toutes les règles métier

Cette skill sert à normaliser le langage, pas à modéliser intégralement le domaine.

Peut-elle fonctionner à partir d’une petite conversation ?

Oui, mais le résultat sera plus faible. La skill extrait à partir de la conversation en cours, donc une entrée trop pauvre mène à des définitions génériques et à moins de détection utile des conflits. Si vous n’avez qu’un court échange, ajoutez d’abord des exemples, des cas limites et des termes concurrents.

Est-ce adapté aux workflows de documentation ?

Oui. Le fichier de sortie est facile à versionner, à relire en pull request et à réutiliser dans des guides de style, des documents d’architecture, des supports d’onboarding et des références API. Cela rend l’usage de ubiquitous-language très pratique pour les équipes qui veulent faire vivre leurs décisions terminologiques à côté du code et de la documentation.

Comment améliorer la skill ubiquitous-language

Donner à la skill des preuves métier plus riches

Le levier principal sur la qualité de sortie, c’est la qualité de la matière source. Avant d’exécuter ubiquitous-language, veillez à inclure :

• de vrais termes visibles côté utilisateur
• les raccourcis internes
• les étapes du processus
• les cas limites
• des exemples où deux personnes ont utilisé des mots différents pour parler de la même chose

La skill ne peut normaliser que ce qu’elle voit.

Distinguer les vrais synonymes des différences importantes

Un mode d’échec fréquent consiste à écraser deux concepts proches mais distincts. Pour l’éviter, énoncez clairement les contrastes, par exemple :

• “Order is the customer request; invoice is the billing artifact.”
• “Account is the legal entity; workspace is the product container.”

Cela aide la skill à préserver les frontières du domaine au lieu de trop simplifier.

Indiquer quelle terminologie doit l’emporter

Le choix des termes canoniques est forcément orienté. Si vous n’exprimez pas votre préférence, la skill peut retenir des termes techniquement corrects mais inadaptés à votre workflow. Pour améliorer les résultats, précisez :

• vocabulaire externe vs interne
• terminologie ingénierie vs métier
• libellés UI vs libellés back-office
• termes qui doivent être conservés pour compatibilité

Cette orientation rend le glossaire plus exploitable une fois généré.

Utiliser des prompts plus fermes pour les domaines ambigus

Si votre domaine est chargé en ambiguïtés, demandez explicitement une analyse de celles-ci. Exemple :

“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.”

Vous réduisez ainsi le risque d’une fausse impression de clarté.

Relire avec un soin particulier les alias à éviter

La colonne “aliases to avoid” est souvent celle qui apporte le plus de valeur aux équipes, mais aussi celle où les erreurs peuvent créer le plus de confusion. Vérifiez si les alias interdits sont :

• réellement trompeurs
• encore nécessaires dans une documentation legacy
• acceptables pour une audience mais pas pour une autre

Une meilleure deuxième passe conserve souvent le terme canonique, tout en assouplissant la consigne sur les alias.

Itérer après la première version

Le meilleur guide ubiquitous-language se construit par itérations :

1. lancer la skill
2. marquer les termes contestés
3. ajouter des exemples clarifiants dans la conversation
4. relancer la skill
5. valider le glossaire
6. l’appliquer dans la documentation et le langage produit

N’attendez pas de la première passe qu’elle tranche tous les choix de nommage.

Prolonger le résultat dans votre système de documentation

Une fois UBIQUITOUS_LANGUAGE.md stabilisé, augmentez la valeur de la skill ubiquitous-language en la reliant à un vrai travail éditorial :

• ajoutez un lien depuis votre guide de style documentaire
• utilisez-la pendant la revue de PR
• alignez les titres et les références UI sur les termes canoniques
• auditez l’ancienne documentation pour repérer les alias interdits

C’est ainsi que le glossaire devient opérationnel, et pas simplement décoratif.