Développement piloté par les spécifications (SDD)

1. Vue d'ensemble du concept et problème systémique

L'erreur la plus courante des développeurs débutants en vibe coding est l'approche « Prompt-and-Pray » (rédiger une requête vague dans le chat et espérer que le modèle devine l'architecture). Lorsque la demande ressemble à « Implémente la facturation Stripe pour les abonnés », le modèle choisit arbitrairement des schémas de base de données, utilise des bibliothèques obsolètes, ignore les webhooks, néglige l'idempotence et ne prend pas en compte les cas limites liés aux annulations de paiement. Lorsqu'un ingénieur demande de corriger un bug, le modèle commence à bricoler frénétiquement, transformant définitivement la base de code en spaghetti code (AI Slop).

Le Spec-Driven Development (SDD, développement piloté par spécifications) est une discipline d'ingénierie qui sépare la phase de conception système de la phase de génération de code. Avant toute modification de la base de code, un document de spécification formalisé (spec.md ou RFC.md) est créé. Ce document devient la source unique de vérité (Single Source of Truth) et le contrat contre lequel l'agent exécute et vérifie chaque étape suivante.

2. Taxonomie architecturale et modèle mental

La structure architecturale du SDD repose sur une hiérarchie claire des artefacts de conception :

┌─────────────────────────────────────────────────────────────┐
│             HIÉRARCHIE DES ARTÉFACTS DE DÉVELOPPEMENT       │
│             POUSSÉ PAR LES SPÉCIFICATIONS                   │
├─────────────────────────────────────────────────────────────┤
│ 1. Contexte produit : Problème utilisateur et objectif      │
│    métier                                                 │
├─────────────────────────────────────────────────────────────┤
│ 2. Contrats techniques :                                  │
│    • Schémas de données (Schémas Drizzle / Prisma, DDL SQL)│
│    • Contrats API (Schémas Zod, OpenAPI, types TypeScript)│
│    • Invariants & Règles de sécurité (Idempotence, RBAC,   │
│      Auth)                                                │
├─────────────────────────────────────────────────────────────┤
│ 3. Liste de tâches atomiques (DAG) :                      │
│    • Étape 1 ➔ Étape 2 ➔ Étape 3 (Ordre strict des        │
│      dépendances)                                         │
├─────────────────────────────────────────────────────────────┤
│ 4. Prédicats de vérification : Critères d'achèvement      │
│    automatisés                                            │
└─────────────────────────────────────────────────────────────┘

1. Contrats techniques (Interface-First) :
   • Description des interactions entre systèmes avant même l'implémentation de la logique interne. Les structures de requêtes/réponses, les schémas de validation et les états d'erreur sont définis.
2. Graphe atomique des tâches (Task Decomposition DAG) :
   • La tâche est décomposée en une séquence de sous-tâches petites et indépendamment vérifiables. Chaque sous-tâche ne doit modifier qu'entre 1 et 3 fichiers.
3. Critères vérifiables par machine (Acceptance Predicates) :
   • Au lieu d'un subjectif « vérifiez que tout fonctionne », la spécification contient des commandes de vérification concrètes : « pnpm test auth.test.ts passe avec succès, couverture de branches > 90 % ».
4. Tracker de statut du cycle de vie (Lifecycle Tracker) :
   • La spécification inclut des cases à cocher interactives ([ ] ➔ [x]), que l'agent met à jour après l'exécution et la vérification de chaque étape.

3. Pipeline technique et mécanique interne

Le cycle de vie du développement selon la méthodologie SDD :

1. Entretien et synthèse de la spécification (Interview Phase) : L'ingénieur formule la tâche. Le modèle pose des questions de clarification sur les détails non triviaux : quel comportement attendre en cas de coupure réseau, comment gérer les doublons, quelles limites appliquer au rate-limiting.
2. Ancrage de la spécification dans le dépôt : Un artefact est créé (par exemple, .specs/004-billing-integration.md) et ajouté au système de contrôle de version Git.
3. Audit humain et approbation (Spec Approval) : L'ingénieur relit les schémas de données et les contrats proposés. Si une décision architecturale présente des défauts, ils sont corrigés au niveau du texte de la spécification en 2 minutes, évitant ainsi des heures de réécriture de code.
4. Délégation progressive à l'agent (Step-by-Step Execution) : L'agent est invoqué pour implémenter une étape spécifique de la spécification :
   • L'agent lit le contexte de la spécification.
   • Il écrit les tests conformément aux contrats (TDD).
   • Il implémente la fonctionnalité.
   • Il lance les tests et valide l'accomplissement de la sous-tâche.
5. Vérification finale et archivage : Une fois tous les points de la spécification cochés comme réalisés, un audit complet est effectué, et la spécification reste dans le dépôt comme documentation vivante de la fonctionnalité.

4. Scénarios d'ingénierie pratiques en production

01. Développement d'un module de paiement critique avec idempotence

Avant d'écrire le code d'intégration de la passerelle de paiement, l'ingénieur crée une spécification :

• Il fixe la structure de la table idempotency_keys avec les champs key, response_payload, status, expires_at.
• Il décrit l'algorithme exact de comportement lors de la réception d'un webhook dupliqué avec un transaction_id similaire.
• L'agent implémente le module strictement selon la spécification ; aucun cas limite n'est perdu.

02. Travail parallèle des agents backend et frontend

L'équipe développe un nouveau tableau de bord analytique :

• D'abord, les schémas Zod et les interfaces TypeScript pour tous les graphiques et métriques sont décrits dans la spécification.
• L'agent frontend utilise ces schémas pour intégrer les composants avec des données mockées.
• L'agent backend implémente simultanément les vraies requêtes SQL et les routes API sous le même contrat.
• L'intégration se déroule sans aucun conflit d'incompatibilité de types.

03. Migration sécurisée et massive d'un module legacy

Remplacement d'une authentification maison ancienne par Better Auth :

• La spécification décrit la préservation de la compatibilité ascendante des sessions dans Redis et un plan de migration étape par étape des hachages de mots de passe de bcrypt vers Argon2id.
• L'agent décompose la migration en 7 étapes isolées, chacune étant testée individuellement.

5. Pièges, erreurs typiques et sécurité

• Paralysie due au sur-dimensionnement (Over-Engineering Paralysis) : Rédiger une spécification de 20 pages pour une correction mineure d'indentation ou un changement de couleur de bouton est une perte de temps absurde. Appliquez le SDD aux tâches touchant plus de 2 modules ou contenant une logique métier critique.
• Désynchronisation du code et de la spécification (Spec Rot) : Si, durant le développement, il s'avère nécessaire de modifier un schéma, les ingénieurs corrigent souvent le code directement, oubliant de mettre à jour spec.md. Cela induit en erreur les agents suivants, qui reliront une spécification obsolète.
• Utilisation de formulations vagues : Des phrases telles que « le système doit être rapide » ou « assurer la fiabilité » sont catastrophiques pour l'IA. La spécification doit opérer avec des valeurs concrètes : « temps de réponse p99 < 150 ms », « retourner HTTP 429 si dépassement de 100 rpm ».
• Ignorance du versioning des spécifications : Les fichiers de spécification doivent faire partie du dépôt Git aux côtés du code, permettant de suivre l'évolution des décisions architecturales via l'historique des commits.