Développement piloté par les spécifications avec Claude Code : un tutoriel guidé

Qu’est-ce que le développement piloté par les spécifications ?

Le développement piloté par les spécifications est un flux de travail bâti sur trois documents, dans cet ordre : un document qui décrit ce que doit faire un changement, un plan qui précise les étapes, puis du code écrit en suivant le plan, avec une relecture humaine entre chaque paire.

Les trois points de revue qu’une fonctionnalité franchit dans un développement piloté par les spécifications.

Une spécification est un court document, en langage simple et rédigé avant tout code, qui décrit ce que doit faire un changement. Prenez une fonctionnalité du type « permettre aux utilisateurs d’exporter leurs données ». Une spécification va verrouiller les réponses que l’agent devrait sinon deviner. Elle liste 

• Les formats de fichiers pris en charge
• Le mode de livraison
• Le comportement en cas d’export interrompu
• Les parties volontairement hors périmètre

Voici l’ouverture réelle d’une spécification que Claude Code a rédigée pour une modification workout-shape-verification dans l’une de mes applications de responsabilisation sur Telegram. Le changement remplace un seuil de fréquence cardiaque fragile par un contrôle de la forme de la courbe de FC dans le temps :

# Workout Shape-Based Verification — Design Spec
 
**Created:** 2026-05-05
**Status:** Draft
**Supersedes (partially):** [2026-03-17-calisthenics-verification-design.md]
  — replaces the absolute-HR thresholds for the Workout activity type.
  Run / Ride / Walk verification is unchanged.
 
## Problem
 
The current Workout verifier accepts an activity only if absolute heart-rate
levels clear fixed cutoffs: avg ≥ 120, max ≥ 140, range ≥ 30, suffer_score ≥ 3.
Two failures in production:
 
1. **False-negative risk.** As cardiovascular fitness improved
   (resting HR ~80), real calisthenics sessions with disciplined rest now
   average 115–125 bpm. Recent sessions have come within 4 bpm of the 120 floor.
 
<!-- ... continues for hundreds of lines through Solution, Risks,
 	Out of scope, and What is removed / added / changed / unchanged -->

Le plan est le document suivant. Il décompose la spécification en tâches numérotées que l’agent peut traiter une par une, chaque tâche indiquant un fichier, un changement, un ordre et un test. Là où la spécification répond au « quoi », le plan répond « par quelles étapes ».

Le code vient en dernier, écrit en suivant le plan, une tâche à la fois.

Trois documents. Une relecture humaine entre chaque paire. Vous relisez la spécification avant qu’elle ne devienne plan. Vous relisez le plan avant qu’il ne devienne code. Vous relisez le code avant la fusion.

En quoi le développement piloté par les spécifications diffère du mode Plan

Vous avez peut‑être utilisé le mode Plan intégré de Claude Code (appuyez deux fois sur Maj+Tab) et vous vous demandez ce qui change. Le mode Plan produit un plan dans un seul tour de chat. Le plan vit en mémoire, sans spécification persistée ni étape de revue entre les phases.

Le développement piloté par les spécifications persiste la spécification et le plan en fichiers sur disque. Chacun passe une revue humaine avant la phase suivante, et les artefacts survivent entre les sessions. Le mode Plan compresse deux phases du développement logiciel en un seul échange. Cela marche pour les petites tâches et échoue dès que la base de code grossit et sert de vrais utilisateurs.

Pourquoi le « vibe-coding » atteint vite ses limites

Le vibe-coding convient aux prototypes, aux fichiers uniques et aux scripts jetables. Il se dégrade sur des applications réelles avec des utilisateurs à servir et sur des bases de code conséquentes. Le seuil pertinent se situe autour de 4 fichiers. Toute modification touchant autant de fichiers a besoin d’une spécification, tout comme un refactoring avec un état final clair, ou toute tâche où la difficulté porte sur « qu’est‑ce que cela doit faire exactement ? »

La cause de l’échec est claire. Une consigne vague comme « ajouter le partage de photos à mon app » pousse le modèle à deviner des milliers d’exigences implicites.

Prenez une seule de ces exigences : les préférences de notification. Le chef de produit imagine des interrupteurs par canal. Le back‑end implémente un on/off global. Le front suppose une intégration au niveau du système d’exploitation. Quatre lectures raisonnables de trois mots, quatre produits différents.

Chaque étape de revue dans le développement piloté par les spécifications intercepte une classe d’erreurs avant qu’elles ne coûtent cher. La revue de spécification repère l’inflation de périmètre et les mauvais diagnostics racine. La revue de plan détecte les implémentations inachevées et les motifs contradictoires. La revue de code rattrape les plans séduisants sur le papier mais qui cassent au premier test.

Le retour sur investissement est réel et s’accumule progressivement. La phase de spécification coûte quelques heures d’écriture avant toute exécution, et les premières fonctionnalités semblent plus lentes que le vibe-coding. Mon point d’équilibre est arrivé vers la quatrième ou cinquième fonctionnalité. À ce moment‑là, les spécifications captaient des erreurs de conception que j’aurais sinon livrées puis réécrites une semaine plus tard.

Les trois sections suivantes présentent trois approches open source pour faire tourner ce flux dans Claude Code, de la plus légère à la plus exigeante en structure.

Superpowers

Superpowers est la plus légère des trois. C’est celle que j’utilise au quotidien, et que nous détaillerons le plus.

Qu’est‑ce que Superpowers ?

Superpowers est un plugin Claude Code de Jesse Vincent (obra/superpowers, licence MIT), avec environ 194 k étoiles sur GitHub. 

Il fournit un ensemble de skills. Une skill Claude, dans Claude Code, est un fichier d’instructions nommé que l’agent charge à la demande pour suivre un flux de travail précis. Superpowers propose des skills qui maintiennent Claude Code dans la boucle pilotée par les spécifications plutôt que de le laisser sauter directement au code.

La page du projet Superpowers sur GitHub.

Comment installer Superpowers

Installez‑le via la marketplace officielle des plugins de Claude Code :

/plugin install superpowers@claude-plugins-official

Un hook SessionStart charge automatiquement la skill using-superpowers, donc le flux de travail est actif dès que vous commencez à taper. (Les hooks Claude Code sont des scripts exécutés par l’agent à des moments précis du cycle de vie.) Rien à câbler par projet.

Le flux de travail Superpowers

Ensuite, quatre skills pilotent votre travail au quotidien :

Un sous‑agent est une instance séparée de Claude Code, déclenchée par le parent pour un travail ciblé dans sa propre fenêtre de contexte. Les sous‑agents relecteurs ci‑dessus lisent le code « à froid », sans le cadrage du parent.

Comment utiliser Superpowers

Vous invoquez les quatre skills en décrivant simplement ce que vous voulez. La skill de brainstorming comprend « discutons de cette nouvelle fonctionnalité » et lance d’elle‑même la conversation de spécification. Les autres se déclenchent de la même façon.

Les quatre skills Superpowers dans l’ordre, avec deux points de revue humaine entre brainstorming et writing-plans.

La démonstration ci‑dessous reprend la même fonctionnalité workout-shape-verification que dans l’extrait de spécification ci‑dessus.

Étape 1 : du brainstorming à la spécification

J’ouvre Claude Code et je tape :

Let's discuss a new feature. The Workout verifier in make-me-work uses absolute heart-rate cutoffs and is now misfiring as my resting HR drops. I want to replace the absolute cutoffs with a check on the shape of the HR curve over the session.

La skill brainstorming prend la main et pose une dizaine de questions, parmi lesquelles :

• Ce qui définit la bonne « forme »
• Quelles données combiner
• Que faire des séances qui ont la bonne forme mais échouent un ancien seuil
• Si le changement doit aussi s’appliquer à Run et Ride

Deux points de revue humaine se situent ici. Le premier est la revue de conception, où je confirme que mes réponses correspondent à mon intention. Le second est la revue de spécification : je lis le fichier rédigé par Claude et je l’approuve avant tout travail de plan.

Étape 2 : de la spécification au plan

Je lance la skill writing-plans. Elle lit la spécification approuvée et produit un plan avec quatre parties :

• Une définition de « Fini »
• Une cartographie des fichiers impactés
• Un parcours utilisateur sur le chemin de démo
• Une liste de tâches numérotées en sous‑étapes cochables. 

Je relis le plan, je challenge les tâches mal ordonnées ou trop grossières, puis j’approuve.

Étape 3 : du plan au code

Je lance subagent-driven-development. À partir d’ici, la boucle s’exécute sans moi. Pour chaque tâche du plan, la skill :

1. Écrit un test rouge
2. Écrit le code pour le faire passer
3. Refactore
4. Déclenche un sous‑agent de revue de code qui lit le diff à froid

Si la relecture signale un problème, la boucle le corrige avant de passer à la tâche suivante. Il n’y a pas de revue humaine dans cette étape. Les revues utiles ici sont les deux précédentes.

Étape 4 : revue de l’intégralité du diff

Une fois le plan terminé, je lance requesting-code-review. Un sous‑agent neuf lit tout le diff au regard de la spécification et du plan, puis publie une revue. Je prends les suggestions avant de fusionner.

Quand une tâche du plan révèle une contradiction avec la spécification, la boucle s’arrête et me consulte. Je peux modifier la spécification (ou laisser Claude le faire) et régénérer les tâches concernées. Autre option : corriger ponctuellement dans la tâche elle‑même. Superpowers ne contourne jamais silencieusement les erreurs de spécification.

De vraies spécifications et plans sur disque

Voici la spécification de la fonctionnalité workout-shape-verification, ouverte dans un éditeur :

Le fichier de spécification tel qu’il atterrit sur disque après la rédaction par la skill de brainstorming.

L’en‑tête comporte les champs Created, Status et Supersedes que la skill de brainstorming ajoute par défaut. Suit la section Problem. Rien de tout cela n’est du code. Le fichier se poursuit bien au‑delà de la capture, avec la solution proposée et les contraintes sur ce que le changement doit ou ne doit pas toucher.

Le plan correspondant s’ouvre sur son User Journey :

Le fichier de plan que la skill writing-plans produit à partir de la spécification approuvée.

Le parcours déroule le chemin de démonstration par blocs de cinq étapes, en précisant commandes, fichiers et arguments à chaque étape. Les tâches numérotées qui suivent traduisent chaque étape en sous‑étapes cochables que la skill subagent-driven-development peut exécuter.

Les deux documents se complètent ainsi :

Spécification et plan côte à côte. La spécification répond à « quoi et pourquoi ». Le plan répond « par quelles étapes ».

Pour des spécifications et plans plus volumineux, j’ajoute une étape que la boucle officielle n’a pas : un passage « red‑team ». Avant de valider, je fais lire la spécification à un ou plusieurs sous‑agents Opus à froid, en cherchant les angles morts. C’est une habitude personnelle, pas une fonctionnalité de Superpowers. Elle m’a évité assez d’hypothèses hasardeuses pour que je la conserve.

Quand Superpowers n’est pas le bon choix

Superpowers convient au travail en solo sur un dépôt unique. Il fonctionne au mieux quand l’ensemble de la base de code tient dans une session Claude Code, et que vous lirez vraiment une spécification de 2 pages. La comparaison détaillée se trouve dans Comment choisir entre eux plus bas. En bref : Superpowers peine avec les fonctionnalités multi‑dépôts et le travail qui exige une séparation claire des rôles.

Un développeur a mis en lumière un quatrième écueil dans une plainte publique sur le plugin : « Même la plus petite tâche prend une éternité, avec Claude qui lance des sous‑agents et rédige des plans complètement disproportionnés. Changer un peu de CSS prend désormais une éternité. »

La solution est de sauter Superpowers pour les micro‑changements. Les skills ne s’activent que sur le déclencheur de brainstorming. Une modification CSS d’une ligne peut passer par Claude Code sans jamais invoquer la boucle de spécification. Le vrai piège ici, c’est de sur‑appliquer le flux à un travail qui n’a pas besoin de spécification.

GitHub Spec Kit

Spec Kit est le bon choix quand la spécification doit survivre à n’importe quelle session Claude Code et être lue par des personnes qui n’ouvriront jamais Claude Code.

Qu’est‑ce que le GitHub spec‑kit ?

Spec Kit est un projet GitHub (github/spec-kit, licence MIT), maintenu par GitHub lui‑même, avec plus de 100 k étoiles. Il fournit un CLI ainsi qu’un flux qui fonctionne de la même manière avec tous les principaux agents de codage IA. Claude Code, Cursor, Aider, Cline et Roo Code sont pris en charge. Ce design neutre côté agent permet à la spécification de vivre en dehors de Claude Code.

La page du projet Spec Kit sur GitHub.

Comment installer le GitHub spec‑kit

Il n’existe pas encore de package PyPI officiel ; installez donc le CLI depuis le tag Git avec uv :

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Remplacez vX.Y.Z par le tag de version actuel. Le package est specify-cli, et la commande qu’il enregistre est specify.

Le flux de travail du GitHub spec‑kit

Le flux s’appuie sur neuf slash‑commands que le CLI installe dans la liste des commandes de votre agent. Six sont au cœur de la boucle, trois sont optionnelles pour couvrir les cas aux marges.

Le séparateur entre le groupe et le verbe est un point, pas un deux‑points : /speckit.specify, pas /speckit:specify. 

Les neuf slash‑commands de Spec Kit : six essentielles sur le pipeline, trois optionnelles en dérivation.

Les artefacts produits sont les mêmes spécification et plan vus dans la section Superpowers, eux aussi écrits sur disque et suivis dans Git. La différence tient à la portabilité : les artefacts de Spec Kit sont conçus pour fonctionner avec n’importe quel agent de codage IA, pas seulement Claude Code, et le flux est pensé pour la revue des parties prenantes via des pull requests GitHub plutôt qu’en sous‑produit d’un outil unique.

Quand utiliser le GitHub spec‑kit

Sur un projet solo, vous n’en aurez probablement pas besoin. Utilisez‑le quand :

• Le projet dépasse une seule personne
• Votre spécification doit être relue par des personnes qui n’ouvrent jamais Claude Code
• Vous utilisez un agent autre que Claude Code pour une partie du travail
• Vous voulez un format de spécification indépendant d’un outil et lisible des mois plus tard

La méthode BMAD

Là où Spec Kit organise les artefacts, BMAD organise les personnes. Elle scinde le flux de « spécification vers code » en quatre phases, chacune portée par un agent‑rôle nommé.

Qu’est‑ce que BMAD ?

BMAD-METHOD (bmad-code-org/BMAD-METHOD, licence MIT, environ 47 k étoiles) en est à la version 6. L’acronyme, dans la documentation du projet, s’étend en « Breakthrough Method for Agile AI‑Driven Development ». Il fonctionne au‑dessus de Claude Code et d’autres agents, et s’installe comme un écosystème de modules. L’installation par défaut fournit un module cœur avec six agents‑rôles, quatre phases et 34 workflows (ou plus) nommés.

La page du projet BMAD-METHOD sur GitHub.

Comment installer BMAD

Installez BMAD avec Node :

npx bmad-method install

Les six agents‑rôles sont des personas de prompt que l’utilisateur active par leur nom dans l’hôte agent. Dans Claude Code, cela signifie taper la commande d’activation installée par BMAD. Consultez le README pour la syntaxe exacte, qui évolue selon les versions. 

Présentation des agents‑collègues BMAD et des artefacts

Une fois activé, l’agent adopte les instructions, la voix et les livrables de ce rôle jusqu’au changement de persona. Les six sont :

• Mary, l’Analyste
• Paige, la Rédactrice technique
• John, le Chef de produit
• Sally, la Designer UX
• Winston, l’Architecte
• Amelia, la Développeuse

Deux rôles attendus manquent en v6 : pas d’agent Scrum Master ni d’agent QA dédié. La planification de sprint et la préparation des stories relèvent de l’agent Développeur, et la génération des tests QA est un workflow déclenché par le Développeur.

L’ensemble d’artefacts est plus riche qu’une simple spécification. Vous obtenez :

• un « product brief »
• un PRD (Product Requirements Document)
• une spécification UX
• un document d’architecture
• des épopées (« epics ») déclinées en user stories (ce que l’utilisateur pourra faire une fois livré)

Le PRD et le document d’architecture jouent ensemble le même rôle que la spécification Superpowers. La séparation les répartit sur deux agents‑rôles et dans un format plus formel. L’ensemble couvre tout le cycle de développement logiciel, chaque fonctionnalité héritant du contexte de la couche au‑dessus.

Le flux de travail BMAD

Le flux v6 se déroule en quatre phases.

Les quatre phases BMAD et l’agent‑rôle pour chacune. La piste Quick Flow saute les trois premières phases pour les petits travaux.

Phase 1, analyse, optionnelle. Mary (Analyste) et Paige (Rédactrice technique) mènent la recherche et produisent un product brief. Passez cette phase si vous savez déjà quoi construire.

Phase 2, planification, obligatoire. John (PM) rédige le PRD. Sally (UX) ajoute une spécification UX quand la fonctionnalité a une interface.

Phase 3, solutioning, est la phase de Winston. L’Architecte rédige d’abord l’architecture, puis John découpe les exigences en epics et stories. Placer les stories après l’architecture est un choix v6 qui les dimensionne selon des frontières d’implémentation réelles. Winston mène ensuite un contrôle de « préparation à l’implémentation » qui conclut par PASS, CONCERNS ou FAIL.

Phase 4, implémentation, où Amelia (Développeuse) avance story par story : créer la story, la construire et la relire. Une fois une epic complète, elle déclenche un workflow de génération de tests QA sur l’epic. C’est la phase où Claude Code écrit effectivement le code, en tant qu’Amelia.

Pour les petits travaux bien cadrés, BMAD propose une piste « Quick Flow » qui active directement Amelia et saute les trois premières phases. La commande d’activation est dans le README BMAD (la syntaxe exacte évolue). Quick Flow ne produit ni PRD ni document d’architecture : juste une courte story et le code qui la satisfait. C’est la réponse à « c’est trop lourd pour changer un bouton ».

Quand la spécification s’avère erronée en cours d’implémentation, BMAD revient au verdict de la Phase 3. Un FAIL vous renvoie en Phase 2 pour réécrire le PRD. Un CONCERNS poursuit avec les risques notés par Winston associés à la story. Cette distinction vous permet d’avancer malgré de petites incohérences et d’arrêter net sur les grosses.

Quand la complexité paie

BMAD est rentable sur des projets au long cours avec de vrais utilisateurs. Il convient aussi aux équipes multi‑développeurs, en assurant les passages de relais. La séparation en phases et rôles doit faire gagner plus de temps qu’elle n’en coûte.

Ce n’est pas adapté à un projet personnel. En solo, la partition en quatre phases et six agents est surtout de la charge. Il n’y a pas de deuxième personne pour que la séparation des rôles prenne tout son sens.

Comment choisir entre les cadres

Trois règles guident le choix.

• Utilisez Spec Kit si la spécification doit être lue par des personnes qui n’ouvrent jamais Claude Code, ou doit vivre dans Git comme artefact de long terme.
• Si plusieurs personnes travaillent sur des rôles distincts, ou si un véritable interlocuteur « PM » est dans la boucle, utilisez BMAD.
• Sinon, utilisez Superpowers.

Trois questions sur votre projet, quatre cadres possibles en sortie.

Il existe une quatrième option nommée par l’arbre de décision : combiner Spec Kit et Superpowers. Utilisez Spec Kit pour la phase de spécification afin que les artefacts vivent dans Git pour la revue inter‑équipes. Puis pointez la skill subagent-driven-development de Superpowers vers le fichier de plan Spec Kit via une simple ligne de configuration. Vous obtenez la spécification durable de Spec Kit et la boucle d’implémentation resserrée de Superpowers.

Conclusion

Le développement piloté par les spécifications repose sur trois documents, dans l’ordre. La spécification dit quoi construire, le plan dit par quelles étapes, et le code suit le plan. Une relecture humaine s’intercale entre chaque paire.

Parcourez l’arbre de décision ci‑dessus pour choisir un cadre qui, pour la plupart des lecteurs, aboutira à Superpowers. Installez‑le et choisissez une fonctionnalité que vous auriez sinon « vibe‑codée », quelque chose qui touche 3 à 5 fichiers. Faites‑la de bout en bout : brainstorm, spécification, plan, exécution. Un vrai passage en conditions réelles vaut mieux que n’importe quelle description.

Si vous souhaitez d’abord réviser les fondamentaux de Claude Code, DataCamp propose un tutoriel pratique Claude Code, un guide des bonnes pratiques couvrant le mode Plan, CLAUDE.md et le TDD, et un focus approfondi sur le mode Plan.