Étape 3 du cycle · /sdd spec

SPEC — la spécification vivante

La SPEC fait le pont entre l'intention métier et l'implémentation concrète par les agents IA. C'est l'instruction de travail de l'agent pour une fonctionnalité donnée — et l'investissement au meilleur ROI du framework : une SPEC de qualité permet à un agent de générer plus de 80 % du code correct du premier coup.

Spec as Living Invariant

Le premier principe fondateur du SDD Mode positionne la SPEC comme un invariant vivant : elle n'est pas un document de passage, elle reste la source de vérité entre l'intention humaine et le code agent — avant, pendant et après l'implémentation. Trois postures existent dans l'écosystème spec-driven :

L'argument n'est pas que documentaire : une session ancrée sur une SPEC consomme en moyenne 41,7 % de tokens en moins qu'une session sans spécification (R2Code, arXiv 2026). La SPEC est un point d'ancrage stable contre le context rot.

Les sections d'une SPEC

Une SPEC AIAD est normalisée. Elle contient douze sections de base :

1. le scope d'activation — injectée seule (par défaut) ou combinée avec d'autres SPECs (fonctionnalités transverses) ;
2. le contexte — référence à l'Intent Statement parent, objectif, outcome attendu ;
3. le périmètre — in scope et out of scope explicites ;
4. les fichiers impactés — à créer ou à modifier, liste exhaustive ;
5. l'interface technique — endpoints, types, schémas de base de données ;
6. le comportement détaillé — flow nominal et cas limites (au moins 3 edge cases explicites) ;
7. les règles de validation — avec schémas ;
8. les règles métier à appliquer ;
9. les tests attendus — scénarios à implémenter ;
10. les exemples d'usage — concrets, requête/réponse ;
11. la Definition of Done (DoOD) — les critères de « Done » ;
12. le Critère de Drift — la règle concrète pour détecter que la SPEC est devenue obsolète.

**Critère de Drift** : cette SPEC est en drift si le fichier
`auth/validator.ts` est modifié sans mise à jour de la section
Interface Technique.

Deux sections pour encadrer l'agent (doctrine v1.9)

La doctrine v1.9 ajoute deux sections, désignées par leur libellé. Elles traduisent dans la SPEC ce que l'humain délègue réellement à l'agent — voir Autonomie de l'agent.

Une SPEC ne doit pas s'alourdir d'un champ rempli par rituel : hors des cas prévus, la section « Périmètre d'exécution de l'agent » tient en deux mots. Le mode de permission du harness n'y figure pas comme mesure de confinement — un mode de permission n'est pas un contrôle.

Les quatre critères de qualité

Ces quatre critères alimentent directement le Spec Quality Score évalué à /sdd gate. Une SPEC qui ne les satisfait pas ne doit jamais être soumise à un agent. Au-delà de 200 lignes, la SPEC est trop grande : direction /sdd split.

La variante EARS (v1.11) — l'option anti-ambiguïté

Depuis la v1.11, les critères d'acceptation peuvent être rédigés au format EARS (Easy Approach to Requirements Syntax) via /sdd spec --ears. La SPEC est alors basée sur le template .aiad/specs/spec-ears-template.md et déclare Format : EARS en entête — c'est ce signal qui active le linter strict ears-validator à la Gate. Chaque critère suit l'un des cinq patterns :

Ubiquitous          The <system> SHALL <response>.
Event-driven        WHEN <trigger>, the <system> SHALL <response>.
State-driven        WHILE <state>, the <system> SHALL <response>.
Optional feature    WHERE <feature>, the <system> SHALL <response>.
Unwanted behaviour  IF <condition>, THEN the <system> SHALL <response>.

Le linter applique les règles R1–R7 : mots interdits (should, might, fast, user-friendly, intuitive…), un seul SHALL par critère, déclencheur explicite (WHEN/WHILE/IF/WHERE), sujet explicite, verbe observable (return, log, reject — jamais understand), quantification chiffrée (« within 200ms p95 », pas « rapidement ») et absence de conjonctions composées.

EARS reste optionnel : les formats prose et EARS cohabitent, aucune migration n'est imposée. À réserver aux SPECs où l'ambiguïté coûterait cher : sécurité, paiement, conformité réglementaire, contrats d'API publics. En contrepartie : environ +30 % de verbosité et une courbe d'apprentissage.

Option REASONS Canvas (SPDD)

Quand l'Intent parent est complexe ou ambigu, /sdd spec propose le REASONS Canvas — l'outil SPDD de Kevlin Henney — comme étape de cadrage : il structure la justification de l'intention avant de basculer au format de SPEC AIAD standard. Les deux approches sont compatibles : le Canvas enrichit le POURQUOI, il ne remplace pas le format de SPEC.

Découper avec /sdd split

Quand la Gate échoue sur l'atomicité, que la SPEC dépasse 200 lignes, que l'agent exige plus de deux relances ou que le budget de contexte explose, on découpe. Trois patterns guident le découpage :

Chaque sous-SPEC doit pouvoir passer la Gate indépendamment, et la somme des sous-SPECs couvre 100 % de la parente. Quand plusieurs SPECs sortent du découpage, /sdd spec produit un plan de parallélisme (waves et graphe de dépendances) validé par le PE avant la rédaction.