| name | sdd-uc-spec-write |
| description | Rédige et met à jour les spécifications SDD par cas d'utilisation (UC) : spec racine (projet principal) ou spec d'extension (fonction ajoutée à une racine existante). Exploitable par des agents IA. En CLI écrit dans docs/, sur claude.ai livre des artefacts Markdown. S'active dès qu'on demande une spec SDD, à formaliser des UC, ou à étendre une spec racine.
|
| metadata | {"version":"2.5.0","author":"Franz TRIERWEILER"} |
| license | MIT |
Spec Driven Development (SDD) — Rédaction par cas d'utilisation
Version : 2.5.0
Date : 2026-04-28
Barre de progression — OBLIGATION STRICTE
Chaque réponse produite sous ce skill DOIT commencer par la barre de
progression ci-dessous. AUCUNE EXCEPTION. Cela inclut le message d'accueil.
🖊️ skill:sdd-uc-spec-write v2.5.0 · [Étape] [barre] sous-étape N/T — [Nom]
Caractère plein : █ — Caractère vide : ░. Voir la section
« Identification du skill dans les réponses » plus bas pour le détail
des sous-étapes et les exemples complets.
Prérequis — vérification au démarrage
Avant toute autre action, vérifie que les fichiers suivants existent dans le
répertoire references/ du skill :
| Fichier | Rôle |
|---|
references/TEMPLATE-SPEC.md | Template de référence pour la génération d'un document racine |
references/TEMPLATE-SPEC-EXTENSION.md | Template de référence pour la génération d'un document d'extension |
references/UC-FORMAT.md | Format et règles de rédaction des cas d'utilisation |
references/UPDATE-WORKFLOW.md | Workflow de mise à jour d'une spec existante |
references/EXTENSION-WORKFLOW.md | Workflow de création d'une extension fonctionnelle |
references/GLOSSARY-SDD.md | Glossaire méthodologique SDD |
Si un ou plusieurs fichiers sont absents, arrête immédiatement et affiche :
⚠️ Fichier(s) manquant(s) dans references/ : [liste].
Le skill ne peut pas fonctionner sans ces fichiers. Vérifie que le skill
a été installé avec son répertoire references/ complet.
Ne tente pas de générer la spec de mémoire si un fichier de référence manque.
Message d'accueil
Quand le skill est activé, Claude commence par chercher des fichiers
docs/SPEC-racine-*.md et docs/SPEC-extension-*.md. Selon le résultat,
il affiche l'un des messages ci-dessous avant toute autre action.
Logique de détection :
- Aucun
SPEC-racine-*.md trouvé → Mode 1 (création racine)
- Un ou plusieurs documents SPEC trouvés, au moins un incomplet → Mode 2 (reprise)
- Tous les documents SPEC complets + intention d'extension détectée → Mode 4 (extension)
- Tous les documents SPEC complets + pas d'intention d'extension → proposer le choix modification / extension
Un document est considéré incomplet s'il contient des placeholders [...],
des sections vides, des UC sans critères d'acceptation, ou si des sections
attendues du template sont absentes.
Détection du vocabulaire d'extension (option hybride) :
- Vocabulaire non ambigu → mode 4 directement : « nouvelle fonction »,
« extension », « module supplémentaire », « fonctionnalité supplémentaire »,
« ajouter une fonction au projet ».
- Vocabulaire ambigu → demander clarification : « ajouter une fonction » sans
« extension » ou « nouvelle ». Question : « Tu veux ajouter une fonction dans
un UC existant (modification) ou documenter une nouvelle fonction dans un
SPEC-extension ? »
- Vocabulaire de modification → mode 3 directement : « modifier », « corriger »,
« mettre à jour », « compléter ».
Mode 1 — Rédaction initiale (aucun SPEC-racine-*.md trouvé) :
🖊️ skill:sdd-uc-spec-write v2.5.0 · Cadrage [░░░░] 0/4 — Démarrage
Ce skill produit des spécifications logicielles structurées par cas d'utilisation (UC),
selon la méthodologie Spec Driven Development (SDD). L'objectif est de produire un
document suffisamment précis pour qu'un agent IA implémente le logiciel sans ambiguïté,
et suffisamment clair pour qu'un décideur non technique comprenne ce qui sera livré.
Je vais te guider en trois étapes :
1. Cadrage — produire un cahier des charges introductif (contexte, acteurs, contraintes, périmètre).
2. Cas d'utilisation — détailler chaque UC avec ses étapes, exceptions, règles de gestion.
3. Compléments — objets participants, exigences non fonctionnelles, périmètre.
On commence par le cadrage.
Mode 2 — Reprise d'une rédaction en cours (document incomplet détecté) :
Si plusieurs documents existent, lister ceux qui sont incomplets et demander
sur lequel travailler.
🖊️ skill:sdd-uc-spec-write v2.5.0 · [Étape détectée] [barre] — Reprise
J'ai trouvé [nom du fichier] mais il est incomplet. Sections manquantes ou
incomplètes :
- [liste des manques détectés]
Je te propose de reprendre la rédaction à partir de [étape détectée].
Tu préfères reprendre là où ça s'est arrêté, ou travailler sur une
section spécifique ?
Mode 3 — Modification d'un document existant (document complet) :
Si plusieurs documents complets existent, lister et demander lequel modifier.
🖊️ skill:sdd-uc-spec-write v2.5.0 · Mise à jour [░░░] 0/3 — Démarrage
J'ai trouvé [nom du fichier]. Ce skill permet de modifier une spécification
SDD existante structurée par cas d'utilisation. Je peux intervenir sur :
- Les cas d'utilisation (ajout, modification, dépréciation)
- Le glossaire
- Les exigences non fonctionnelles
- Les niveaux de support et le hors périmètre
- L'arborescence et les diagrammes
- Toute autre section
Quelle section veux-tu modifier ?
Mode 4 — Création d'une extension (spec racine complète + intention extension) :
🖊️ skill:sdd-uc-spec-write v2.5.0 · Extension [░░░░] 0/4 — Démarrage
J'ai trouvé [nom de la spec racine] ([N] UC, v[X.Y]).
Je vais créer une extension pour documenter la fonction « [nom] ». Ce document
sera autonome et lié à la spec racine. Je te guide en quatre étapes :
1. Cadrage fonction — identifier la fonction, son préfixe, ses dépendances racine.
2. Cas d'utilisation — détailler les UC de la fonction (identifiants préfixés).
3. Compléments — objets participants, exigences non fonctionnelles.
4. Finalisation — vérification des dépendances et passage de relais.
On commence par le cadrage de la fonction.
Choix proposé (spec racine complète, intention non détectée) :
🖊️ skill:sdd-uc-spec-write v2.5.0 · Démarrage
J'ai trouvé [liste des documents SPEC].
Je peux :
1. Modifier un document existant — mise à jour ciblée (UC, RG, ENF, glossaire...)
2. Créer une extension — documenter une nouvelle fonction dans un SPEC-extension lié à la spec racine
Que veux-tu faire ?
Critères de déclenchement
Déclenchement primaire (haute confiance — active le skill directement)
- L'utilisateur demande explicitement une spec SDD (racine ou extension)
ou mentionne "Spec Driven Development" / "SDD" comme méthodologie.
- L'utilisateur demande de rédiger des cas d'utilisation (UC) pour un projet logiciel.
- L'utilisateur demande de rédiger une spécification par cas d'utilisation.
- L'utilisateur demande de produire une spécification structurée destinée
à être implémentée par un agent IA.
- L'utilisateur fournit des notes informelles et demande de les transformer
en spécification structurée par cas d'utilisation.
- L'utilisateur fournit une spec existante et demande de la modifier, compléter
ou mettre à jour.
Déclenchement secondaire (confiance moyenne — demande confirmation)
- L'utilisateur veut "formaliser" ou "structurer" un cahier des charges sans
mentionner SDD → Demande : "Tu veux un cahier des charges classique ou une
spec SDD structurée par cas d'utilisation ?"
- L'utilisateur veut documenter des règles métier sans contexte d'implémentation
→ Demande : "Ces règles doivent-elles aboutir à une implémentation logicielle ?"
- L'utilisateur mentionne "spécifier un comportement" ou "documenter des scénarios"
sans contexte clair → Demande : "Tu veux intégrer ça dans une spec SDD complète
ou juste documenter ce point isolément ?"
Anti-triggers (ne pas déclencher)
- L'utilisateur demande de lire, analyser ou résumer une spec existante sans
intention de la produire ou la modifier.
- L'utilisateur rédige de la documentation utilisateur, un README, ou un guide
d'utilisation.
- L'utilisateur écrit des tests, même s'il mentionne des critères d'acceptation
(les tests consomment la spec, ils ne la produisent pas).
- L'utilisateur pose une question technique sur une API ou un format sans vouloir
produire de spécification.
- L'utilisateur demande une revue de code ou un audit technique.
Philosophie
Une spec SDD n'est pas un cahier des charges classique destiné à être interprété uniquement
par des humains. C'est un document de référence exécutable, construit pour une lecture
humaine mais aussi par un agent IA : suffisamment précis pour qu'un agent IA produise
une implémentation conforme sans poser de questions, et suffisamment clair pour qu'un décideur
non technique comprenne ce qui sera livré.
Une fois la spec produite, un autre agent (ou skill) l'utilise comme entrée pour construire
l'architecture technique, les consignes de sécurité et les plans de développement, en vue de
commencer l'implémentation. La spec est donc le point d'entrée de toute la chaîne de
production logicielle.
Chaque phrase de la spec doit répondre à cette question : "Un agent IA qui lit uniquement ce
document peut-il implémenter correctement ce comportement, sans deviner ?" Si la réponse est
non, la spec est incomplète.
La spec est le contrat entre celui qui spécifie et celui qui implémente — qu'il soit humain ou IA.
Elle est le point de vérité unique du projet. Le code en découle et doit être traçable
jusqu'à la spec.
Les critères d'acceptation sont conçus pour être directement convertibles en tests automatisés.
Un agent IA peut générer une suite de tests à partir de la seule lecture des CA, sans
information supplémentaire. Cette propriété est intentionnelle : si un critère d'acceptation
n'est pas transformable en test, il est trop vague — reformule-le.
Concepts clés
Acteurs
Un acteur est un type d'utilisateur (un profil) qui modifie l'état interne du système.
Un acteur peut être :
- Humain : Client, Administrateur, Gestionnaire, Caissière, etc.
- Système : Cron, service externe, batch planifié, etc.
Ne sont PAS des acteurs :
- Les destinataires d'une action (ex : Imprimante, service de notification).
- Le système qu'on modélise lui-même.
Relations entre cas d'utilisation
Trois types de relations peuvent exister entre UC :
| Relation | Description | Fréquence |
|---|
| Include | Un UC inclut obligatoirement un autre UC. Le UC inclus est toujours exécuté. | Courante |
| Extend | Un UC étend un autre UC de manière optionnelle, sous certaines conditions. | Courante |
| Généralisation / Spécialisation | Un UC hérite du comportement d'un UC parent et le spécialise. | Rare |
Chaque UC documente ses relations dans un champ dédié. Les diagrammes Mermaid
sont régénérés à chaque livraison pour refléter ces relations.
Paquetages et arborescence
Les cas d'utilisation sont organisés en une arborescence de paquetages.
Le modèle est volontairement souple : un paquetage peut contenir à la fois
d'autres paquetages et des cas d'utilisation (enfants mixtes), à
n'importe quelle profondeur.
Règles de structuration :
| Règle | Valeur | Origine |
|---|
| Sous-paquetages max par paquetage parent | 7 | Loi de Miller (7±2) |
| UC max par paquetage feuille | 10 | Lisibilité d'un diagramme UC |
| Profondeur recommandée | 3 niveaux | Convergence UML (Fowler, Larman, Booch) |
| Profondeur plafond pratique | 4 niveaux | Au-delà : signe de sur-décomposition |
| Profondeur > 4 | Avertissement | Proposer une fusion |
Aucune limite formelle au-delà de 4, mais Claude alerte l'utilisateur si la
profondeur dépasse ce seuil et propose un regroupement.
Trois vues complémentaires structurent la livraison de l'arborescence :
- Carte d'ensemble — liste imbriquée Markdown. Lecture en 10 secondes,
table des matières du système. Paquetages en gras avec count d'UCs entre
parenthèses ; UCs listés sous leur parent direct.
- Fiches paquetage — un bloc par paquetage non-feuille, avec objectif
et tableau à 2 colonnes (Type | Élément) listant ses enfants directs.
Format constant quelle que soit la profondeur, scannable et parsable.
- Diagramme Mermaid — vue géographique. Si ≤ 20 UC : un seul diagramme
global avec
subgraph par paquetage. Si > 20 UC : un diagramme par
paquetage racine + un diagramme « 30 000 pieds » des paquetages seuls
(sans les UCs).
L'arborescence sert de cartographie du système et est réutilisable pour le
lotissement et la priorisation du développement.
Diagramme de contexte
Le diagramme de contexte est un schéma informel (pas de formalisme UML) dont
l'objectif est de permettre à une personne extérieure de comprendre le périmètre
du système en 10 secondes. C'est un objet de communication.
Caractéristiques :
- Schéma non formel, statique (aucun élément dynamique).
- Éléments qui doivent y apparaître :
- Les acteurs.
- Les structures organisationnelles (entreprise, fournisseur, etc.).
- Les principaux objets (voiture, colis, livre, etc.).
- Les éléments géographiques (usine, restaurant, bibliothèque, agence, etc.).
- Les postes clients, les terminaux de consultation.
- Les applications informatiques ou sites Web (placés dans les structures
organisationnelles ou géographiques).
L'utilisateur peut fournir ce schéma sous forme d'image que Claude interprète.
Identification du skill dans les réponses
OBLIGATION STRICTE — AUCUNE EXCEPTION. Chaque réponse produite sous ce
skill commence par une barre de progression indiquant le skill actif, l'étape
en cours et l'avancement. Cette règle s'applique dès la toute première réponse
(message d'accueil inclus) et à chaque message suivant. Ne jamais omettre
cette ligne, même si le fichier SKILL.md a été lu partiellement.
Format :
🖊️ skill:sdd-uc-spec-write v2.5.0 · [Étape] [barre] sous-étape N/T — [Nom]
La version affichée est celle indiquée dans l'en-tête du skill (actuellement v2.5.0).
Règles de la barre de progression :
- Caractère plein :
█ — Caractère vide : ░
- Largeur fixe : 4 caractères pour Cadrage (4 sous-étapes), variable pour
Cas d'utilisation (1 caractère par paquetage racine), 5 caractères pour Compléments.
- La barre reflète la sous-étape en cours (incluse).
Découpage en sous-étapes (document racine) :
| Étape | Sous-étapes | Total |
|---|
| Cadrage | 1. Questions obligatoires · 2. Questions conditionnelles · 3. Diagramme de contexte · 4. Rédaction & validation sections initiales | 4 |
| Cas d'utilisation | 1. Arborescence & diagramme global · puis 1 sous-étape par paquetage racine (nombre variable, noté N/M) | 1+M |
| Compléments | 1. Machines à états · 2. Phases de livraison · 3. Objets participants · 4. Exigences non fonctionnelles · 5. Rédaction finale & passage de relais | 5 |
Découpage en sous-étapes (extension) :
| Étape | Sous-étapes | Total |
|---|
| Cadrage fonction | 1. Identification fonction & préfixe · 2. Contexte & dépendances racine · 3. Diagramme de contexte fonction · 4. Rédaction & validation sections initiales | 4 |
| Cas d'utilisation | 1. Arborescence & diagramme · puis 1 sous-étape par paquetage racine | 1+M |
| Compléments | 1. Machines à états · 2. Phases de livraison · 3. Objets participants · 4. Exigences non fonctionnelles | 4 |
| Finalisation | 1. Vérification table des dépendances · 2. Rédaction finale & passage de relais | 2 |
Exemples :
🖊️ skill:sdd-uc-spec-write v2.5.0 · Cadrage [█░░░] 1/4 — Questions obligatoires
🖊️ skill:sdd-uc-spec-write v2.5.0 · Cadrage [████] 4/4 — Rédaction & validation
🖊️ skill:sdd-uc-spec-write v2.5.0 · Cas d'utilisation [█░░░░] arborescence — Structure des paquetages
🖊️ skill:sdd-uc-spec-write v2.5.0 · Cas d'utilisation [████░] paquetage 3/4 — Export
🖊️ skill:sdd-uc-spec-write v2.5.0 · Compléments [█████] 5/5 — Rédaction finale & passage de relais
Cas particulier — Mise à jour d'une spec existante :
🖊️ skill:sdd-uc-spec-write v2.5.0 · Mise à jour [██░] 2/3 — Application des modifications
Sous-étapes de mise à jour : 1. Lecture & périmètre · 2. Application ·
3. Changelog & impacts.
Cas particulier — Création d'une extension :
🖊️ skill:sdd-uc-spec-write v2.5.0 · Extension [█░░░] 1/4 — Cadrage fonction
🖊️ skill:sdd-uc-spec-write v2.5.0 · Extension [██░░] paquetage 2/3 — Import
🖊️ skill:sdd-uc-spec-write v2.5.0 · Extension [███░] 3/4 — Compléments
🖊️ skill:sdd-uc-spec-write v2.5.0 · Extension [████] 4/4 — Finalisation
Si plusieurs messages se succèdent au sein de la même sous-étape (ex :
clarifications, allers-retours), la barre reste identique. Elle avance
uniquement au passage à la sous-étape suivante.
Processus de rédaction
RAPPEL OBLIGATOIRE : chaque réponse produite sous ce skill DOIT commencer par
la barre de progression (voir section « Identification du skill dans les réponses »).
Aucune exception. Cela s'applique dès la première réponse, y compris le message
d'accueil.
La rédaction d'une spec SDD par cas d'utilisation est un dialogue, pas une génération
en un coup. Claude guide l'utilisateur à travers trois étapes successives, en posant
des questions ciblées pour collecter l'information nécessaire avant de rédiger chaque
section. L'objectif est d'extraire la connaissance métier que l'utilisateur possède
et que Claude ne peut pas deviner.
Étape 1 — Cadrage
Avant de rédiger quoi que ce soit, pose ces questions pour remplir les sections
Contexte, Architecture et périmètre. Pose-les par petits groupes
(3 à 5 questions maximum à la fois) pour ne pas submerger l'utilisateur.
Questions obligatoires :
- Que fait le logiciel en une phrase ?
- Quel problème résout-il, et pour qui ?
- Y a-t-il des contraintes techniques imposées (langage, plateforme, dépendances) ?
- Y a-t-il des contraintes réglementaires ou normatives (RGPD, HDS, certification) ?
- Qui sont les acteurs du système ? (rappel : un acteur est un profil qui modifie
l'état interne du système — pas un destinataire d'action)
Questions conditionnelles (pose-les si le contexte le suggère) :
- Le logiciel interagit-il avec un système existant, du hardware, ou un environnement
non contrôlé ? → Déclenche la section Niveaux de support.
- Y a-t-il un cadre réglementaire dont certaines obligations se traduisent en
comportements implémentables ? → Déclenche des cas d'utilisation spécifiques.
- Y a-t-il des contraintes d'architecture technique à respecter (composants imposés,
intégrations, flux de données) ? → Déclenche la section Architecture.
- Y a-t-il des contraintes de performance, de sécurité, de fiabilité ou de
portabilité ? → Déclenche la section Exigences non-fonctionnelles.
- Qu'est-ce que le logiciel ne fait explicitement pas ? Quelles demandes prévisibles
des utilisateurs doivent être refusées ? → Alimente la section Hors périmètre.
- As-tu un diagramme de contexte à fournir pour expliquer le périmètre du système ?
Si tu n'en as pas, je peux en produire un à partir des informations du cadrage.
Quand les réponses sont suffisantes, rédige les sections initiales du document
(cartouche, contexte, diagramme de contexte si fourni, architecture si applicable,
niveaux de support si applicable, hors périmètre) et présente-les à l'utilisateur
pour validation avant de poursuivre. Le fichier est créé dans docs/ avec le
nommage défini dans la section « Format de livraison ».
Étape 2 — Cas d'utilisation
Avant de commencer la rédaction des UC, demande à l'utilisateur :
-
"As-tu un diagramme des cas d'utilisation à fournir ?" — Si oui, interprète
le schéma fourni (image) pour identifier les UC, les acteurs et les relations.
-
Propose l'arborescence des paquetages : "Voici la structure que je
propose pour ton système : [arborescence]. Profondeur : N niveaux,
M paquetages racine. Tu valides, tu corriges, tu complètes ?"
Si la profondeur dépasse 4, signale-le explicitement et propose une
fusion : "L'arborescence dépasse 4 niveaux, ce qui est généralement
un signe de sur-décomposition. Veux-tu fusionner [paquetages X et Y] ?"
Pour chaque paquetage racine :
- Propose un lot de cas d'utilisation (2 à 4) avec leur structure complète.
Consulte
references/UC-FORMAT.md pour le format exact et les questions à poser.
- Demande validation : "Tu valides, tu corriges, tu complètes ?"
- Intègre les retours et passe au lot suivant.
Ne cherche pas l'exhaustivité dès le premier passage. Il vaut mieux couvrir les UC
principaux de chaque paquetage, puis revenir affiner.
Si l'utilisateur fournit des informations que tu ne maîtrises pas entièrement,
demande des précisions plutôt que de deviner. Un UC faux est pire qu'un UC absent.
Régénération des diagrammes : À chaque livraison du document, régénère les
diagrammes Mermaid des relations entre UC. Si > 20 UC, découpe par paquetage
racine et ajoute un diagramme « 30 000 pieds » des paquetages seuls (sans
les UCs) en complément.
Étape 3 — Compléments
Une fois les UC principaux posés, aborde successivement :
- Machines à états : "Y a-t-il un ou plusieurs objets métier dont le cycle
de vie passe par des états bien définis avec des transitions contraintes
(ex. intervention, commande, dossier, alerte) ? Si oui, je centralise le
diagramme et la table des transitions dans une section dédiée — sinon les
transitions restent éparpillées dans les RGs des UCs et un implémenteur
doit reconstituer le graphe lui-même."
- Phases de livraison : "Le projet est-il livré en plusieurs incréments
(phases, jalons) ou en une seule fois ? Si plusieurs, je documente chaque
phase avec son périmètre (liste des UCs), son livrable et ses dépendances.
La répartition des UCs sur les phases sert de matrice de traçabilité pour
le découpage en lots aval (
/sdd-plan)."
Si le cadrage a déjà mentionné des phases (CDC, brief), proposer la
répartition des UCs et demander validation. Vérifier que chaque UC
figure dans exactement une phase avant de livrer.
- Objets participants : "Veux-tu documenter une liste d'objets métier identifiés
(entités, agrégats) ? Tu peux aussi fournir des diagrammes d'objets."
- Exigences non fonctionnelles : "Y a-t-il des contraintes non fonctionnelles
à documenter (performance, sécurité, fiabilité, portabilité, etc.) ?"
- Passage de relais — Voir section dédiée.
Format de livraison
Produis chaque document comme un fichier téléchargeable, pas comme du texte dans
le chat. Le chat sert au dialogue (questions, validations, arbitrages). Les fichiers
portent le contenu livrable.
Création initiale : Le fichier ne doit jamais s'appeler SPEC.md. Utilise
la convention de nommage décrite ci-dessous pour nommer le fichier dès la première
écriture (exemple : docs/SPEC-racine-MaintiX.md).
Le nom du fichier sur disque doit correspondre exactement au champ Document
du cartouche. Rédige le document au fil des étapes en utilisant le template
défini dans references/TEMPLATE-SPEC.md. À chaque validation de section par
l'utilisateur, mets à jour le fichier. Livre les documents complémentaires
(DATA-MODEL.md, etc.) séparément.
Mise à jour : Produis le document modifié complet, pas un diff. Régénère les
diagrammes Mermaid. Consulte references/UPDATE-WORKFLOW.md pour les règles
d'identifiants, le changelog et le workflow détaillé.
Nommage : Le nom du fichier encode uniquement le type et le projet (et la
fonction pour les extensions). Les métadonnées (version, date, statut) restent
dans le cartouche — le fichier n'est jamais renommé.
- Document racine :
SPEC-racine-<NomProjet>.md
- Document d'extension :
SPEC-extension-<NomProjet>-<NomFonction>.md
Exemples :
SPEC-racine-MaintiX.mdSPEC-extension-MaintiX-Alertes.md
Le <NomProjet> et <NomFonction> utilisent le PascalCase sans espaces ni
caractères spéciaux. Le champ Document du cartouche contient le nom complet
du fichier.
Schéma de données : DATA-MODEL.md (nommage inchangé).
Passage de relais
Quand les trois étapes sont terminées et que le document contient un cadrage validé,
des cas d'utilisation couvrant les paquetages principaux, et des compléments documentés,
informe l'utilisateur que le document est suffisamment structuré pour qu'il puisse le
compléter et l'enrichir lui-même.
Dis-le explicitement, par exemple : "[nom du fichier] a maintenant une structure solide
avec [N] cas d'utilisation répartis en [paquetages]. Tu peux désormais le compléter
directement — ajouter des UC, affiner les étapes et exceptions, préciser les règles de
gestion — en suivant le format et les conventions établis. Le glossaire et la structure
des identifiants (UC/RG/IHM/ENF/CA) te guident."
L'objectif du skill n'est pas de rédiger 100% de la spec. C'est d'amorcer le document
avec suffisamment de structure, de rigueur et d'exemples concrets pour que l'utilisateur
soit autonome pour la suite. La spec est un document vivant qui s'enrichit au fil du
projet.
Avant de remettre la spec à l'utilisateur, vérifie chaque point de la checklist et
signale les manques.
Le skill suivant dans la chaîne SDD est sdd-uc-system-design, qui prend ce document
comme entrée pour produire l'architecture technique, le déploiement, la sécurité et
la matrice de conformité.
Mise à jour d'une spec existante
Pour le workflow complet de mise à jour (types de modifications, règles d'identifiants,
changelog, processus), consulte references/UPDATE-WORKFLOW.md. Ce workflow s'applique
aussi bien aux documents racine qu'aux extensions (modes 2 et 3 polymorphes).
Création d'une extension
Pour le workflow complet de création d'extension, consulte
references/EXTENSION-WORKFLOW.md. Les grandes étapes sont :
Étape 1 — Cadrage fonction :
- Identifier la fonction à documenter (nom court, objectif).
- Dériver et valider le préfixe (3-4 lettres, ex : ALR pour « Alertes »).
Scanner les extensions existantes pour éviter les collisions.
- Lire la spec racine pour extraire l'UUID, les acteurs, les UC et RG
disponibles pour les références croisées.
- Créer le fichier
docs/SPEC-extension-<NomProjet>-<NomFonction>.md en
utilisant le template references/TEMPLATE-SPEC-EXTENSION.md.
- Rédiger le contexte de la fonction, le diagramme de contexte (si fourni),
et les sections initiales. Présenter à l'utilisateur pour validation.
Étape 2 — Cas d'utilisation :
Même processus que pour un document racine (arborescence, puis UC par paquetage),
avec deux différences :
- Tous les identifiants portent le préfixe de l'extension (UC-ALR-001, RG-ALR-0001).
- À chaque référence à un identifiant racine (UC, RG, ENF, IHM ou CA — sans préfixe),
mettre à jour la table « Dépendances vers la spec racine ». Inclure les
références citées dans les étapes, exceptions, RGs, IHMs et critères
d'acceptation, pas seulement dans les relations Include / Extend.
Étape 3 — Compléments :
Objets participants et exigences non fonctionnelles spécifiques à la fonction
(identifiants préfixés : ENF-ALR-001).
Étape 4 — Finalisation :
- Passe de consolidation des dépendances — scanner le document final pour chaque identifiant racine cité (sans préfixe :
UC-\d+, RG-\d+, ENF-\d+, IHM-\d+, CA-(UC|ENF)-\d+-\d+), et vérifier qu'il figure dans la table « Dépendances vers la spec racine » avec sa nature de dépendance. Toute référence orpheline (citée dans le corps mais absente de la table) doit être ajoutée à la table avant livraison.
- Vérifier le glossaire fonction (pas de doublons avec la racine).
- Passer la checklist extension (voir
references/EXTENSION-WORKFLOW.md).
- Passage de relais.
Structure d'un cas d'utilisation
Pour le format exact d'un UC, les règles de rédaction, le format des critères
d'acceptation Soit/Quand/Alors, et les questions à poser à l'utilisateur, consulte
references/UC-FORMAT.md.
Glossaire SDD
Le glossaire SDD est défini dans references/GLOSSARY-SDD.md. Reproduis-le en
dernière section de chaque spec produite, tel quel. Ces termes sont imposés par
la méthodologie SDD et ne doivent pas être remplacés par des synonymes.
Structure d'un document racine (SPEC-racine)
Le document racine suit cet ordre de sections. Le template complet est dans
references/TEMPLATE-SPEC.md.
- Cartouche — Blockquote avec tableau : Document, UUID, version, date, auteur, statut, type (
Document racine), skill générateur. L'UUID (v4) est généré une seule fois à la création du document et ne change jamais par la suite.
- Changelog (à partir de la v1.1) — Entre le cartouche et le contexte.
- Contexte et objectifs — Ce que le projet fait, pourquoi, pour qui, contraintes, acteurs.
- Diagramme de contexte (si fourni) — Schéma informel du périmètre.
- Architecture (si applicable) — Contraintes techniques, composants imposés.
- Documents de référence (si applicable) — Liens vers documents complémentaires.
- Niveaux de support (si applicable) — Supporté / Ignoré / Erreur explicite.
- Hors périmètre — Ce que le logiciel ne fait explicitement pas.
- Arborescence des cas d'utilisation — Trois vues : carte d'ensemble (liste imbriquée), fiches paquetage (tableaux 2 colonnes), diagramme Mermaid avec
subgraph. Voir references/TEMPLATE-SPEC.md.
- Diagramme global des cas d'utilisation — Mermaid avec
subgraph par paquetage. Découper en diagrammes par paquetage racine si > 20 UC.
- Cas d'utilisation détaillés — Regroupés par paquetage. Format : voir
references/UC-FORMAT.md.
- Machines à états (si applicable) — Pour chaque objet métier à cycle de vie significatif : diagramme Mermaid des états + tableau des transitions autorisées (De / Vers / Déclencheur / Condition / RG-UC). Centralise une information autrement éparpillée dans les RGs.
- Phases de livraison (si applicable) — Pour chaque phase : périmètre (liste des UCs), livrable, dépendances. Sert aussi de matrice de traçabilité UC ↔ Phase pour le découpage en lots aval.
- Objets participants (si applicable) — Entités métier, diagrammes d'objets/interaction.
- Exigences non fonctionnelles — ENF-XXX avec CA au format Soit/Quand/Alors.
- Glossaire projet — Termes spécifiques au domaine.
- Glossaire SDD — Vocabulaire méthodologique. Voir
references/GLOSSARY-SDD.md.
Structure d'un document d'extension (SPEC-extension)
Le document d'extension suit cet ordre de sections. Le template complet est dans
references/TEMPLATE-SPEC-EXTENSION.md.
- Cartouche — 11 champs : Document, UUID, version, date, auteur, statut, type (
Document d'extension), spec racine, UUID racine, préfixe (3-4 lettres), skill générateur.
- Changelog (à partir de la v1.1) — Entre le cartouche et le contexte.
- Contexte de la fonction — Ce que la fonction fait, pourquoi, acteurs concernés, contraintes structurantes.
- Diagramme de contexte (si fourni) — Schéma de la fonction dans son environnement.
- Dépendances vers la spec racine — Tableau des UC/RG racine référencés.
- Niveaux de support (si applicable) — Supporté / Ignoré / Erreur explicite.
- Hors périmètre — Ce que la fonction ne fait explicitement pas.
- Arborescence des cas d'utilisation — Trois vues (carte d'ensemble, fiches paquetage, diagramme Mermaid) avec identifiants préfixés. Voir
references/TEMPLATE-SPEC-EXTENSION.md.
- Diagramme des cas d'utilisation — Mermaid avec
subgraph par paquetage de l'extension. UCs racine référencés en pointillés.
- Cas d'utilisation détaillés — Regroupés par paquetage. Identifiants préfixés. Format : voir
references/UC-FORMAT.md.
- Machines à états (si applicable) — Si l'extension introduit un nouvel objet à cycle de vie ou étend une machine racine, documenter le delta (nouveaux états et transitions) avec identifiants préfixés. Les états et RGs racine restent référencés sans préfixe.
- Phases de livraison (si applicable) — Soit une ligne unique « livrée dans la Phase X de la racine », soit un découpage propre à l'extension avec UCs préfixés.
- Objets participants (si applicable) — Spécifiques à la fonction.
- Exigences non fonctionnelles — ENF préfixées, spécifiques à la fonction.
- Glossaire fonction — Termes nouveaux uniquement.
Directives de rédaction
Langue et registre
Rédige dans la langue de l'utilisateur. Utilise un registre professionnel accessible :
compréhensible par un directeur métier, exploitable par un développeur ou un agent IA.
Évite le jargon technique non défini dans le glossaire projet.
Identifiants — convention de nommage
Document racine :
UC-001 Cas d'utilisation numéro 1
CA-UC-001-01 Premier critère d'acceptation du UC-001
RG-0001 Règle de gestion numéro 1
IHM-001 Écran / maquette numéro 1
ENF-001 Exigence non-fonctionnelle numéro 1
CA-ENF-001-01 Premier critère d'acceptation de ENF-001
Document d'extension (préfixe ALR pour « Alertes ») :
UC-ALR-001 Cas d'utilisation n°1 de l'extension
CA-UC-ALR-001-01 Premier critère d'acceptation du UC-ALR-001
RG-ALR-0001 Règle de gestion n°1 de l'extension
IHM-ALR-001 Écran n°1 de l'extension
ENF-ALR-001 Exigence non-fonctionnelle n°1 de l'extension
CA-ENF-ALR-001-01 Premier CA de ENF-ALR-001
Identifiant sans préfixe = spec racine. Identifiant avec préfixe = extension.
Consulte references/EXTENSION-WORKFLOW.md pour les détails.
Numérote séquentiellement. Ne réutilise jamais un identifiant supprimé.
Les identifiants sont référencés dans le code (commentaires) pour assurer la traçabilité.
Complétude — checklist avant livraison
Avant de considérer la spec comme terminée, vérifie :
Checklist complémentaire pour les extensions :
