Guide de démarrage
Démarrer — votre premier cycle SDD en une journée
De l'installation à la première PR verrouillée par le Drift Lock : ce guide condense tout ce qu'il faut pour passer en SDD Mode. Une commande pour installer, une matinée pour cadrer, un après-midi pour livrer votre première fonctionnalité spec-anchored.
Prérequis
- Node.js 18+ — la CLI
aiad-sdds'exécute vianpx, sans installation globale ; - un agent IA de développement — Claude Code en première intention, mais aussi Cursor, GitHub Copilot, Codex, Gemini ou Kiro : depuis
aiad-sdd1.12, SDD Mode est multi-runtime (Kiro depuis la 1.19.0), les règles sont émises pour chaque outil depuis une source unique (npx aiad-sdd emit-rules) ; - un dépôt Git — neuf ou existant, les deux chemins sont couverts ci-dessous.
Installation en 1 minute
npx aiad-sdd initCette unique commande installe dans votre projet : la structure .aiad/ (templates PRD, ARCHITECTURE, AGENT-GUIDE, index des intents et des SPECs), les 4 agents de gouvernance Tier 1 (AI-ACT, RGPD, RGAA, RGESN) complétés de l'agent CRA pour les produits logiciels, les 33 commandes slash (17 /sdd + 16 /aiad) regroupées sous les routers /sdd, /aiad et /aiad-help, les 9 skills réutilisables, et un CLAUDE.md configuré avec le cycle, la hiérarchie documentaire et les règles absolues.
| Option | Effet |
|---|---|
--sans-gouvernance | Installe le cycle SDD sans les 4 agents de gouvernance Tier 1. |
--minimal | Profil AIAD-Lean : Intent Statement + SQS + Drift Lock, 4 commandes, < 1 000 tokens à froid. Évoluez ensuite avec --upgrade gouvernance|rituals|metrics|all. |
--runtime cursor|codex|copilot|gemini|kiro|all | Émet les fichiers de règles pour le runtime ciblé (multi-runtime depuis aiad-sdd 1.12 ; kiro depuis la 1.19.0). |
Puis, dans votre agent, lancez /sdd init. La commande affiche d'abord un message de redémarrage recommandé : pour charger toutes les commandes fraîchement installées dans la session, relancez l'agent (/exit puis nouvelle session) avant de poursuivre. Vous pouvez continuer sans redémarrer, mais certaines skills pourraient ne pas être disponibles.
Le cadrage : trois artefacts fondamentaux
/sdd init guide la rédaction interactive des trois documents qui structurent tout le reste — et propose deux assistants de discovery dédiés :
/sdd prd— l'assistant PRD pose les questions d'un Product Manager : vision, utilisateurs, outcomes. Le PRD ne sera injecté qu'en phase de cadrage, jamais en développement ;/sdd arch— l'assistant ARCHITECTURE pose les questions d'un architecte : stack, patterns, contraintes. Le document sera injecté condensé (~500 tokens) dans chaque session agent ;- l'AGENT-GUIDE — contexte permanent de l'agent : règles absolues, conventions, puis au fil des itérations les Lessons Learned et Human Learnings.
Le cadrage complet prend de 3 à 7 jours pour une équipe — mais une version minimale viable des trois artefacts s'écrit en une matinée. Ne visez pas la perfection : ce sont des documents vivants.
Votre premier cycle pas à pas
Le cycle SDD compte sept étapes — on n'en saute jamais aucune. Pour une fonctionnalité bien délimitée, l'ensemble tient dans une journée :
| Étape | Commande | Durée indicative | Livrable |
|---|---|---|---|
| 1. Intent Statement | /sdd intent | 15-30 min | Intent archivé dans .aiad/intents/, auteur humain identifiable. |
| 2. Research | /sdd research | Variable (proportionnée) | Discovery ancrée dans le code + verdict GO / CONDITIONAL GO / DEFER / NO-GO tranché par l'humain. |
| 3. SPEC | /sdd spec | 30-60 min | SPEC committée dans .aiad/specs/ — format prose ou EARS. Si l'agent dispose de credentials ou d'un accès en écriture partagé : section « Périmètre d'exécution de l'agent » (gabarits du paquet : à paraître). |
| 4. Execution Gate | /sdd gate | 15-30 min | SQS ≥ 4/5, Gate ouverte, Context Engineering Budget préparé. Pré-contrôle déterministe gate-precheck avant le SQS : à paraître. |
| 5. Exécution agent | /sdd exec | 2 h - 3 jours | Plan d'implémentation validé, puis code + tests annotés @spec. |
| 6. Validation | /sdd validate | 1-4 h | Rapport technique + fonctionnel + gouvernance Tier 1, puis validation métier de l'intention. |
| 7. Drift Lock | /sdd drift-check | 10 min | SPEC et code synchronisés dans la même PR — mergeable. |
La règle est absolue : tant que le SQS n'atteint pas 4/5, l'agent ne démarre pas. Si la SPEC est trop volumineuse pour être atomique, /sdd split la découpe ; si la session agent s'interrompt, /sdd resume la reprend avec un contexte minimal.
Adoption sur un projet existant
Vous n'avez pas besoin de repartir de zéro. /aiad init réalise un bootstrap progressif : il analyse le codebase réel et génère les artefacts initiaux depuis l'état du projet — l'ARCHITECTURE depuis les patterns observés, l'AGENT-GUIDE depuis les conventions en place. Aucune disruption : le cycle SDD s'applique d'abord aux nouvelles fonctionnalités, et la couverture en SPECs s'étend itération après itération.
Quand un nouveau membre rejoint l'équipe, /aiad onboard génère un briefing contextualisé depuis les artefacts (PRD, ARCHITECTURE, SPECs actives, Lessons Learned) avec une liste de lecture priorisée.
Dual-mode : --guided et --fast
Chaque commande supporte deux modes. --guided est le mode débutant : questions une par une, concepts expliqués (SQS, Drift Lock…), exemples proposés — utilisez-le la première fois. --fast est le mode expert : inputs en bloc, rendu direct. Sans flag, l'agent auto-détecte : structure .aiad/ vide ou quasi vide → guidé, sinon → fast. Pour votre première journée, restez en --guided.
Conseils pour la première itération
- Commencez petit — choisissez une fonctionnalité bien délimitée, pas le chantier structurant du trimestre ;
- une seule SPEC atomique — une session agent = une SPEC. C'est la règle du Context Engineering Budget, et la meilleure protection contre le context rot ;
- mesurez dès la première itération — SQS, drifts détectés, first-time success : les métriques n'ont de valeur qu'avec une tendance, et la tendance commence au premier point.
Rester à jour
npx aiad-sdd updateMet à jour les commandes, les skills et les agents de gouvernance vers la version du paquet, sans toucher à vos artefacts .aiad/ (PRD, Intents, SPECs, métriques). En CI, npx aiad-sdd update --check échoue si le projet diverge du paquet. Prochaine version — à paraître : update sauvegardera tout agent de gouvernance que vous avez adapté localement (AIAD-X.md.bak-AAAA-MM-JJ) avant de l'écraser — voir la référence CLI.
Vérifier sa maturité
npx aiad-sdd statusLa commande calcule un score de maturité SDD de 0 à 5 : fraîcheur des artefacts, SPECs actives et leur SQS, gouvernance activée, recommandations immédiates. Lancez-la après chaque itération — la progression du score raconte l'adoption mieux que n'importe quel ressenti.
Votre premier cycle bouclé, explorez chaque étape en détail en commençant par l'Intent Statement, puis installez les rituels d'équipe — rétrospective, Atelier d'Intention — pour faire vivre la boucle d'amélioration.