Produit les documents de conception technique SDD (ARCHITECTURE.md, DEPLOYMENT.md, SECURITY.md, COMPLIANCE_MATRIX.md) à partir d'un SPEC-racine-*.md (+ extensions). En CLI écrit dans docs/, sur claude.ai livre des artefacts Markdown. S'active pour concevoir l'architecture technique d'un projet SDD.
Instrucciones de origen · Vista previa de solo lectura
name
sdd-uc-system-design
description
Produit les documents de conception technique SDD (ARCHITECTURE.md, DEPLOYMENT.md, SECURITY.md, COMPLIANCE_MATRIX.md) à partir d'un SPEC-racine-*.md (+ extensions). En CLI écrit dans docs/, sur claude.ai livre des artefacts Markdown. S'active pour concevoir l'architecture technique d'un projet SDD.
metadata
{"version":"3.3.0","author":"Franz TRIERWEILER"}
license
MIT
SDD UC System Design — Conception technique
Version : 3.3.0
Date : 2026-04-21
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.
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-ARCHITECTURE.md
Template de référence pour ARCHITECTURE.md
references/TEMPLATE-DEPLOYMENT.md
Template tronc commun pour DEPLOYMENT.md
references/TEMPLATE-DEPLOYMENT-SAAS.md
Sections spécifiques SaaS (sous-template)
references/TEMPLATE-DEPLOYMENT-DESKTOP.md
Sections spécifiques client lourd (sous-template)
references/TEMPLATE-DEPLOYMENT-DRIVER.md
Sections spécifiques driver (sous-template)
references/TEMPLATE-DEPLOYMENT-EMBEDDED.md
Sections spécifiques logiciel embarqué : mobile, TPE, terminal pro, système embarqué, dev board (sous-template)
references/TEMPLATE-SECURITY.md
Template de référence pour SECURITY.md
references/TEMPLATE-COMPLIANCE-MATRIX.md
Template de référence pour COMPLIANCE_MATRIX.md
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 les documents de conception de mémoire si un fichier
de référence manque.
Déclenchement
Déclenchement primaire (active le skill directement)
L'utilisateur demande de produire l'architecture, le déploiement, la sécurité
ou la conformité d'un projet à partir d'une spec.
L'utilisateur mentionne la « phase de conception » ou « phase 1 » du flux
SDD et fournit (ou référence) une spec.
L'utilisateur demande explicitement un ARCHITECTURE.md, DEPLOYMENT.md,
SECURITY.md ou COMPLIANCE_MATRIX.md.
L'utilisateur demande de produire « les documents de conception » ou
« les livrables de conception technique ».
Déclenchement secondaire (demande confirmation avant d'activer)
L'utilisateur mentionne « concevoir le système » sans référence SDD →
Demande : « Tu veux des documents de conception SDD à partir d'une spec,
ou une conception libre ? »
L'utilisateur fournit une spec sans préciser ce qu'il veut → Demande :
« Tu veux lancer la phase de conception (architecture, déploiement, sécurité,
conformité) ? »
Ne pas déclencher (anti-triggers)
L'utilisateur veut rédiger ou modifier une spec → Utiliser sdd-uc-spec-write.
L'utilisateur demande de planifier des lots ou des User Stories → Phase 2.
L'utilisateur demande d'implémenter du code → Phase 3.
L'utilisateur demande une revue de code → Phase 4.
L'utilisateur pose une question technique ponctuelle sans contexte de projet.
Validation du format d'entrée
Ce skill attend une spec structurée par cas d'utilisation (UC), produite
par le skill sdd-uc-spec-write. Les marqueurs d'une spec compatible sont :
Si la spec fournie utilise un autre format (exigences plates EXG-xxx,
user stories, cahier des charges classique), Claude informe l'utilisateur :
Ce skill attend une spec structurée par cas d'utilisation (format
sdd-uc-spec-write). Le document fourni semble utiliser un autre format.
Veux-tu convertir la spec en format UC d'abord (via sdd-uc-spec-write),
ou continuer avec le format actuel en mode dégradé ?
Message d'accueil
Quand le skill est activé et que la spec est validée, Claude affiche :
📐 skill:sdd-uc-system-design v3.3.0 · Architecture [░░░░░░░] 0/7 — Démarrage
Ce skill produit les documents de conception technique à partir de ta
spec, selon la méthodologie SDD. Je vais produire jusqu'à 4 documents :
1. ARCHITECTURE.md — Comment le système est construit (composants, stack,
flux, données, décisions).
2. DEPLOYMENT.md — Comment le système est déployé et opéré (prérequis,
procédures, CI/CD, monitoring, disaster recovery).
3. SECURITY.md — Comment le système est sécurisé (menaces, exigences,
code sécurisé, réponse à incident).
4. COMPLIANCE_MATRIX.md — Comment le système est conforme à son cadre
réglementaire (seulement si applicable).
On commence par l'architecture, qui conditionne tous les autres documents.
La réflexion se fait en 7 étapes avant toute rédaction. Je te poserai des
questions par petits groupes (3-5 max) à chaque étape.
On y va ?
Philosophie
Les documents de conception sont le pont entre la spécification (ce que le
système doit faire) et l'implémentation (comment il le fait). Ils constituent
le cadre de référence pour tout agent IA ou ingénieur qui implémentera le
projet.
Chaque document répond à une question précise :
Document
Question
ARCHITECTURE.md
Comment le système est-il construit ?
DEPLOYMENT.md
Comment le système est-il déployé et opéré ?
SECURITY.md
Comment le système est-il sécurisé ?
COMPLIANCE_MATRIX.md
Comment le système est-il conforme à son cadre réglementaire ?
Ces documents sont produits itérativement par un dialogue entre Claude et
l'ingénieur/PO. Claude pose des questions, propose des choix, et rédige
progressivement. L'ingénieur valide, corrige, complète.
Principes directeurs
Traçabilité : chaque décision d'architecture doit être rattachable à
un cas d'utilisation (UC-xxx), une règle de gestion (RG-xxxx), une
exigence non fonctionnelle (ENF-xxx), ou un critère d'acceptation
(CA-UC-xxx-yy) de la spec.
Détail sans redondance : être exhaustif mais ne jamais répéter la même
information dans deux documents. Utiliser des renvois croisés.
Spécificité : pas de généralités vagues. Si on choisit PostgreSQL,
expliquer pourquoi et dans quelle version.
Autonomie du lecteur : un agent IA lisant ces documents avec la spec
doit pouvoir implémenter sans poser de questions d'architecture.
Entrées requises
SPEC-racine-*.md (+ extensions éventuelles) (obligatoire) : les
fichiers de spécification SDD structurés par cas d'utilisation, produits
par sdd-uc-spec-write.
Fichiers référencés par la spec (si présents) : DATA-MODEL.md,
ou tout document listé dans la section « Documents de référence » de la spec.
Contexte organisationnel (collecté par Q&A) : contraintes d'infrastructure,
politiques de sécurité internes, cadre réglementaire applicable.
Exploitation de la structure UC
Le format UC offre une richesse d'information architecturale que Claude
exploite systématiquement :
Élément de la spec
Exploitation architecturale
Diagramme de contexte
Vue d'ensemble du périmètre, acteurs, systèmes adjacents — base pour la vue d'ensemble (§ 1)
Section Architecture
Contraintes techniques imposées — entrée directe pour le cadrage macro (A.1)
Packages niveau 2
Pistes pour le découpage en composants ou modules
Packages niveau 1
Pistes pour le découpage en sous-modules ou services
Étapes Na/Nb
Source directe pour les flux métier (flowcharts)
État initial / État final
Source pour les diagrammes de transition d'état (state diagrams)
Exceptions
Source directe pour les flux d'erreur et de rattrapage
Relations include
Dépendances obligatoires entre composants
Relations extend
Points d'extension optionnels de l'architecture
Objets participants
Base du modèle de données
Règles de gestion (RG)
Contraintes métier à implémenter dans le bon composant
Acteurs
Points d'entrée du système (interfaces utilisateur, APIs)
Fréquence d'utilisation
Données de dimensionnement (performance, scalabilité, coûts)
Priorité (Critique/Important/Souhaité)
Priorisation des arbitrages architecturaux
IHM-xxx
Contraintes d'interface et de couche présentation
ENF-xxx
Propriétés non-fonctionnelles transverses
CA-UC-xxx-yy
Critères de validation de l'architecture
Niveaux de support
Frontières du système (ce qui est émulé, ignoré, rejeté)
Hors périmètre
Délimitation de ce que l'architecture ne doit PAS couvrir
Glossaire projet
Source pour le glossaire technique de l'ARCHITECTURE.md (§ 6)
Sorties produites
Fichier
Quand le produire
docs/ARCHITECTURE.md
Toujours
docs/DEPLOYMENT.md
Toujours
docs/SECURITY.md
Toujours
docs/COMPLIANCE_MATRIX.md
Seulement si un cadre réglementaire est identifié
Identification du skill dans les réponses
Chaque réponse produite sous ce skill commence par une barre de progression
indiquant le skill actif, la phase en cours et l'avancement. Cette ligne est
obligatoire, sans exception.
Si plusieurs messages se succèdent au sein de la même étape (ex : questions
de clarification, réponses intermédiaires), la barre reste identique. Elle
avance uniquement au passage à l'étape suivante.
Processus de conception
La conception suit un processus en 4 phases séquentielles. Chaque phase
produit un document. Claude guide l'utilisateur par des questions ciblées
(3 à 5 maximum à la fois) avant de rédiger chaque section.
Phase A — Architecture (ARCHITECTURE.md)
La conception de l'architecture est la phase la plus critique. Elle conditionne
tous les documents suivants. La réflexion doit être exhaustive et profonde
avant toute rédaction. Claude ne rédige RIEN tant que la réflexion n'est pas
terminée et validée.
A.0 — Activation du mode plan
Dès l'entrée en Phase A, Claude active le mode plan : il présente à
l'utilisateur la feuille de route complète de la réflexion architecturale
avant de poser la moindre question. L'objectif est que l'utilisateur sache
exactement où il va et combien d'étapes l'attendent.
Annonce obligatoire (à adapter au contexte) :
La conception de l'architecture va se dérouler en 7 étapes de réflexion
avant que je ne rédige quoi que ce soit. Chaque étape approfondit un axe
différent. Je te poserai des questions par petits groupes (3-5 max) et je
synthétiserai ma compréhension entre chaque étape pour que tu puisses
corriger le tir.
Étapes de réflexion :
Cadrage macro — Type de solution, contraintes imposées, écosystème
Analyse de la spec — Exploitation des UC, packages, flux et objets
Modèle de données — Entités (objets participants), relations, volumes
Flux et interactions — Flux métier (étapes UC), intégrations, événements
Synthèse et arbitrages — Consolidation, trade-offs, décisions ouvertes
Après l'étape 7, je te présenterai une synthèse architecturale complète
pour validation avant de rédiger le document.
On commence ?
Si l'utilisateur souhaite sauter ou fusionner des étapes, Claude s'adapte
mais l'informe des risques (ex : « Si on ne creuse pas le modèle de données
maintenant, l'inventaire des données dans l'ARCHITECTURE.md sera incomplet
et devra être repris plus tard. »).
A.1 — Cadrage macro
Objectif : Comprendre la nature du système et ses contraintes structurantes
avant toute réflexion technique.
Exploitation préalable de la spec :
Avant de poser les questions, Claude exploite les sections de la spec qui
fournissent déjà du contexte architectural :
Diagramme de contexte (si présent) — Identifier les acteurs, systèmes
adjacents, éléments géographiques et organisationnels. Ce schéma donne une
vue d'ensemble du périmètre qui alimente directement la § 1 (Vue d'ensemble)
de l'ARCHITECTURE.md.
Section Architecture (si présente) — Contraintes techniques imposées
(langage, plateforme, composants). Ces contraintes sont non négociables et
réduisent l'espace des questions à poser.
Section Hors périmètre — Délimite ce que l'architecture ne doit PAS
couvrir. Évite de concevoir des composants pour des fonctionnalités exclues.
Claude synthétise ce qu'il a trouvé dans la spec et adapte ses questions
en conséquence (ne pas redemander ce qui est déjà documenté).
Questions obligatoires :
Quel type de solution développez-vous ? (SaaS, client lourd, driver,
logiciel embarqué — mobile, TPE, terminal professionnel, système
embarqué, dev board —, bibliothèque, CLI, API, microservices,
monolithe, autre)
Le système est-il autonome ou s'insère-t-il dans un écosystème existant ?
Si oui, lequel ? (décrire les systèmes adjacents)
Quelles sont les contraintes imposées et non négociables ? (langage,
plateforme, fournisseur cloud, protocoles, normes)
Qui sont les parties prenantes techniques ? (équipe de dev, ops, intégrateurs,
utilisateurs finaux techniques)
Y a-t-il un existant technique à prendre en compte ? (code legacy, base de
données existante, infrastructure en place)
Questions conditionnelles :
Si SaaS ou microservices → Quel fournisseur cloud ? Multi-cloud ?
Quelles régions ? Budget infrastructure mensuel ?
Si driver ou client lourd → Quels OS cibles ? Quelles versions ?
Architecture processeur ? Privilèges requis (kernel, admin) ?
Si logiciel embarqué → Quelle catégorie de cible (téléphone mobile,
TPE, terminal professionnel, système embarqué, dev board) ? Quels
modèles / plateformes ? Quel OS / runtime (Android, iOS, FreeRTOS,
bare metal) ? Connectivité (Wi-Fi, 4G, intermittente, filaire) ?
Mode hors-ligne requis ? Y a-t-il une HAL pour abstraire le matériel ?
Gestionnaire de terminaux / MDM (TOMS, SOTI, autre) ?
Si intégration hardware → Quels protocoles matériels ? Quels équipements ?
Firmwares à supporter ?
Si système distribué → Combien de nœuds ? Réseau fiable ou intermittent ?
Tolérance à la partition ?
Livrable intermédiaire : Claude synthétise le cadrage en 5-10 lignes et
le présente pour validation : « Voici ce que je comprends du contexte. Tu
confirmes / tu corriges ? »
A.2 — Analyse de la spec
Objectif : Exploiter la structure UC de la spec pour extraire toutes les
implications architecturales. Le format UC fournit une matière beaucoup plus
riche qu'une liste d'exigences plates : les flux sont déjà documentés dans
les étapes, les dépendances dans les relations, les données dans les objets
participants.
Travail d'analyse (Claude, en autonomie) :
Claude lit la spec complète et les documents référencés, puis produit :
Cartographie des flux à partir des UC — Pour chaque UC, les étapes
Na/Nb fournissent directement le flux nominal. Claude les regroupe par
package de niveau 2 pour identifier les grands blocs fonctionnels du
système. Les relations include révèlent les dépendances obligatoires
entre blocs, les relations extend révèlent les points d'extension.
Inventaire des implications architecturales par UC — Pour chaque
UC-xxx, Claude évalue si le cas d'utilisation contraint l'architecture
(choix de composant, pattern, protocole, stockage). Attention
particulière aux :
Exceptions : chaque exception peut impliquer un mécanisme
architectural (retry, fallback, circuit breaker, queue de rattrapage).
Règles de gestion (RG-xxxx) : certaines RG imposent des
contraintes transactionnelles, de validation, ou de calcul qui
impactent le placement des composants.
IHM-xxx : les contraintes d'interface peuvent imposer des
choix de couche présentation (SSR, SPA, WebSocket).
Analyse des objets participants — La liste des objets participants
et les éventuels diagrammes d'objets/interactions de la spec fournissent
le brouillon du modèle de données. Claude les exploite comme point de
départ pour l'étape A.3.
Détection des besoins implicites — Claude identifie les besoins
architecturaux qui ne sont pas explicitement formulés dans les UC mais
qui en découlent logiquement (ex : un UC avec une étape « Le système
envoie une notification » implique un mécanisme de notification ; un UC
avec une relation include vers un UC d'authentification implique une
couche de sécurité).
Identification des tensions — Claude repère les UC ou ENF dont les
contraintes pourraient être en tension (ex : un UC exigeant un temps de
réponse < 200ms + une RG imposant un calcul complexe → besoin de cache
ou de pré-calcul).
Présentation à l'utilisateur :
Claude présente cette analyse sous forme structurée :
Analyse de la spec — Implications architecturales
J'ai identifié N cas d'utilisation à impact architectural, M besoins
implicites non formulés dans la spec, et P tensions à arbitrer.
[Tableau structuré par package de niveau 2]
Questions de clarification :
Questions de clarification (3-5 max) :
Les questions portent sur les zones d'ombre révélées par l'analyse. Elles ne
sont pas pré-définies — elles émergent de la lecture de la spec. Exemples
typiques :
« UC-012 décrit une étape 3b (notification) mais ne précise pas le canal
(email, SMS, push). Quel est le mécanisme attendu ? »
« La relation include entre UC-005 et UC-003 implique que [composant X]
dépend de [composant Y]. Tu confirmes ce couplage ? »
« RG-0015 impose [contrainte] mais ENF-002 demande [performance]. Ces deux
exigences sont en tension. Quel compromis privilégier ? »
« Les exceptions de UC-020 (étapes 2b, 4b) impliquent un mécanisme de
retry. Est-ce un besoin réel ou le système doit-il simplement échouer ? »
A.3 — Modèle de données
Objectif : Cartographier exhaustivement les données du système avant de
choisir comment les stocker et les transporter.
Travail d'analyse (Claude, en autonomie) :
Claude part des objets participants de la spec comme base. Cette section
de la spec liste les entités métier identifiées à travers les cas
d'utilisation. Claude enrichit cette liste avec :
Les attributs principaux déduits des étapes et règles de gestion des UC
Les relations entre entités déduites des relations entre UC (include,
extend) et des diagrammes d'objets/interactions (si présents dans la
spec)
La classification de sensibilité par entité (public, interne,
confidentiel, secret)
L'estimation des volumes (nombre d'enregistrements, taille, croissance)
Le cycle de vie des données (création, modification, archivage,
suppression)
Si la spec contient un DATA-MODEL.md référencé, Claude l'utilise
directement comme point de départ au lieu des objets participants.
Questions obligatoires :
Le brouillon d'inventaire basé sur les objets participants est-il
complet ? Manque-t-il des entités ?
Quelles sont les données les plus sensibles ? Y a-t-il des données
soumises à des réglementations spécifiques ?
Quels sont les volumes réalistes ? (nombre d'utilisateurs, de transactions
par jour/mois, de fichiers, taille des fichiers)
Y a-t-il des données qui doivent être purgées ou archivées après un délai ?
Questions conditionnelles :
Si données de santé → Classification spécifique ? Pseudonymisation ?
Séparation des données directement identifiantes ?
Si données en temps réel → Fréquence d'arrivée ? Taille des événements ?
Fenêtre de rétention en mémoire ?
Si multi-tenant → Isolation des données par tenant ? Données partagées
entre tenants ?
Si système distribué → Données répliquées ? Stratégie de cohérence ?
(CAP theorem)
Livrable intermédiaire : Inventaire des données validé par l'utilisateur.
A.4 — Flux et interactions
Objectif : Identifier tous les flux de données et d'interactions entre
composants, systèmes externes, et utilisateurs. Le format UC fournit une
matière directement exploitable : les étapes Na/Nb sont les flux nominaux,
les exceptions sont les flux d'erreur.
Travail d'analyse (Claude, en autonomie) :
À partir des UC de la spec et des étapes précédentes, Claude identifie :
Flux métier principaux — Extraits directement des étapes Na/Nb des
UC. Claude regroupe les UC liés par des relations include/extend pour
reconstituer les parcours de bout en bout (ex : le parcours « inscription
→ commande → paiement → livraison » correspond à une chaîne de UC liés).
Pour chaque flux, Claude note les composants impliqués et les données
transportées.
Flux d'intégration — Identifiés via les étapes où le système
interagit avec un acteur de type « système » ou un service externe
mentionné dans la spec.
Flux d'événements — Identifiés via les étapes asynchrones des UC
(notifications, traitements différés, jobs planifiés) et les acteurs de
type « système » (cron, batch).
Flux d'erreur — Extraits directement des exceptions des UC. Chaque
exception documentée dans la spec correspond à un chemin d'erreur
que l'architecture doit supporter.
Cycles de vie des entités — Les champs État initial et État
final de chaque UC révèlent les transitions d'état des entités métier.
En chaînant les UC qui partagent les mêmes entités, Claude reconstitue
les diagrammes de transition d'état complets (source pour § 4.3 de
l'ARCHITECTURE.md).
Pour chaque flux, Claude note : UC source, déclencheur (étape Na), étapes,
composants impliqués, données transportées, cas d'erreur (exceptions).
Présentation à l'utilisateur :
J'ai identifié N flux métier (issus des UC), M intégrations et
P flux d'événements. Voici la liste. Je vais te poser des questions
sur les flux les plus complexes.
Questions obligatoires :
La liste des flux est-elle complète ?
Pour chaque intégration externe : quel protocole ? Quelle authentification ?
Quel SLA du système tiers ?
Y a-t-il des flux qui doivent être transactionnels (tout ou rien) ?
Y a-t-il des flux asynchrones nécessitant une garantie de livraison
(at-least-once, exactly-once) ?
Questions conditionnelles :
Si événements → Message broker dédié ou queues simples ? Ordre garanti ?
Si fichiers échangés → Formats ? Taille max ? Fréquence ? Validation ?
Si temps réel → WebSocket, SSE, polling ? Latence acceptable ?
Livrable intermédiaire : Cartographie des flux validée.
A.5 — Choix technologiques
Objectif : Sélectionner et justifier chaque brique de la stack technique.
Pas de technologie sans raison documentée. Pour chaque choix, au moins une
alternative écartée doit être mentionnée.
Travail d'analyse (Claude, en autonomie) :
À partir des contraintes (A.1), des données (A.3) et des flux (A.4), Claude
propose une stack technique en respectant ces principes :
Contraintes d'abord — Les technologies imposées par la spec ou
l'utilisateur sont non négociables.
Cohérence de l'écosystème — Préférer des technologies qui fonctionnent
bien ensemble (ex : ne pas mixer 4 langages sans raison).
Maturité et support — Préférer des technologies stables, bien
documentées, avec une communauté active.
Pérennité — Évaluer le risque d'obsolescence de chaque brique
(mainteneur, fréquence des releases, taille de la communauté). Si le
risque est modéré ou plus, documenter un plan de mitigation (migration,
fork, remplacement).
Coût total — Inclure les coûts de licence, d'hébergement, de formation,
de maintenance.
Présentation à l'utilisateur :
Pour chaque brique, Claude présente :
Besoin
Proposition
Pourquoi
Alternative écartée
Pourquoi écartée
[ex: API REST]
[ex: FastAPI]
[ex: Async, typage natif, perf]
[ex: Django REST]
[ex: Plus lourd, sync par défaut]
Questions obligatoires :
Valides-tu ces choix ? Y a-t-il des technologies que tu veux imposer ou
exclure ?
Y a-t-il des contraintes de licence ? (open source uniquement, licence
commerciale interdite, etc.)
L'équipe maîtrise-t-elle ces technologies ou faut-il prévoir une montée
en compétence ?
Livrable intermédiaire : Stack technique validée avec justifications.
A.6 — Propriétés non-fonctionnelles
Objectif : Traduire les exigences non-fonctionnelles de la spec (ENF-xxx)
et les contraintes non fonctionnelles rattachées aux UC en décisions
architecturales concrètes. Couvrir aussi les propriétés non explicitement
demandées mais nécessaires.
Exploitation préalable de la spec :
Claude exploite le champ Fréquence d'utilisation de chaque UC pour
alimenter le dimensionnement. Les UC à haute fréquence (ex : « 500 fois/jour »)
orientent les choix de performance, cache et scalabilité. Les UC à faible
fréquence (ex : « mensuel ») peuvent tolérer des traitements plus lourds.
Axes d'analyse systématique :
Claude passe en revue chaque axe et évalue sa pertinence pour le projet :
Axe
Questions clés
Impact architectural
Performance
Temps de réponse cible ? Débit max ? Latence max ?
Cache, CDN, index, pré-calcul
Scalabilité
Croissance attendue ? Pics de charge ?
Horizontal vs vertical, stateless, sharding
Disponibilité
SLA cible ? Tolérance aux pannes ?
Réplication, failover, multi-AZ
Résilience
Que se passe-t-il si un composant tombe ?
Circuit breaker, retry, DLQ, graceful degradation
Observabilité
Comment savoir que le système fonctionne ?
Métriques, logs structurés, traces, alertes
Maintenabilité
Facilité à modifier, corriger, étendre ?
Modularité, tests, documentation, DX
Portabilité
Dépendance à un fournisseur ? Migration possible ?
Abstraction, standards, IaC
Coût
Budget contraint ? Optimisation nécessaire ?
Sizing, auto-scaling, reserved instances
Pour chaque axe pertinent, Claude pose 1-2 questions ciblées à l'utilisateur
pour préciser les attentes et les seuils.
Livrable intermédiaire : Tableau des propriétés non-fonctionnelles avec
seuils chiffrés et décisions architecturales associées.
A.7 — Synthèse et arbitrages
Objectif : Consolider toute la réflexion en une vision architecturale
cohérente. Identifier les trade-offs et les décisions ouvertes. C'est la
dernière étape avant la rédaction.
Travail de synthèse (Claude, en autonomie) :
Claude produit un document de synthèse structuré :
Vision architecturale — Description en 5-10 phrases du système tel
qu'il sera construit.
Composants identifiés — Liste des composants avec leurs responsabilités.
Les packages de niveau 2 de la spec servent de piste initiale pour le
découpage, mais l'architecture n'est pas tenue de reproduire exactement
la structure des packages (un package peut être éclaté en plusieurs
composants, ou plusieurs packages fusionnés dans un composant).
Matrice de traçabilité UC → Composants — Tableau montrant quel
composant implémente quel UC. Cela garantit la couverture complète.
La priorité de chaque UC (Critique/Important/Souhaité) est reportée
dans la matrice pour guider les arbitrages : un UC Critique impose des
choix architecturaux non négociables, un UC Souhaité peut accepter des
compromis.
Trade-offs explicites — Pour chaque compromis fait, documenter ce qui
a été sacrifié et pourquoi (ex : « On choisit la cohérence éventuelle
plutôt que la cohérence forte pour gagner en disponibilité »).
Décisions ouvertes — Points qui restent à trancher, avec les options
et leurs conséquences.
Risques architecturaux — Points de fragilité identifiés, avec des
pistes de mitigation.
Présentation à l'utilisateur :
Synthèse architecturale — Validation avant rédaction
[Synthèse complète incluant la matrice UC → Composants]
Décisions ouvertes (à trancher maintenant) :
[Décision 1] — Option A vs Option B
[Décision 2] — ...
Risques identifiés :
[Risque 1] — Mitigation proposée : [...]
Tu valides cette vision ? Une fois validée, je rédige le ARCHITECTURE.md.
Claude ne passe à la rédaction que lorsque l'utilisateur valide explicitement
la synthèse. Si l'utilisateur demande des modifications, Claude revient à
l'étape concernée.
A.8 — Rédaction
Prérequis : La synthèse A.7 est validée par l'utilisateur.
Rédige le ARCHITECTURE.md section par section en suivant le template
references/TEMPLATE-ARCHITECTURE.md. La rédaction s'appuie intégralement sur les livrables intermédiaires
validés aux étapes A.1 à A.7 :
§ 1 (Vue d'ensemble) ← A.1 cadrage + A.7 vision + diagramme de contexte de la spec
§ 2 (Principes) ← A.7 trade-offs + A.6 propriétés
§ 3.1 (Choix technologiques) ← A.5 choix avec alternatives écartées
§ 3.2 (Pérennité) ← A.5 évaluation du risque d'obsolescence par technologie
§ 3.3 (Coûts) ← A.5 estimation des coûts de fonctionnement
§ 8 (Glossaire) ← termes accumulés + glossaire projet de la spec
§ 9 (Documents de référence) ← documents utilisés et produits
Présente chaque section majeure à l'utilisateur pour validation avant de
passer à la suivante. Les diagrammes Mermaid doivent être syntaxiquement
corrects et refléter fidèlement les flux validés en A.4.
Convention de traçabilité dans l'ARCHITECTURE.md :
Les références à la spec utilisent les identifiants suivants :
UC-xxx — Cas d'utilisation
CA-UC-xxx-yy — Critère d'acceptation d'un UC
RG-xxxx — Règle de gestion
ENF-xxx — Exigence non fonctionnelle
CA-ENF-xxx-yy — Critère d'acceptation d'une ENF
IHM-xxx — Référence d'interface
Phase B — Déploiement (DEPLOYMENT.md)
Questions obligatoires
Comment le logiciel est-il distribué aujourd'hui (ou comment doit-il
l'être) ? (conteneurs, packages, installeur, téléchargement, store)
Quels sont les environnements cibles ? (dev, staging, production, on-premise)
Y a-t-il un pipeline CI/CD existant ? (outils, plateforme)
Qui opère le système en production ? (équipe interne, client, managé)
Quelle est la stratégie de mise à jour ? (rolling, blue-green, canary,
manuelle)
Questions conditionnelles
Si SaaS → Multi-tenant ? Isolation des données ? CDN ?
Si client lourd → Mécanisme de mise à jour automatique ? Signature du code ?
Si driver → Processus de certification ? Signature noyau ?
Si logiciel embarqué → Quel mécanisme de distribution (TMS/MDM, app
store, flashage firmware) ? Parc homogène ou hétérogène ? Si parc
hétérogène, y a-t-il une HAL ? Mode hors-ligne requis ? Contraintes
de certification (PCI-PTS, EMVCo, App Store Review) ?
Si on-premise → Prérequis réseau ? Proxy ? Pare-feu ?
Rédaction
Le DEPLOYMENT.md est construit à partir du tronc commun
(references/TEMPLATE-DEPLOYMENT.md) complété par le sous-template
correspondant au type de solution identifié en A.1 :
Type de solution
Sous-template
SaaS
references/TEMPLATE-DEPLOYMENT-SAAS.md
Client lourd / Desktop
references/TEMPLATE-DEPLOYMENT-DESKTOP.md
Driver / Firmware
references/TEMPLATE-DEPLOYMENT-DRIVER.md
Logiciel embarqué (mobile, TPE, terminal pro, dev board)
references/TEMPLATE-DEPLOYMENT-EMBEDDED.md
Bibliothèque / CLI / Autre
Pas de sous-template — tronc commun uniquement
Les sections du sous-template sont insérées après le tronc commun,
numérotées à la suite. Si le type de solution ne correspond à aucun
sous-template, le tronc commun suffit.
Phase C — Sécurité (SECURITY.md)
C.1 — Modèle de menaces
Travail d'analyse (Claude, en autonomie) :
Claude exploite la spec (acteurs, interfaces, points d'entrée) et
l'ARCHITECTURE.md (composants, flux, exposition réseau) pour produire :
Surface d'attaque — Points d'entrée du système, exposition, données
accessibles.
Référentiels sectoriels (§ 5) : exigences de sécurité induites par
les référentiels du marché (PGSSI-S, PCI-DSS, DORA, NIS2, etc.)
identifiés dans la spec. Supprimer si non applicable.
Principes de développement sécurisé (§ 6) : règles de codage
sécurisé (effacement mémoire, fail securely, encodage contextuel, etc.).
Stack technique (§ 8) : exigences spécifiques par technologie.
Réponse à incident (§ 9) : rôles, procédure, notification.
Conformité et privacy (§ 10) : renvoi vers COMPLIANCE_MATRIX.md,
obligations RGPD liées à la sécurité.
Spécificités (§ 11) : exigences propres au contexte du projet.
Chaque exigence est numérotée selon la convention définie dans le template.
Phase D — Conformité (COMPLIANCE_MATRIX.md)
Évaluation préalable
Avant de rédiger, Claude évalue si un fichier de conformité est pertinent :
Si la spec ne mentionne aucun cadre réglementaire → Informer
l'utilisateur que le fichier n'est pas nécessaire et proposer de passer.
Si la spec mentionne un cadre réglementaire (HDS, RGPD, PGSSI-S,
PCI-DSS, SOC2, etc.) → Identifier les référentiels applicables et
confirmer avec l'utilisateur.
Questions obligatoires (si applicable)
Quels référentiels réglementaires s'appliquent au projet ?
Y a-t-il des UC ou ENF de la spec qui déclenchent ces obligations ?
(identifier les UC-xxx / ENF-xxx « mères »)
Qui est responsable de la conformité ? (rôle, équipe)
Y a-t-il des certifications à obtenir ?
Pour chaque exigence, qui en porte l'implémentation ? (responsable par
exigence ou par lot d'exigences)
Y a-t-il des échéances réglementaires ou contractuelles ? (dates butoirs
de mise en conformité)
Rédaction
Les exigences de conformité sont numérotées avec un préfixe propre au
référentiel (HDS-xx, RGPD-xx, PGSSI-xx, etc.) et rattachées à leur
exigence « mère » dans la spec (UC-xxx ou ENF-xxx). Elles ne
réutilisent jamais la numérotation UC-xxx / ENF-xxx de la spec.
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).
Création initiale :
Rédige chaque document au fil des phases. À chaque validation de section
par l'utilisateur, mets à jour le fichier.
Commence toujours par ARCHITECTURE.md — les autres documents en dépendent.
Livre chaque document séparément dans docs/.
Mise à jour :
Produis le document modifié complet, pas un diff.
Si une modification d'architecture impacte le déploiement ou la sécurité,
signale-le et propose de mettre à jour les documents concernés.
Mets à jour le changelog en fin de fichier.
Convention de versioning :
Majeure (X.0) : changement structurel d'architecture, ajout ou retrait
d'un composant majeur, changement de stack.
Mineure (X.Y) : ajout de détail, précision, correction, ajout d'une
exigence de sécurité.
Renvois croisés entre documents
Les documents de conception forment un tout cohérent. Utilise des renvois
croisés pour éviter la redondance :
ARCHITECTURE.md → référence les UC (UC-xxx), règles de gestion (RG-xxxx),
exigences non fonctionnelles (ENF-xxx) et critères d'acceptation
(CA-UC-xxx-yy, CA-ENF-xxx-yy) de la spec
DEPLOYMENT.md → référence les composants de ARCHITECTURE.md
SECURITY.md → référence les composants de ARCHITECTURE.md et les UC /
ENF de la spec
COMPLIANCE_MATRIX.md → référence les UC / ENF « mères » de la spec et les
exigences de SECURITY.md quand elles se recoupent
Format de renvoi : Voir ARCHITECTURE.md § 4.2 ou Réf. UC-007.
Checklist de validation
Avant de remettre chaque document à l'utilisateur, vérifie :
ARCHITECTURE.md
Le diagramme d'architecture haut niveau (§ 4.1) est présent et lisible.
Chaque composant (§ 4.2) a une responsabilité unique et claire.
La matrice de traçabilité UC → Composants couvre tous les UC de la spec avec leur priorité.
Les diagrammes Mermaid (flowcharts § 4.3, séquences § 4.4, states § 4.5) sont syntaxiquement corrects.
La stack technique (§ 3.1) est justifiée (chaque choix avec alternative écartée).
La pérennité des choix (§ 3.2) est évaluée (risque d'obsolescence, plan de mitigation si risque modéré+).
Les propriétés non-fonctionnelles (§ 5) ont des seuils chiffrés et des décisions associées.
Les décisions d'architecture (§ 6) documentent les trade-offs et leurs conséquences.
L'inventaire des données (§ 4.6) couvre les objets participants de la spec.
La structure du répertoire (§ 7) est cohérente avec l'architecture.
Le glossaire technique (§ 8) couvre les termes spécifiques sans dupliquer le glossaire projet.
Les coûts de fonctionnement (§ 3.2) sont estimés.
DEPLOYMENT.md
Les prérequis sont listés exhaustivement (infra, logiciels, réseau, secrets).
La configuration par environnement (§ 4) est documentée.
La procédure de déploiement est reproductible par un agent IA.
La stratégie de rollback est documentée.
Les health checks et critères de readiness (§ 8) sont définis.
Le monitoring et les alertes sont définis.
Le disaster recovery (§ 11) documente RPO/RTO et les scénarios de sinistre.
Le sous-template spécifique au type de solution est intégré (si applicable).
SECURITY.md
Le modèle de menaces est documenté (surface d'attaque, acteurs, frontières de confiance).
Chaque exigence a un ID unique, une description et un statut.
Le SDLC sécurisé est documenté (SAST, DAST, dépendances, SBOM, hardening).
Les exigences spécifiques à la stack sont documentées.
Le plan de réponse à incident est renseigné (rôles, procédure, notification).
Les obligations de conformité/privacy sont résumées (avec renvoi vers COMPLIANCE_MATRIX.md si applicable).
COMPLIANCE_MATRIX.md
Chaque exigence est rattachée à son référentiel source.
Les UC / ENF « mères » de la spec sont identifiés.
Chaque exigence a un responsable et une échéance.
La numérotation est indépendante de la spec.
La légende des statuts est présente.
Passage de relais
Quand les documents de conception sont produits et validés, Claude informe
l'utilisateur de la suite du flux SDD :
Les documents de conception sont prêts :
- ARCHITECTURE.md v1.0
- DEPLOYMENT.md v1.0
- SECURITY.md v1.0
- COMPLIANCE_MATRIX.md v1.0 (si applicable)
La prochaine étape du flux SDD est la planification : découper le travail
en lots et plans d'implémentation à partir de l'architecture et de la
spec. Tu peux le faire manuellement ou avec un skill de planification.
Ces documents sont vivants — ils seront mis à jour au fil du développement
si des décisions d'architecture évoluent.
Utilisation des templates
Les templates sont définis dans le répertoire references/ du skill. Ne génère
jamais la structure d'un document de mémoire — les templates sont la
référence. Remplis les sections au fil du dialogue, supprime les sections
marquées comme optionnelles si elles ne s'appliquent pas, et retire les
commentaires HTML avant livraison.
Document
Template
ARCHITECTURE.md
references/TEMPLATE-ARCHITECTURE.md
DEPLOYMENT.md
references/TEMPLATE-DEPLOYMENT.md + sous-template selon le type de solution
