Claude Craft partie 2 : BMAD v6, quality gates et routing multi-agent

Un seul agent Claude qui fait tout, ça marche jusqu'au premier sprint sérieux. Dès que la PR revient avec une régression que personne n'a bloquée, que le contexte sature à mi-feature ou que l'architecture part dans une direction que le product owner n'avait pas validée, le modèle monolithique montre ses limites. BMAD v6, intégré dans Claude Craft v8.18.1 sorti le 28 juin 2026, répond à ce problème en structurant les 31 agents du framework autour de 9 personas spécialisés, 5 quality gates à seuils configurables et un routing basé sur le statut réel de la tâche. Ce tutoriel te montre comment activer cette architecture sur un projet existant sans tout réécrire, configurer les seuils adaptés à ton contexte et exploiter les trois scénarios les plus courants : revue de code multi-agent, génération d'API et déploiement supervisé.

31 agents, 9 personas — ce que BMAD v6 change vraiment

La confusion est fréquente, alors commençons par la clarifier. Claude Craft expose 31 agents par défaut — plus 39 packs infra optionnels — : ce sont des unités d'exécution spécialisées par stack (@symfony-reviewer, @tdd-coach, @kubernetes-architect), chacune maîtrisant un périmètre précis. Les 9 personas BMAD v6 sont une couche au-dessus : des orchestrateurs agent-as-code qui pilotent ces agents, appliquent les quality gates aux transitions de phase et gèrent le cycle de vie du sprint. Un persona n'exécute pas du code — il dirige ceux qui le font.

• bmad-master — orchestrateur central, lit .bmad/sprint-status.yaml, route vers le bon persona, enforce les quality gates et coordonne le batch processing
• ralph-conductor v2.0 — boucle continue avec circuit breaker adaptatif, intégration native /goal, DoD validators en temps réel, health monitoring (modèle Opus + effort xhigh)
• uiux-orchestrator — coordonne les spécialistes UI, UX et accessibilité pour des solutions design cohérentes
• product-owner — backlog, user stories, priorisation de sprint et validation des critères d'acceptance
• accessibility-expert — conformité WCAG 2.2 AAA et implémentation ARIA correcte (modèle Haiku + effort low)
• tech-lead — décomposition technique, ADR, décisions d'architecture et gestion du risque
• api-designer — design REST/GraphQL avec contrats OpenAPI, cohérence inter-services et versioning
• devops-engineer — configuration Docker, pipelines CI/CD et stratégies de déploiement
• qa-recette — tests d'acceptance automatisés via navigateur, génération de tests de régression, principe fondateur : un bug corrigé ne revient jamais

Le modèle IA n'est pas uniforme pour tous les personas : Claude Craft route automatiquement vers Opus avec effort xhigh pour les personas à forte charge cognitive (ralph-conductor, security-auditor, database-architect), vers Sonnet pour les agents courants et vers Haiku avec effort low pour les reviewers et l'accessibility-expert. Cette distribution cible une économie de 55 à 65 % sur les tokens sans sacrifier la précision là où elle compte.

bmad-master et le status-based routing

bmad-master est le point d'entrée de toute session multi-agent. À chaque commande, il lit le fichier .bmad/sprint-status.yaml, détermine la phase active du workflow (Analyze → Plan → Design → Implement → QA), sélectionne le persona correspondant et vérifie les quality gates avant toute transition. L'installation sur un projet existant prend moins d'une minute :

# Détection automatique du stack
npx @the-bearded-bear/claude-craft install . --tech=symfony --lang=fr

# Initialiser BMAD v6 sur le projet
# Dans Claude Code :
/workflow:init

BMAD v6 propose trois variantes de flow selon la complexité détectée automatiquement par /workflow:init : Quick (implémentation seule, moins de 5 min), Standard (plan → design → implement, moins de 15 min) et Enterprise (cycle complet analyze → implement, moins de 30 min). Le fichier .bmad/sprint-status.yaml généré et maintenu par bmad-master ressemble à ceci :

# .bmad/sprint-status.yaml — généré et mis à jour par bmad-master
sprint:
  id: sprint-4
  phase: implementation        # analyze | plan | design | implement | qa
  flow: standard
  active_persona: api-designer
  story:
    id: US-42
    title: "POST /api/orders — création de commande"
    assigned_to: dev
    review_by: tech-lead
  gates:
    prd: passed
    tech_spec: passed
    code_review: pending
    qa: pending
    dod: pending
  token_budget:
    used: 12400
    remaining: 87600

Le raccourci le plus puissant reste /workflow:auto-sprint : il exécute un sprint de bout en bout — story → décomposition → validation → implémentation → PR → CI watch → revue → rétro → merge — chaque cérémonie dans un sous-agent isolé pour éviter la pollution de contexte. Pour les tâches itératives, /common:ralph-run "description de la tâche" active la boucle continue de ralph-conductor jusqu'à satisfaction du DoD, avec circuit breaker adaptatif pour sortir des boucles infinies.

Les 5 quality gates et leurs seuils configurables

Chaque transition de phase passe obligatoirement par un gate. bmad-master bloque la progression si le seuil n'est pas atteint et renvoie un feedback structuré vers le persona concerné. Voici les cinq gates, leurs seuils par défaut et les personas impliqués :

• PRD Gate — seuil ≥ 80 %, reviewers : product-owner + tech-lead, bloque l'entrée en phase Design
• Tech Spec Gate — seuil ≥ 90 %, reviewers : tech-lead + api-designer, bloque l'entrée en Implement
• Code Review Gate — grille 4×25 points (architecture, qualité, testing, sécurité) : APPROVE ≥ 80, COMMENT 50–79, REQUEST CHANGES < 50
• QA Gate — couverture minimale configurable + passage de la suite qa-recette, bloque le DoD
• Definition of Done Gate — validation croisée product-owner + qa-recette avant merge en main

# .bmad/gates.yml — Claude Craft v8.18.1
gates:
  prd:
    threshold: 80
    reviewers: [product-owner, tech-lead]
    blocking: true

  tech_spec:
    threshold: 90
    reviewers: [tech-lead, api-designer]
    blocking: true

  code_review:
    dimensions:
      architecture: 25
      code_quality: 25
      testing: 25
      security: 25
    approve_threshold: 80
    comment_threshold: 50       # entre 50 et 79 → discussion, pas de merge
    blocking: true
    auto_escalate: true         # COMMENT → déclenche session tech-lead automatiquement

  qa:
    coverage_min: 90
    acceptance_required: true
    blocking: true

  definition_of_done:
    cross_validation: [product-owner, qa-recette]
    blocking: true

L'option auto_escalate: true sur le Code Review Gate est particulièrement efficace en équipe : quand le score tombe en zone COMMENT (50–79), bmad-master déclenche automatiquement une session tech-lead, journalise l'escalade dans le dashboard et notifie le product-owner que la story est en révision technique. Aucune intervention manuelle requise.

Scénario 1 — Revue de code multi-agent sur un endpoint Symfony

Une PR sur un contrôleur Symfony 8.1 arrive. Le workflow enchaîne trois personas sans intervention : dev soumet la revue, tech-lead évalue l'architecture et la sécurité, qa-recette valide les tests de régression sur l'endpoint modifié. Si le score atterrit en zone COMMENT, l'escalade vers tech-lead est automatique — et journalisée.

# 1. Le développeur demande la revue
/dev:review --pr=42
# bmad-master route vers tech-lead
# Score obtenu : 73/100 → COMMENT → auto_escalate déclenché

# 2. tech-lead soumet ses suggestions, api-designer vérifie le contrat REST
/gate:validate-quality --pr=42
# Score après révision : 84/100 → APPROVE

# 3. qa-recette exécute les tests de régression navigateur
/qa:recette --scope=api --story=US-42

# 4. Vérifier le statut du workflow
/workflow:status

Le dashboard affiché par /workflow:status centralise tout en temps réel :

Sprint 4 — US-42 : POST /api/orders
────────────────────────────────────────────────
Phase active   : implementation
Persona actif  : qa-recette
Code Review    : COMMENT (73) → escalade tech-lead → APPROVE (84)
QA Gate        : en cours — couverture 88% (seuil 90%)
DoD Gate       : en attente
Budget tokens  : 18 200 utilisés / 100 000
ETA            : ~8 min
────────────────────────────────────────────────
Blockage détecté : QA coverage 88% < 90% — action requise : /qa:automate

Scénario 2 — Générer une API avec product-owner et api-designer

Partir d'une user story brute et obtenir un contrat OpenAPI 3.1 complet validé par le Tech Spec Gate — sans ticket Jira ni réunion de grooming. Le workflow : product-owner formalise la story, api-designer génère le contrat, tech-lead valide à 90 %.

# 1. Raffiner la story avec le product-owner
/po:refine --story="En tant que vendeur, je veux créer une commande via API afin d'automatiser mon ERP"

# 2. api-designer génère le contrat OpenAPI depuis la story validée
/arch:api --from-story=US-42 --format=openapi3 --output=docs/api/orders.yaml

# 3. Déclencher le Tech Spec Gate (seuil 90%)
/gate:validate-quality --spec=docs/api/orders.yaml

Le fichier généré par api-designer respecte les conventions validées en phase Design et inclut les cas d'erreur RFC 9457 (application/problem+json) :

# docs/api/orders.yaml — généré par api-designer (Claude Craft v8.18.1)
openapi: "3.1.0"
info:
  title: Orders API
  version: "1.0.0"
paths:
  /api/orders:
    post:
      operationId: createOrder
      summary: Créer une nouvelle commande
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        "201":
          description: Commande créée
          headers:
            Location:
              schema:
                type: string
                format: uri
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        "422":
          description: Erreur de validation
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        "401":
          description: Non authentifié

Si le Tech Spec Gate échoue — par exemple, api-designer renvoie 87 % sur les 90 % requis — bmad-master refuse d'ouvrir la phase Implement et détaille les points manquants (sécurité, gestion des conflits d'idempotence). Le code n'est jamais écrit sur un contrat incomplet.

Scénario 3 — Déploiement supervisé par devops-engineer

devops-engineer ne prend la main qu'après validation du DoD Gate. Il vérifie la configuration Docker, le pipeline CI et les variables d'environnement de staging avant d'autoriser le déploiement. Si un gate amont est encore pending, la commande échoue immédiatement avec un log structuré.

# Déclencher la supervision déploiement — bloqué si DoD Gate pas franchi
/devops:deploy --env=staging --stack=symfony

# devops-engineer génère le Dockerfile optimisé selon le stack détecté

# Généré par devops-engineer — Claude Craft v8.18.1 / PHP 8.5 + Symfony 8.1
FROM php:8.5-fpm-alpine AS base

RUN apk add --no-cache \
    postgresql-dev \
    icu-dev \
    libzip-dev \
    && docker-php-ext-install \
        pdo_pgsql \
        intl \
        zip \
        opcache

COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
WORKDIR /app

# ── Dépendances ──────────────────────────────
FROM base AS deps
COPY composer.json composer.lock ./
RUN composer install \
    --no-dev \
    --optimize-autoloader \
    --no-interaction \
    --no-scripts

# ── Runtime ──────────────────────────────────
FROM base AS runner
COPY --from=deps /app/vendor ./vendor
COPY . .

RUN php bin/console cache:warmup --env=prod \
    && chown -R www-data:www-data var/ \
    && chmod -R 750 var/

EXPOSE 9000
CMD ["php-fpm"]

Si le DoD Gate est encore pendant — par exemple, QA Gate bloqué à 88 % de couverture sur 90 % requis — /devops:deploy retourne une erreur bloquante et bmad-master journalise le refus avec le détail du gate manquant. Aucune variable d'environnement de production n'est touchée avant validation complète.

Agent frontmatter et isolation par worktree

Chaque persona dans Claude Craft est défini par un frontmatter YAML qui déclare le modèle IA cible, le niveau d'effort, les outils autorisés et la liste des agents qu'il peut déléguer. L'isolation par worktree git garantit qu'aucun sous-agent ne pollue le contexte d'un autre : chaque persona opère dans sa propre branche, et ses modifications ne deviennent visibles qu'après validation du gate correspondant. C'est cette isolation qui permet à /workflow:auto-sprint d'enchaîner plusieurs personas en parallèle sans collision d'état — chaque worktree est un sandbox étanche dont seul bmad-master lit le statut via .bmad/sprint-status.yaml. Pour ajouter un persona custom, il suffit de créer un fichier .claude/agents/mon-persona.md avec le frontmatter approprié et de le déclarer dans .bmad/personas.yaml : bmad-master l'intégrera automatiquement au routing dès la prochaine session.

La force de BMAD v6 ne réside pas dans le nombre d'agents, mais dans la discipline qu'il impose au workflow : aucun code écrit sans contrat validé, aucun déploiement sans DoD franchi, aucune régression qui passe entre les mailles d'un gate. La troisième partie de la série Claude Craft couvrira la configuration des personas custom avancés, les packs infra optionnels et l'intégration de ce routing multi-agent dans un pipeline CI/CD GitOps complet.