Boucle de Développement Piloté par les Spécifications (SDDL)

Open Source : https://github.com/xt-mahh/sddl (2026-08-06, Licence MIT) Méthodologie complète + scripts de vérification + exemples de projets sur le dépôt GitHub.

Aperçu

SDDL fait passer la programmation IA d'un modèle « piloté par la conversation » à un modèle « piloté par les spécifications ». Promesse clé : définir clairement ce qu'il faut faire avant d'écrire du code – une spécification structurée (spec) comme source unique de vérité, avec une double boucle fermée garantissant la qualité et l'auditabilité.

Boucle de formation (répond « quoi faire »)       Boucle de dérivation (répond « comment bien faire »)
Besoins ──▶ Entretien ──▶ Ébauche de spec ──▶ Gel de la spec ──▶ tests/code/docs ──▶ Convergence
                └─▶ Contrôle qualité SQC ──┘                    └─▶ Vérifications C1-C4 ──┘
                └─▶ Confirmation des décisions ──┘

Pourquoi utiliser SDDL ? Les points faibles de la programmation conversationnelle : dérive du contexte (50 tours de discussion, oubli des accords du 3e tour), désynchronisation des artefacts (le code change mais pas les tests/la documentation), évaluation subjective (« ça semble bon » au lieu de « conforme à la spec »). SDDL résout ces problèmes avec une spec stable et chargeable en entier + des vérifications de cohérence par couches.

Quand Utiliser

Déclencheurs :

L'utilisateur souhaite démarrer un nouveau projet, écrire une fonctionnalité principale, concevoir une architecture système
L'utilisateur dit « d'abord planifier », « d'abord concevoir », « d'abord rédiger les spécifications », « comment faire cette fonctionnalité »
L'utilisateur a besoin de produire simultanément plusieurs artefacts (code + tests + documentation)
Projet avec ≥ 5 interfaces, ou ≥ 5 critères d'acceptation « must », durée de vie prévue > 2 semaines

Ne pas utiliser (écrire directement du code, ne pas utiliser cette compétence) :

Scripts ponctuels / prototypes / POC / code de recherche exploratoire
Petits outils mono-fichier (interfaces < 5, pas de besoin d'artefacts multiples)
L'utilisateur dit explicitement « écris directement », « fais vite »

Commandes par phases (mode d'interaction principal de la compétence) :

Commande	Phase	Action	Résultat
`/sddl:init`	Initialisation	Créer la structure de répertoires, lire le code/les besoins existants	Squelette `sddl/` + `state.yaml`
`/sddl:interview`	Formation	Entretien des besoins par couches (L0-L2 obligatoires)	Énoncé des besoins
`/sddl:spec`	Formation	Générer une ébauche de spec L1-L5 + marquer les points de décision	`specs/<domaine>/spec.yaml`
`/sddl:confirm`	Formation	Résumé des décisions, clarification et confirmation	`decisions/<domaine>-confirmation.yaml`
`/sddl:freeze`	Formation	Contrôle SQC + gel	`spec_status: frozen`
`/sddl:derive`	Dérivation	Dériver des tests/code/docs à partir de la spec	`src/ tests/ docs/`
`/sddl:verify`	Dérivation	Vérifications C1-C4 + jugement de convergence	`checks/*.json` + convergence / routage
`/sddl:archive`	Archivage	Archiver les modifications, fusionner la spec	Mise à jour `specs/` + CHANGELOG

Principes Fondamentaux

La spec est une oracle, mais elle peut être remise en question : les défauts découverts dans la spec lors de la dérivation → dégel → retour à la boucle de formation pour révision → nouveau gel (passer par le contrôle qualité complet, ne pas contourner)
La déterminisme prime : toujours préférer l'analyse statique / le schéma / l'exécution des tests aux suppositions du LLM
La convergence est un système d'ingénierie : passerelles de conditions dures + taux de consensus pour les conditions souples + contraintes budgétaires + recours humain
Les points de décision ne sont pas silencieux : en cas d'ambiguïté, l'IA propose une valeur par défaut + marque le point de décision, l'utilisateur confirme avant de geler
La progression est le répertoire : une phase terminée = un fichier existe (Convention over Config), la reprise après interruption est gratuite

Le Répertoire Comme État (Convention over Config)

Pas besoin de lire un fichier d'état, on connaît la progression rien qu'en regardant les dossiers. C'est le mécanisme de visibilité de la progression de cette compétence (avec les commits git comme points de contrôle).

<projet>/
├── sddl/
│   ├── specs/                    # existe = entretien terminé, spec générée
│   │   └── <domaine>/spec.yaml    # status: frozen = gel terminé
│   ├── changes/                  # propositions de modification (développement incrémental, peut être parallélisé)
│   ├── decisions/                # enregistrement des confirmations de décision
│   │   └── <domaine>-confirmation.yaml
│   ├── checks/                   # archive des rapports de vérification (JSON lisible par machine)
│   │   ├── sqc-<domaine>-v1.json
│   │   └── c1-c4-<domaine>-v1.json
│   └── state.yaml                # seul méta-donnée : pointeur de phase + budget + dernière vérification
├── src/                          # apparaît après la boucle de dérivation
├── tests/                        # apparaît après la boucle de dérivation
├── docs/                         # apparaît après la boucle de dérivation (avec partitions current/planned)
└── (commit git à chaque fin de phase)

state.yaml minimal (stocke seulement le pointeur, pas les détails de progression) :

spec_status: frozen          # interviewing | drafting | reviewing | frozen | evolved
current_phase: derivation    # formation | derivation | complete
budget: { formation: 40%, implementation: 12%, revision: 100% }
last_check: { type: sqc, spec: auth-v0.1.0, result: pass, at: 2026-08-06T16:00 }

Règle de reprise : lorsque la compétence est rechargée, elle scanne le répertoire – pas de specs/ = commencer par interview ; specs/ présent mais pas decisions/ = commencer par confirm ; decisions/ présent mais spec non gelée = commencer par freeze ; src/ présent mais pas checks/ = commencer par derive ; checks/ présent = commencer par verify.

Phase terminée = commit git (assisté par l'E) : après chaque commande réussie, commit (feat(sddl): interview complete), garantissant la traçabilité.

Orchestration de la Double Boucle

Boucle de Formation (faire la bonne chose) – 5 commandes

/sddl:interview → /ddl:spec → /ddl:confirm → /ddl:freeze
     │              │              │              │
     └─ Révision ──┴──────┴──────┘
       (Échec SQC / changement de décision utilisateur → retour à l'étape précédente, max 5 tours)

Commande	Action clé	Point de contrôle
interview	Questions par couches L0-L2 (≤10 questions obligatoires), produire un énoncé des besoins	Énoncé complet
spec	Générer la spec L1-L5 + marquer les points de décision (DP pour les ambiguïtés)	SQC-def squelette valide
confirm	Résumé des décisions → clarification point par point (avec saisie personnalisée)	Aucun DP en attente
freeze	Contrôle SQC complet + signature du registre de confirmation	Pas de bloquant SQC + frozen

Boucle de Dérivation (bien faire les choses) – 3 commandes

/sddl:derive → /ddl:verify → (convergence) → terminé
     │              │
     └─ Routage ───┘
       (violation → regénérer code/tests/docs ou dégeler et retourner à la boucle de formation)

Commande	Action clé	Point de contrôle
derive	Dériver tests/code/docs à partir de la spec	Artefacts exécutables
verify	Vérifications C1-C4 par couches + jugement de convergence	Passerelles dures + consensus souple + couverture must
archive	Archiver les modifications, fusionner la spec	CHANGELOG + mise à jour spec

Scripts de Vérification (scripts/) – Preuves Déterministes, Pas de Jugement Sémantique

Les scripts ne produisent que des preuves déterministes (vérification de type / exécution de tests / table des symboles / YAML), l'évaluation sémantique est assurée par la capacité LLM de l'agent :

# Vérification déterministe SQC (passerelle de la boucle de formation) – le script donne les faits
python3 scripts/check_sqc.py sddl/specs/<domaine>/spec.yaml --verbose

# Vérification déterministe C1-C4 (passerelle de la boucle de dérivation) – le script donne les faits
python3 scripts/check_c1_c4.py . --verbose

# Récupération d'état (après interruption) – scanne le répertoire, affiche la progression + commande suivante
python3 scripts/sddl_status.py .

Code de sortie : 0 = succès/convergence, 1 = échec (peut être utilisé dans CI)
Sortie --json : preuves lisibles par machine (pour la révision LLM)

Principe de répartition (important) :

Couche	Responsable
Preuve déterministe (condition dure) : schéma valide / interface existe / test passé / table des symboles	Script
Révision sémantique (condition souple) : couverture du comportement / THEN peut être asserté / vrai couverture de test / authenticité de la documentation	LLM de l'agent (voir `references/llm-review.md`)

Ne pas utiliser l'heuristique pour les jugements sémantiques – la correspondance de chaîne de caractères provoquerait une explosion de faux négatifs (T1 a mesuré C1-sem à 0.48). Le script est un collecteur de preuves, l'agent est le juge.

Quand Lire Quelle Référence

Chargement à la demande, pas tout en une fois (divulgation progressive) :

Scénario	Lire
Exécuter `interview`	`references/formation-loop.md` (étape 1)
Générer la spec	`references/spec-schema.md` + `templates/spec-template.yaml`
Contrôle SQC	`references/sqc-checklist.md` (def avec script, sem avec LLM)
Confirmation des décisions	`templates/decision-summary.md`
Dériver des artefacts	`references/derivation-loop.md` (étapes 1-2)
Vérifications C1-C4	`references/checker-matrix.md` (def avec script, sem avec LLM)
Révision sémantique	`references/llm-review.md` (clé : comment le LLM fait la révision)
Routage / réécriture / budget	`references/derivation-loop.md` (étapes 3-5)
Proposition de modification	`references/formation-loop.md` (gestion des changements)

Budget et Dégradation

Trois budgets : formation (2M tokens / 5 tours) / implémentation (15M / 4 sessions) / révision (5M, L2 coûte 10%, L3 coûte 25%, premier L3 gratuit)
Budget enregistré dans state.yaml, mis à jour à chaque commande
Budget épuisé → passer en mode piloté par l'humain, pas de dégradation automatique (la qualité de la spec est la fondation)
Chemins de dégradation : D1 dégradation sémantique → D2 déplacer should/could dans la liste des risques → D3 réduire la variance → D4 diviser la spec → D5 livrer au mieux

Règles d'Expérience (Important)

Commandes par phases : ne jamais exécuter toute la double boucle dans une seule réponse – chaque commande est une unité d'interaction indépendante avec son point de contrôle
Points de décision avec clarify, saisie personnalisée explicitement visible : un clarify par point de décision, avec explication de l'impact ; ≤3 choix métier, la 4e place est fixée pour « Autre (saisie libre) » (testé : clarify n'a pas d'Autre automatique, choix max 4, doit être explicitement réservé) ; le texte de la question invite à « Pour d'autres valeurs, choisissez saisie libre » ; la valeur personnalisée de l'utilisateur suit un protocole de capture (enregistrer valeur+raison → synchroniser spec → marquer modified dans l'enregistrement de confirmation) ; les points de décision ouverts utilisent directement un clarify sans choix
Visibilité de la progression : au début et à la fin de chaque commande, indiquer la phase actuelle + la prochaine étape
Écriture d'état : à la fin de chaque commande, écrire state.yaml + git commit
Rapports de vérification : chaque vérification (SQC/C1-C4) écrit checks/*.json, avec un résumé lisible + des détails lisibles par machine

Pièges Courants

Sauter la boucle de formation pour aller directement à la dérivation – écrire du code sans spec gelée = revenir à la programmation conversationnelle. /sddl:freeze est une frontière dure, pas de dérivation sans gel.
Décision silencieuse – ne pas marquer un point de décision en cas d'ambiguïté et écrire directement la valeur par défaut = distorsion de l'intention de l'utilisateur. Tout « choix à la place de l'utilisateur » doit être enregistré comme DP.
Boucle d'auto-validation – faire confiance aux étiquettes collées par l'IA. C1-def doit faire une rétro-ingénierie de structure (analyser l'AST des tests), ne pas se fier aux étiquettes.
Score absolu de vérification sémantique – un score LLM de 0-100 n'est pas fiable. Utiliser une checklist binaire + un taux de consensus par vote (comptage objectif).
Contournement du contrôle qualité lors de la réécriture – corriger directement la spec suite à un spec_error = relâcher ses propres standards. Doit dégeler → retourner à la boucle de formation → regeler.
Gonflement du fichier d'état – écrire tous les détails de progression dans state.yaml = revenir au « mensonge documentaire ». state.yaml ne stocke que le pointeur, les détails sont dans les fichiers eux-mêmes.
Budget non enregistré – ne pas mettre à jour le budget dans state.yaml = perte de contrôle des coûts. Mettre à jour à la fin de chaque commande.
Vérification sémantique avec correspondance grossière de chaînes – mesuré sur T1 : la correspondance de mots-clés a fait chuter C1-sem à 0.48 (explosion de faux négatifs). Prioriser le vote LLM avec checklist ; l'heuristique uniquement comme fallback, et doit être sémantique (extraction d'AST + mots-clés structurés). Les résultats du premier tour ne sont pas fiables, nécessitent une relecture humaine.
Fuites d'état partagé entre tests – mesuré sur T1 : le store en mémoire partagé entre tests a provoqué des échecs d'assertion. Lors de la dérivation, ajouter un fixture d'isolation (autouse reset) ; les assertions des tests passent par l'interface publique, n'accèdent pas directement au _store interne.
Fonctions de requête pure avec effets de bord – mesuré sur T1 : detectDiscrepancy modifie le status en interne, violant la spec B006 (devrait rester draft). Les interfaces de requête pure (retourner un rapport/une requête) ne doivent pas modifier l'état. C2-sem doit le vérifier.

Liste de Vérification

Recettes One-Shot

Nouveau projet à partir de zéro

/sddl:init → /ddl:interview → /ddl:spec → /ddl:confirm → /ddl:freeze
           → /ddl:derive → /ddl:verify → /ddl:archive

Re-spécification d'un projet existant (projet de migration)

/sddl:init (lire le code existant) → /ddl:spec (extraction inverse de l'état actuel + marquer les décisions)
  → /ddl:confirm → /ddl:freeze → /ddl:verify (vérifier la cohérence spec↔code)

Développement incrémental de fonctionnalité (spec déjà gelée)

/sddl:init → écrire la proposition changes/<nom>/ → /ddl:confirm (points de décision impactés)
  → /ddl:freeze → /ddl:derive → /ddl:verify → /ddl:archive

Compétences Associées

writing-plans : écrire des plans d'implémentation (les changes/tasks.md de SDDL peuvent l'utiliser)
test-driven-development : TDD est un moyen de vérification pour SDDL (exécution de test C3)
hermes-agent-skill-authoring : les normes de création de cette compétence elle-même

xt-mahh/sddl

Qu'est-ce que sddl ?

Demander à votre IA préférée

Documentation