Spec-Driven Development with BMAD

1L'IA invente tout ce que le contexte ne dit pas

Première famille : encadrer le code, en commençant avant la première ligne. L'IA ne connaît du projet que ce qu'on lui en dit. On appelle cela le contexte. Ce que le contexte ne dit pas, l'IA l'invente. Le livre propose donc de fixer le contexte d'avance : c'est le context engineering. Son objectif est de créer « des frontières de vérité que l'IA ne peut pas franchir » (leçon 5). Autrement dit, des faits posés d'avance, que l'IA ne doit pas contredire. Voici une consigne nue, puis la même avec son contexte :

✗ AVANT : Construis une application de liste de tâches.

✓ APRÈS (exemple du livre, abrégé) :
Qui      : des designers freelances débordés
Pourquoi : suivre les heures facturables par tâche
Quoi     : un Kanban (un tableau de cartes en colonnes) avec un minuteur, pas de fonction sociale

Dans ce bloc, la dernière ligne est la plus utile. Elle dit aussi ce qu'on ne construit pas : pas de fonction sociale. Le livre y consacre une section, « Explicit exclusions », les exclusions explicites. Sans elle, le projet peut grossir de fonctions que personne n'a demandées. C'est la dérive de périmètre. Le livre dit que fixer d'avance ce qui est hors périmètre l'évite.

2Les tests s'écrivent avant le code, pas après

Le contexte dit quoi construire. Reste à vérifier que l'agent l'a bien construit. Or un agent peut coder d'abord, puis écrire ses tests ensuite. Ses tests vérifient alors ce qu'il a fait, pas ce qu'on lui avait demandé.

BMAD inverse donc l'ordre avec son module de tests, TEA (Test Architect, architecte de tests, que le livre écrit de trois façons). Sa méthode s'appelle ATDD : le développement piloté par les tests d'acceptation. Elle part des critères d'acceptation. Un critère d'acceptation (AC en anglais) est une condition que la fonctionnalité doit remplir pour être déclarée finie. Chaque critère porte un identifiant, comme AC1, et on écrit un test pour chacun avant le code.

La méthode suit trois temps, avec des couleurs de feu. Rouge : le test échoue, car la fonctionnalité n'existe pas encore. Vert : l'agent code jusqu'à ce que le test passe. Refactor : on nettoie le code sans changer ce qu'il fait.

Cette boucle repart donc à chaque critère d'acceptation. Les tests sont d'abord mis en veille avec test.skip : ils existent, mais ne s'exécutent pas. Voici ma version minimale, pas une copie du livre :

test.skip('AC1 : la carte affiche le titre de la tâche', async () => {
  // corps du test à écrire
});

Pour passer au rouge, on retire le skip : le test échoue. L'agent code ensuite jusqu'au vert. Dans la démonstration du livre, les tests de la carte et de la fenêtre de tâche existent avant la moindre ligne d'interface. La raison, selon l'auteur : « si les tests sont créés après l'implémentation, nous ne couvrons pas forcément tous les scénarios » (leçon 26).

Ces identifiants servent aussi de fil d'un document à l'autre : ils relient la story, son test et sa revue (idée 4). Une story est une unité de travail, assez petite pour tenir dans une session. Elle est décrite dans un fichier markdown, du texte à mise en forme légère.

3Avant le code, on vérifie que les documents concordent

Les tests vérifient le code. Avant le code, BMAD vérifie aussi les documents. À ce stade, il n'existe encore aucun code, seulement trois textes : le PRD (ce qu'il faut faire), l'architecture (comment le construire) et les epics, c'est-à-dire de grands lots de fonctionnalités découpés en stories. Ces textes peuvent se contredire ou oublier quelque chose.

Imaginez trois plans d'une même maison : celui de l'architecte, celui de l'électricien, la liste des pièces. Avant de bâtir, on s'assure qu'ils décrivent la même maison. Le contrôle d'implementation readiness (« prêt à implémenter ») fait ce travail. Un agent lit les trois documents et les recoupe.

Ce contrôle agit comme une porte avant l'implémentation. Il rend l'un de trois verdicts :

• PASS : tout est cohérent, on avance ;
• CONCERNS : des écarts existent, mais ils ne bloquent pas ;
• FAIL : on corrige avant de continuer.

Sur la démonstration, ce contrôle a trouvé trois problèmes dans les documents, avant la moindre ligne de code (leçon 28) :

• des entités absentes du modèle de données : des objets que l'application manipule, mais qu'aucun document ne décrit ;
• un filtre par date manquant ;
• un AppProvider qui aurait fait planter l'application s'il avait été construit tel quel. C'est le composant racine, celui qui distribue les données partagées à tous les écrans.

Un FAIL n'a donc rien d'un drame. Le livre le dit : « plutôt que d'y voir un revers, voyez le système qui fait son travail » (leçon 15). L'agent propose le correctif, puis l'humain le valide.

4Après chaque story, une revue qui cherche à casser le code

Le contrôle de l'idée 3 passe avant le code. La revue passe après, à la fin de chaque story. Pour le livre, elle n'est « pas une formalité » (leçon 18). C'est un contrôle adversarial : il cherche à faire tomber le travail plutôt qu'à le confirmer. Son but est d'attraper ce que l'implémentation a laissé passer.

Or le livre décrit cette revue de deux façons, sans choisir entre elles :

• Leçon 18, trois passes à la suite. Le Blind Hunter cherche les erreurs de logique et les échecs silencieux, ceux qui n'affichent aucun message. L'Edge Case Hunter cherche les cas limites, comme une liste vide, et les accès concurrents. L'Acceptance Auditor vérifie chaque identifiant de critère. Avant la revue, un menu demande quels changements relire : non commités, indexés, différence de branche ou plage de commits.
• Leçon 31, trois agents en parallèle. Le workflow les lance en même temps, sur les cas limites, les critères d'acceptation et la différence avant et après. Aucun Blind Hunter n'y est nommé.

Dans les deux cas, le développeur corrige, puis la revue repasse.

Le livre ajoute un conseil : confier la revue à « idéalement un autre modèle » (leçon 30), pour une évaluation indépendante. La raison, à mon sens : deux sessions du même modèle partagent les mêmes angles morts.

5Chaque workflow démarre dans une session neuve

Seconde famille : donner au projet une mémoire d'une session à l'autre. Elle part d'une règle du livre : une nouvelle session par workflow, sans exception. Il ne faut « jamais enchaîner » le PRD puis l'architecture dans la même session (leçon 43).

La raison : le contexte accumulé biaise la suite. Pendant le PRD, la conversation se remplit de discussions sur le produit. Si on enchaîne avec l'architecture, l'agent les a encore en tête et s'en inspire. Une session neuve, c'est un tableau blanc effacé avant la réunion suivante.

Ce contexte a aussi une taille limitée, comptée en tokens. Un token est un morceau de mot, l'unité que le modèle compte et facture. Changer de session coûte peu : « repartir de zéro coûte quelques secondes » (leçon 45).

Repartir de zéro pose pourtant une question : comment ne pas perdre le travail en cours ? Chaque workflow garde la trace de son avancement dans un fichier (leçon 21). Le livre le montre deux fois :

• l'installation des tests écrit son avancement dans le fichier framework-setup-progress (leçon 22) ;
• le PRD se construit en onze étapes, et son avancement s'écrit aussi dans un fichier.

Si le contexte sature, on ouvre une session neuve et on relance le workflow en lui désignant ce fichier. Il reprend où il en était (leçon 27).

6project-context.md : des règles qui s'enrichissent à chaque rétrospective

Une session neuve repart de zéro, mais le projet, lui, doit se souvenir. BMAD range cette mémoire dans le fichier project-context.md, « une constitution pour le projet » (leçon 15). Il joue le rôle d'un CLAUDE.md, le fichier de consignes que Claude Code relit à chaque session. Il n'est chargé que dans les workflows BMAD : 18 workflows et fichiers s'y réfèrent (leçon 23).

Le project-context.md liste d'abord la pile technique, c'est-à-dire les langages et outils du projet, avec leurs versions. Il liste ensuite des conventions : configuration TypeScript, gestion d'état, modèle de données, bonnes pratiques de test.

Cette constitution, on l'amende à la fin de chaque epic, et c'est la meilleure idée du livre. Trois étapes se suivent :

1. Une porte de couverture vérifie que l'epic est assez testé. La couverture est la part du code que les tests vérifient. La porte rend PASS, CONCERNS, FAIL ou WAIVED, une dérogation validée par le métier. Un epic mal testé ne se clôt donc pas (leçon 19).
2. La rétrospective, le bilan de l'epic, relit les notes de complétion écrites à la fin de chaque story.
3. On relance la génération du fichier, qui intègre ce bilan.

Un cas concret, pas du livre : un test a fait perdre du temps parce que la base de données n'était pas vidée entre deux tests. La rétrospective en tire une règle, « vider la base avant chaque test ». L'epic suivant démarre avec elle.

Cette boucle, le livre la résume en une phrase : « le project-context.md devient le registre vivant de la façon dont le projet a appris à se construire » (leçon 19).

7Un petit changement passe par une version allégée

Tout ce rituel pèserait lourd pour corriger un bouton. Pour les petits changements, BMAD prévoit donc le workflow quick-dev. Il condense en une session l'intention, le plan, l'implémentation et la revue.

Ce raccourci a un piège. BMAD estime d'abord le « rayon d'impact » du changement : les chemins par lesquels il pourrait casser autre chose. Quand ce rayon est nul, quick-dev peut implémenter sans écrire de spécification. Le livre demande de l'exiger quand même, pour la traçabilité : pouvoir retrouver plus tard pourquoi le code a changé (leçon 24).

Même allégé, le workflow laisse le dernier mot à l'humain. Quand quick-dev propose de plafonner l'affichage à trois tags, le livre suggère de refuser (leçon 26).