Spec-driven development : pourquoi on écrit la spec avant de lâcher Claude Code

J'ai passé six mois à faire du vibe coding avec Claude Code. Le résultat : du code livré vite, des PRs ouvertes en 20 minutes, et une dette technique qui s'accumule sprint après sprint. Le jour où j'ai commencé à écrire des specs avant de lancer l'agent, le nombre d'allers-retours a chuté de plus de la moitié. Ce n'est pas une intuition, c'est un constat mesuré sur 12 projets en production.

Le spec-driven development n'est pas un concept nouveau. Mais appliqué aux agents IA, il creuse un fossé entre un prototype qui tient avec du scotch et un livrable que votre équipe peut maintenir.

Le vibe coding a un plafond, et on l'atteint vite

Le vibe coding fonctionne tant que le périmètre reste petit. Vous décrivez ce que vous voulez en langage naturel, l'agent génère du code, vous itérez. Sur un script de 200 lignes ou un composant React isolé, c'est efficace.

Pourquoi le vibe coding casse en production ?

Le problème apparaît dès que le contexte dépasse ce que l'agent peut absorber en une seule passe. Sur un projet Next.js avec 50+ composants, une base Supabase, des edge functions et un pipeline CI, l'agent fait des choix architecturaux implicites à chaque prompt. Il nomme les fichiers comme il veut. Il crée des abstractions que personne n'a demandées. Il duplique du code parce qu'il n'a pas exploré le répertoire utils/.

J'ai documenté ce phénomène sur 12 projets en production avec Claude Code : quand l'agent n'a pas de spec, il produit du code fonctionnel mais structurellement incohérent avec le reste du projet. Le résultat, c'est que le review prend plus de temps que le développement lui-même, comme on le détaille dans notre retour sur le goulot d'étranglement du review de PRs générées par agents.

Selon le guide publié par GitHub sur le spec-driven development, le problème fondamental est qu'on traite les agents comme des moteurs de recherche alors qu'il faudrait les traiter comme des pair programmers littéraux. Ils excellent en pattern matching, mais ils ont besoin d'instructions non ambiguës.

Le vibe coding est un accélérateur de POC, pas une méthode de production.

Ce que le spec-driven development change concrètement

Le spec-driven development (SDD) inverse la hiérarchie : la spécification devient l'artefact principal, le code devient un output dérivé. L'humain passe de "dans la boucle" (il écrit le code avec l'agent) à "sur la boucle" (il conçoit le système que l'agent exécute).

C'est quoi le spec-driven development ?

C'est une méthodologie en 4 phases, formalisée par plusieurs outils open-source depuis fin 2025 :

1. Constitution : on rassemble le contexte projet (CLAUDE.md, ARCHITECTURE.md, conventions, décisions passées).
2. Spécification : on décrit les requirements fonctionnels, les edge cases, les critères d'acceptation, et surtout ce qu'on ne veut PAS (les "non-goals").
3. Plan : l'agent explore le codebase en lecture seule, pose des questions, et propose un plan d'implémentation que l'humain valide.
4. Tâches : le plan est découpé en tâches unitaires, chacune avec ses critères de validation. L'agent les exécute une par une, teste, commite, documente.

D'après le framework documenté par Panaversity sur le SDD avec Claude Code, chaque itération bénéficie des apprentissages des itérations précédentes via les fichiers agents MD. C'est un cycle qui s'améliore au fil du temps, à condition que la spec de départ soit solide.

C'est quoi GitHub Spec Kit ?

GitHub a open-sourcé Spec Kit fin 2025. Le projet propose un cadre structuré compatible avec GitHub Copilot, Claude Code et Gemini CLI. Sur GitHub, le dépôt claude-code-spec-workflow de Pimzino cumule plus de 3 800 stars mi-2026, et cc-sdd de Gotalab dépasse les 3 500 stars avec 17 skills installables sur 8 agents différents.

L'écosystème a explosé en quelques mois. On est passé de "personne ne fait ça" à plus de 30 intégrations d'agents compatibles avec un workflow spec-first.

Ce qui distingue Spec Kit des approches artisanales, c'est le découplage strict entre les phases. Vous ne passez à l'implémentation que quand la spec est validée. Vous ne validez la spec que quand les edge cases sont couverts. Chaque checkpoint est un portail, pas une suggestion.

Comment écrire une spec que Claude Code exécute sans dériver

La qualité de la spec détermine tout. Une spec floue produit du code flou. Une spec précise produit du code prévisible. J'ai testé les deux approches sur des projets clients et la corrélation est directe.

Comment écrire une spec pour Claude Code ?

Une bonne spec pour Claude Code contient cinq blocs :

Les requirements fonctionnels : pas "faire un formulaire de login", mais "un formulaire avec email + mot de passe, validation côté client via Zod, soumission via server action Next.js 15, redirect vers /dashboard après succès, affichage inline des erreurs API".

Les non-goals : ce que l'agent ne doit PAS toucher. "Pas d'authentification OAuth dans cette itération. Pas de page d'inscription. Pas de refactoring du layout existant." Sans cette section, Claude Code va créer des fichiers que personne n'a demandés.

Les critères d'acceptation : des conditions binaires (pass/fail) que l'agent peut vérifier. "Le formulaire soumet sans erreur TypeScript. Le test Playwright passe sur le happy path. Le build Next.js compile sans warning."

Les contraintes techniques : "Utiliser le composant Button existant dans components/ui/. Suivre le pattern de naming du projet (camelCase pour les hooks, PascalCase pour les composants). Ne pas ajouter de dépendance npm."

Les edge cases : "Que se passe-t-il si l'API retourne un 429 ? Un 500 ? Si le champ email est pré-rempli par le navigateur ?"

Mon expérience sur l'intégration d'IA en projet sans dev senior confirme que les edge cases sont le bloc le plus souvent oublié, et celui qui génère le plus de bugs en production.

À quoi sert le plan mode de Claude Code ?

Le plan mode est la fonctionnalité native de Claude Code qui implémente la phase 3 du SDD. Quand vous l'activez, l'agent passe en mode lecture seule : il explore les fichiers, analyse l'architecture existante, et pose des questions avant de proposer un plan.

Concrètement, l'agent ne peut pas éditer de fichier en plan mode. Il ne peut que lire, chercher (via ripgrep), et réfléchir. Il vous soumet un plan structuré que vous validez, modifiez ou rejetez avant qu'il touche la moindre ligne de code.

C'est la différence entre un agent qui fonce tête baissée et un agent qui s'arrête pour comprendre le terrain. Sur un codebase de 50 000+ lignes, cette phase d'exploration évite les cas où l'agent réécrit un utilitaire qui existe déjà ou crée un pattern concurrent à celui du projet.

CLAUDE.md joue le rôle de source de vérité persistante. C'est le fichier que Claude Code lit automatiquement à chaque démarrage de session. J'y mets l'architecture du projet, les conventions, les décisions passées, et les pièges connus. Sans ce fichier, chaque nouvelle session repart de zéro.

Spec-driven vs vibe coding : le vrai écart en production

Pour trancher le débat, j'ai comparé les deux approches sur des projets similaires (SaaS Next.js + Supabase, entre 3 et 5 développeurs, durée 2 à 4 mois).

Quel est l'écart réel entre spec-driven et vibe coding ?

Le vibe coding démarre plus vite, mais le coût total par feature est plus élevé. Le temps "gagné" au démarrage est consommé en review, en corrections, et en refactoring post-merge.

Sur mes propres chiffres GSC pour ai-dev.team en juin 2026, l'article sur le vrai coût en tokens de Claude Code concentre 12 clics sur 13 au total, avec 366 impressions. Ce qui intéresse les devs, ce n'est pas la hype, c'est le retour terrain chiffré. Le spec-driven development entre dans cette catégorie : ce qui compte, c'est le delta mesurable sur la vélocité et la qualité.

Comme le montre alexop.dev dans son retour d'expérience, le SDD permet de traiter des refactors massifs (15+ fichiers touchés) en une seule journée, là où le vibe coding aurait nécessité plusieurs jours d'itérations.

Quand on fait tourner 10 agents Claude Code en parallèle, la spec devient encore plus critique. Sans elle, chaque agent part dans une direction différente et les conflits de merge explosent.

Pour qui le spec-first vaut le détour (et pour qui c'est overkill)

Le spec-driven development n'est pas adapté à tous les contextes. Je le recommande dans trois cas précis.

Ça vaut le coup pour une petite équipe ?

Oui, à une condition : que l'équipe ait au moins un dev senior capable d'écrire des specs claires. Le SDD ne simplifie pas le travail de conception, il le déplace en amont. Si personne dans l'équipe ne sait définir des critères d'acceptation ou identifier des edge cases, la spec sera aussi floue que le prompt.

Pour une équipe de 2-3 devs seniors qui utilisent Claude Code au quotidien, le spec-first est un multiplicateur. La spec sert de documentation vivante, de brief pour l'agent, et de checklist de review. Trois fonctions en un seul artefact.

Pour un développeur solo qui prototype, le vibe coding reste pertinent. Le coût de rédaction d'une spec formelle sur un script de 100 lignes ne se justifie pas. Le point de bascule se situe autour de 500 lignes de code ou 3 fichiers touchés : en dessous, le prompt suffit, au-dessus, la spec fait gagner du temps net.

Mon verdict : en production avec une équipe senior, le spec-driven development est la pratique qui a le plus réduit nos allers-retours avec Claude Code. Les développeurs offshore comme les devs locaux travaillent sur la même base (la spec), ce qui élimine les ambiguïtés culturelles et techniques. C'est d'ailleurs un point qu'on applique systématiquement sur les projets GoLive Software : la spec partagée aligne tout le monde avant la première ligne de code. Selon Forrester, les équipes qui formalisent leurs requirements en amont réduisent le coût de correction des défauts de 30 à 50% par rapport aux approches itératives non structurées.

Je ne reviendrai pas au vibe coding pour un projet de production. La spec prend 30 minutes à écrire, elle en fait gagner des heures sur le cycle complet. Si vous utilisez Claude Code, Cursor ou n'importe quel copilote sur un vrai projet, commencez par la spec. Pas par le prompt.

« La spec ne ralentit pas le développement, elle supprime le temps perdu en corrections, en review et en refactoring post-merge. »

Vincent Roye, juin 2026