BMAD : le pari de la documentation exécutable

Dans un projet de développement classique, le développeur écrit du code. C’est son output principal, le livrable que le projet attend de lui.

BMAD change la donne. Avec ce framework, l’output principal du développeur devient la documentation. Et c’est cette documentation qui produit le code, via des agents IA spécialisés.

Ce renversement est plus concret qu’il n’y paraît. Il ne s’agit pas d’écrire plus de specs pour la rigueur.

Il s’agit d’un workflow où chaque décision d’architecture, chaque spécification fonctionnelle, chaque critère d’acceptance est formalisé dans un fichier avant que l’IA commence à coder. C’est de cette base documentaire que le code émerge, de façon cohérente et traçable.

Pour une équipe, les implications sont significatives : sur la gouvernance, sur la répartition des rôles, et sur ce qu’on attend concrètement d’un développeur qui travaille avec l’IA.

1. Qu’est ce que BMAD ?

BMAD – Breakthrough Method for Agile AI-Driven Development – est un framework open source de développement piloté par agents IA. Il est gratuit et s’installe en une commande :

npx bmad-method install

Mais réduire BMAD à un outil serait une erreur. C’est avant tout une méthode, une façon d’organiser la collaboration entre humains et IA à travers des rôles définis, des phases séquentielles, et une hiérarchie documentaire qui pilote l’ensemble du projet.

La documentation comme pilote, pas comme livrable

Dans un projet classique, la documentation est un livrable : on la produit en fin de sprint, elle vieillit dans un coin de Confluence, et personne ne la consulte vraiment.

Dans BMAD, la documentation est un pilote : elle précède le code, le génère, et reste la référence en cas de désaccord ou de régression.

Ce positionnement implique que les specs soient maintenues avec le même soin que le code et mises à jour quand les décisions évoluent.

Si le code diverge des specs, c’est le code qui a tort.

Un point important : cette documentation n’est pas un outil tiers, une plateforme ou un wiki d’entreprise. Ce sont des fichiers Markdown, stockés dans le repository aux côtés du code, versionnés dans Git comme n’importe quel fichier source.

Pas de licence supplémentaire, pas d’intégration à configurer – les agents IA lisent directement ces fichiers au moment d’exécuter leur tâche.

Les agents spécialisés

Là où la plupart des équipes utilisent un LLM généraliste pour tout faire, BMAD déploie différents agents aux rôles distincts et aux permissions restreintes :

• Analyst : conduit les sessions de découverte, transforme une intention floue en brief structuré
• Product Manager : rédige le PRD, définit le périmètre MVP, gère les compromis
• Architect : conçoit l’architecture technique, les schémas de base de données, les contrats d’API
• Scrum Master : découpe la documentation en stories atomiques exploitables par le Developer
• Developer : implémente les stories
• QA / Test Architect : valide la qualité, produit les stratégies de test
• UX Designer : génère les spécifications d’interaction

Chaque agent a un périmètre strict :

• Le Developer ne peut pas modifier le schéma de base de données.
• L’Architect ne dérive pas en écriture de feature.

Ce cloisonnement garantit la cohérence du résultat et empêche les dérives que l’on observe avec un LLM non contraint.

Le workflow BMAD

BMAD impose un workflow en quatre temps :

1. Analysis – l’Analyst transforme l’intention produit en brief exploitable
2. Planning – le PM produit un PRD détaillé, avec des epics et un périmètre clair
3. Solutioning – l’Architect conçoit les blueprints techniques
4. Implementation – le Developer exécute story par story

On ne passe pas à la phase suivante sans avoir validé la précédente. Il est structurellement impossible de coder sans que les specs existent. Ce n’est pas une recommandation – c’est la logique du framework.

2. Qu’est ce que cela change pour vous ?

C’est la question qui mérite d’être posée : qu’est-ce qui change pour les personnes qui travaillent avec ce framework au quotidien ?

Dans un projet classique, le développeur porte le contexte dans sa tête

Sans BMAD, le développeur qui travaille avec une IA reconstruit le contexte à chaque session. Il re-explique l’architecture, rappelle les contraintes, repose les décisions déjà prises.

L’IA repart de zéro à chaque fois – et produit des résultats qui divergent au fil des sessions. La cohérence du projet repose sur la mémoire des individus, pas sur un système.

Sur un projet qui dure plusieurs mois avec plusieurs développeurs, cela génère des incohérences difficiles à identifier et coûteuses à corriger : des patterns contradictoires d’un fichier à l’autre, des décisions d’architecture jamais documentées, des composants qui ne respectent pas les mêmes conventions.

La dette technique s’accumule non pas parce que l’IA code mal, mais parce qu’elle code sans mémoire.

Avec BMAD, le développeur travaille en amont du code

Le déplacement est net : le développeur passe moins de temps à écrire du code et plus de temps à formaliser les décisions qui permettront à l’IA de le faire correctement. Il rédige des specs précises, valide une architecture, découpe les stories. L’agent Developer exécute ensuite dans ce cadre – sans réinventer ce qui a déjà été décidé, sans diverger du schéma validé.

En pratique, une journée de travail ressemble davantage à celle d’un lead technique qu’à celle d’un développeur junior : on arbitre des choix, on valide des propositions d’architecture, on affine les critères d’acceptance. L’IA produit le code, le développeur gouverne la direction.

Ce n’est pas une réduction du rôle du développeur. C’est un déplacement vers les activités à plus haute valeur ajoutée : la conception, l’arbitrage technique, la validation. L’exécution répétitive est déléguée.

Ce que cela libère, ce que cela implique

Le gain principal est la cohérence.

Une IA qui travaille dans un contexte structuré et stable produit des résultats beaucoup plus prévisibles qu’une IA à laquelle on re-explique tout à chaque session. Chaque agent ne reçoit que le contexte pertinent pour sa tâche – ce qui réduit les hallucinations, améliore la précision et rend le résultat plus facile à reviewer.

La contrainte principale est le changement de posture.

Un développeur habitué à coder directement devra accepter de passer du temps à rédiger avant de voir du code. Cette friction est réelle, surtout dans les premières semaines. Elle s’atténue une fois que l’équipe a intégré que la qualité de la documentation est directement corrélée à la qualité du code produit – et pas l’inverse.

3. Qu’est ce que cela change pour l’organisation ?

BMAD n’est pas une question d’outillage. C’est une question d’organisation – et les implications sont concrètes pour les décideurs.

La traçabilité comme sous-produit du process

Chaque décision d’architecture, chaque choix de conception, chaque compromis produit est documenté et versionné avant que le code existe.

Pour les équipes qui font face à des audits clients, des appels d’offres avec exigences de traçabilité, ou simplement des transitions de prestataires, c’est un avantage concret : chaque choix technique est justifiable, daté, et rattaché à un contexte.

Pas besoin de reconstituer a posteriori pourquoi telle décision a été prise – elle est dans le dépôt Git, avec la date et le raisonnement.

La réduction du bus factor

Dans la plupart des équipes, la connaissance d’un projet est concentrée dans la tête de deux ou trois personnes – souvent les plus anciens. Si l’un d’eux part, une partie de la mémoire du projet part avec lui.

Avec BMAD, cette connaissance est dans les fichiers. L’architecture est documentée, les décisions sont tracées, les règles métier sont formalisées dans les stories. Un nouveau développeur peut reprendre le fil d’un projet sans dépendre d’un transfert de connaissance oral – et un prestataire externe peut intervenir sur une partie du système sans avoir besoin de comprendre l’ensemble.

L’onboarding transformé

Quand un nouveau développeur rejoint un projet BMAD, il dispose d’une documentation complète, à jour et structurée qui reflète l’état réel du système. Pas les notes de réunions d’il y a six mois. Pas le « je t’explique oralement ». La documentation étant maintenue comme du code, elle est fiable par construction.

En pratique, le temps nécessaire pour qu’un nouveau développeur soit autonome sur une feature se réduit significativement – parce que le contexte n’est plus à reconstituer, il est disponible.

Ce que cela exige en retour

Soyons directs : BMAD exige une discipline documentaire que peu d’équipes ont naturellement. Il faut savoir écrire de bonnes specs, formaliser les décisions d’architecture, maintenir un backlog propre. Si cette culture n’existe pas dans votre équipe, BMAD ne la créera pas – il révélera son absence.

4. Les limites du framework

BMAD a des points forts bien documentés par sa communauté. Ce qu’on lit moins, c’est ce qui coince vraiment.

Une courbe d’apprentissage sous-estimée

Maîtriser BMAD demande un peu de temps pour en exploiter les techniques avancées. La configuration des agents (YAML, gestion des handoffs, permissions par rôle), la logique de context sharding, l’orchestration multi-agents : tout cela s’apprend.

Des alternatives plus légères sont opérationnelles en une journée. BMAD vaut l’investissement – mais il faut le consentir lucidement.

Inadapté aux périmètres trop instables

BMAD encadre très bien la discovery – l’agent Analyst est précisément conçu pour transformer une intention floue en brief structuré. La vraie limite apparaît quand la vision produit est si instable que les specs deviennent obsolètes avant même que le code soit écrit.

Si la direction change toutes les semaines, la charge documentaire devient un frein net : on passe du temps à formaliser des décisions qui seront remises en cause avant d’être implémentées. Dans ce cas précis, une approche plus légère est préférable – BMAD reprendra sa valeur une fois le cap stabilisé.

Une consommation de tokens élevée

BMAD est gourmand en tokens. Chaque agent charge son contexte complet à chaque appel : le PRD, les specs d’architecture, la story en cours, les règles du framework. Sur un projet dense avec plusieurs agents actifs, la facture API peut surprendre. Ce n’est pas un défaut de conception – c’est le prix de la cohérence. Mais c’est un paramètre à intégrer dans le calcul économique avant de déployer à grande échelle.

5. BMAD ou développement IA classique : comment choisir

Les deux approches répondent à des besoins différents selon le moment de vie du projet et les contraintes de gouvernance. Aucune n’est universellement meilleure.

Les questions à se poser avant de choisir

Adoptez BMAD si :

• Votre projet dure longtemps et implique plusieurs développeurs
• Vous avez des exigences de traçabilité : audits, appels d’offres, transitions de prestataires
• Vous modernisez un système legacy et devez relier chaque nouveau composant à une logique métier existante
• Votre équipe a une culture agile solide : vous savez écrire de bonnes specs et tenir un backlog propre

Évitez BMAD si :

• Votre vision produit est trop instable – les specs d’aujourd’hui seront obsolètes dans dix jours
• Votre équipe n’a pas de culture de la documentation – BMAD ne comblera pas ce manque, il l’amplifiera
• Vous avez besoin d’un PoC livrable rapidement

7. Comment adopter BMAD sans se perdre

Si BMAD vous semble pertinent pour votre contexte, voici une approche progressive qui évite les erreurs classiques.

Investir dans la phase Analyst dès le départ

La qualité de tout ce qui suit dépend directement de la qualité du brief initial. Une session Analyst bâclée produit un PRD approximatif, qui produit une architecture fragile, qui produit du code qui ne correspond pas à l’intention de départ. Prenez le temps de cette phase – c’est là que le retour sur investissement se joue.

Ne pas contourner le Scrum Master

La tentation de sauter le découpage en stories atomiques est forte, surtout sous pression de livraison. C’est précisément cette étape qui garantit que le Developer agent travaille dans un contexte maîtrisé. La contourner, c’est sacrifier la cohérence que le framework est censé apporter.

Traiter la documentation comme du code

Versionnez dans Git, reviewez lors des PR, mettez à jour quand les décisions évoluent. Si vos specs restent dans des documents Word ou des pages Confluence non maintenues, BMAD n’apportera rien.

Conclusion : le pari mérite d’être tenu – dans les bons contextes

BMAD est un framework sérieux, bien conçu, et honnête dans ses ambitions. Son pari central – faire de la documentation la source de vérité du projet plutôt qu’un livrable accessoire – est le bon pari à long terme pour les équipes qui développent des applications métier complexes avec l’IA.

Trois points à retenir avant de vous lancer :

• BMAD n’est pas fait pour tout le monde. Sur un projet exploratoire ou une équipe sans culture documentaire, il sera contre-productif.
• Le vrai coût est organisationnel, pas technique. L’installation prend trois minutes. Changer les habitudes de travail d’une équipe, c’est une autre affaire.
• La qualité de la sortie IA est proportionnelle à la qualité de ce qu’on lui donne. C’est vrai avec ou sans BMAD – le framework rend simplement cette réalité impossible à ignorer.

Chez Sooyoos, nous accompagnons des équipes sur ces sujets depuis plusieurs années. L’intégration de l’IA dans un processus de développement logiciel métier structuré ne s’improvise pas – et les gains sont réels, à condition de partir sur des bases solides.

Vous évaluez comment intégrer l’IA dans votre processus de développement ? Contactez-nous pour un audit gratuit de 30 minutes. Nous analyserons ensemble la pertinence de BMAD pour votre contexte et ce qui a réellement du sens pour votre organisation.

FAQ – Questions fréquentes sur BMAD

BMAD est-il vraiment gratuit ?
Oui, entièrement. Le framework est open source, sans freemium, sans plan payant. Le code source est disponible sur GitHub et la documentation officielle est accessible librement.

Faut-il abandonner son workflow actuel pour adopter BMAD ?
Non. BMAD peut facilement se greffer sur des projets déjà bien entamés. L’adoption progressive est non seulement possible, elle est recommandée.

BMAD fonctionne-t-il avec tous les IDEs ?
BMAD s’intègre nativement avec Cursor et les IDEs compatibles Claude.

Combien de temps faut-il pour être opérationnel ?
L’installation prend quelques minutes. Être à l’aise avec le workflow complet peut prendre plusieurs semaines selon la complexité du projet et la familiarité de l’équipe avec les méthodes agiles.

BMAD peut-il remplacer un développeur ?
Non – et ce n’est pas sa prétention. BMAD structure la collaboration entre une équipe humaine et des agents IA. Il ne supprime pas le besoin de développeurs : il change leur rôle, qui passe de l’écriture de code à la validation, l’orientation et la gouvernance du travail des agents.

À partir de quelle taille de projet BMAD devient-il pertinent ?
Pour tout taille de projet. Cela peut aller d’un projet personnel « side-project » à un projet avec déjà une équipe bien structurée.