Orchestration multi-agents avec Claude Code :
comment livrer une feature complète
en 90 minutes

Je vais être direct : la plupart des articles sur l'"IA qui code à votre place" sont du marketing. Ce qui m'intéresse — et ce qui devrait vous intéresser si vous êtes senior — c'est le modèle de collaboration réel. Pas "l'IA écrit votre code", mais "comment plusieurs agents spécialisés peuvent compresser un cycle feature complet sans sacrifier les invariants qui vous ont pris des années à construire".

Sur ma mission actuelle (plateforme enterprise .NET 9 chez Edenred, architecture BFF + orchestrateur + HRIS, DDD + CQRS + Clean Architecture + MassTransit), j'utilise un pipeline multi-agents depuis quatre mois. Voici ce qui fonctionne réellement, et ce qui m'a explosé à la figure.

Le pipeline en un coup d'œil

┌─────────────────────────────────────────────────────────────────────┐
│                    PIPELINE MULTI-AGENTS (90 min)                   │
└─────────────────────────────────────────────────────────────────────┘

  User Story
      │
      ▼  [8 min]
  ┌──────────┐
  │  PO      │  → Gherkin + critères d'acceptation + edge cases
  │  Agent   │    (sortie : spec technique exhaustive)
  └──────────┘
      │
      │  VALIDATION HUMAINE ← vous lisez, vous challengez
      ▼  [12 min]
  ┌──────────┐
  │  Archi   │  → Structure fichiers, interfaces, contrats d'API
  │  Agent   │    (sortie : scaffold + dépendances explicites)
  └──────────┘
      │
      │  VALIDATION HUMAINE ← décision architecturale non-délégable
      ▼  [12 min]
  ┌──────────┐
  │  Red     │  → Tests xUnit RED (tous échouent, c'est voulu)
  │  Agent   │    (sortie : suite de tests couvrant spec + edge cases)
  └──────────┘
      │
      │  COMMIT red: — snapshot des tests failing
      ▼  [18 min]
  ┌──────────┐
  │  Green   │  → Implémentation minimale pour faire passer les tests
  │  Agent   │    (sortie : code qui compile + tests verts)
  └──────────┘
      │
      │  COMMIT green: — snapshot avant nettoyage
      ▼  [10 min]
  ┌──────────┐
  │ Refactor │  → Qualité sans changer le comportement
  │  Agent   │    (sortie : code propre, métriques améliorées)
  └──────────┘
      │
      │  COMMIT refactor:
      ▼  [20 min — PARALLÈLE]
  ┌──────────┬──────────┬──────────┐
  │  Review  │ Security │   Perf   │
  │  Agent   │  Agent   │  Agent   │
  └──────────┴──────────┴──────────┘
      │
      │  FIX LOOP (vous triez, vous appliquez, vous justifiez)
      ▼
  PR ready

Les instructions CLAUDE.md qui font fonctionner tout ça

Sans configuration explicite, les agents divergent. L'agent Green va "améliorer" le design pendant qu'il implémente. L'agent Refactor va ajouter des fonctionnalités non demandées. Voici les contraintes non-négociables dans mon CLAUDE.md global :

## Workflow TDD multi-agents — règles absolues

# Phases et responsabilités
- PO Agent : spec UNIQUEMENT — pas de code, pas d'architecture
- Archi Agent : structure et interfaces UNIQUEMENT — pas d'implémentation
- Red Agent : tests UNIQUEMENT — aucun fichier de production modifié
- Green Agent : implémentation MINIMALE — 0 généralisation, 0 "pour plus tard"
- Refactor Agent : qualité SANS changement de comportement — 0 fonctionnalité ajoutée
- Review/Security/Perf : lecture SEULE — ils proposent, vous décidez

# Guardrails absolus
- Code-before-tests = delete (vérifier git diff avant chaque commit green:)
- Périmètre figé par phase : l'agent ne touche pas aux fichiers hors scope défini
- Chaque phase se termine par un commit atomique avec préfixe obligatoire
- red: | green: | refactor: | fix: — jamais de commit multi-phase

# Kill switch
- Si un agent modifie des fichiers hors périmètre → Ctrl+C immédiat
- Si green: modifie un test existant → Ctrl+C immédiat
- Si les tests passent mais git diff --stat montre >150 lignes → audit manuel

Exemple réel : l'endpoint de plafonnement de commande

Voici un exemple non-trivial : un endpoint POST /orders/{orderId}/validate-cap qui vérifie qu'une commande ne dépasse pas le plafond annuel d'un bénéficiaire, en tenant compte des commandes en cours de traitement (statut Pending) et des annulations partielles. Pas un CRUD — un vrai invariant métier.

Ce que l'agent PO produit (extrait)

Après 8 minutes, le PO Agent rend une spec Gherkin avec les cas d'usage. L'essentiel de sa valeur est dans les edge cases qu'il force à expliciter :

Scenario: Commande dépassant le plafond annuel résiduel
  Given un bénéficiaire avec plafond annuel de 800 EUR
  And des commandes validées en cours d'année de 650 EUR
  And une commande Pending de 100 EUR (non encore comptabilisée)
  When on valide une nouvelle commande de 80 EUR
  Then le résultat est Rejected
  And le motif est "CAP_EXCEEDED"
  And le résiduel disponible retourné est 50 EUR

Scenario: Commande exactement au plafond
  Given un bénéficiaire avec résiduel disponible de 80 EUR
  When on valide une commande de 80 EUR
  Then le résultat est Approved
  # Boundary condition — souvent oublié sans spec explicite

Ce que j'aurais oublié sans l'agent PO : le cas des commandes Pending non encore comptabilisées. Ce n'est pas dans la user story d'origine — c'est une conséquence métier que le PO Agent identifie en challengeant le "plafond annuel restant". Ce seul point justifie la phase.

L'agent Green et son mode d'échec principal

L'agent Green a produit une implémentation qui faisait passer tous les tests. Mais à la review, l'agent Refactor a signalé ceci : le handler implémentait directement la logique de calcul du résiduel au lieu de la déléguer à un service de domaine. Les tests passaient car ils testaient le résultat final, pas les invariants de couche.

C'est le mode d'échec le plus fréquent avec les agents Green : ils optimisent pour le vert, pas pour l'architecture. La logique métier atterrit dans le handler, le controller, ou pire — dans un helper statique. Les tests sont verts, le code est faux.

Ma contre-mesure : des tests de convention NetArchTest dans la suite d'intégration. L'agent Green ne peut pas "tricher" en mettant la logique au mauvais endroit si un test vérifie que les handlers ne contiennent pas de logique métier :

// Convention test — architecture guardrail
[Fact]
public void Handlers_ShouldNotContainDomainLogic()
{
    var result = Types.InAssembly(ApplicationAssembly)
        .That().HaveNameEndingWith("Handler")
        .ShouldNot().HaveDependencyOn("System.Math")
        .And().ShouldNot().HaveMethodCalledDirectly("CalculateCap")
        .GetResult();

    result.IsSuccessful.Should().BeTrue(
        because: "la logique de plafonnement appartient au domaine, pas aux handlers");
}

La phase de review parallèle — ce qu'elle produit vraiment

Après le commit refactor:, je lance Review + Security + Perf en parallèle. Voici un extrait réel de la sortie de l'agent Security sur la feature de plafonnement :

[Security Agent — findings]
CRITIQUE : L'endpoint POST /orders/{orderId}/validate-cap ne valide pas que l'orderId appartient au tenant de l'utilisateur authentifié. Le handler récupère la commande par ID sans vérification d'autorisation cross-tenant. Vecteur : IDOR — un utilisateur peut valider (et donc inspecter le résiduel de) la commande d'un autre bénéficiaire en devinant l'orderId.

RECOMMANDATION : Injecter le CurrentTenantId dans la query de récupération de commande. Ajouter un test : WhenOrderBelongsToAnotherTenant_ReturnsForbidden.

NON-BLOQUANT : Le champ AnnualCap est retourné dans la réponse même en cas de rejet. Selon la politique de confidentialité, exposer le plafond exact peut constituer une fuite d'information. À décider avec le PO.

Ce finding IDOR est réel — pas inventé pour l'article. L'agent Green ne l'a pas vu parce qu'il n'y avait pas de test pour ça. L'agent PO ne l'a pas spécifié parce que la user story ne parlait pas d'autorisation. C'est exactement pour ça que la phase Security est non-optionnelle.

Quand les agents sont en désaccord

Le cas classique : l'agent Review dit "extraire cette logique dans une classe séparée", l'agent Refactor l'avait déjà intégrée inline en justifiant "trop peu de code pour mériter une classe". Qui a raison ?

Personne — et c'est exactement là que vous intervenez. Ma règle de résolution :

• Désaccord sur le style (naming, inline vs extract) → CLAUDE.md tranche, pas moi. Si ce n'est pas dans CLAUDE.md, je l'ajoute et je décide une fois pour toutes.
• Désaccord sur la sécurité vs performance (ajouter une vérification d'authz vs éviter une requête DB) → la sécurité gagne toujours, sans discussion.
• Désaccord sur l'architecture (le Review Agent propose de changer la structure de couche) → je refuse. Les décisions architecturales ne se prennent pas dans un fix loop.

Un désaccord entre agents sur l'architecture est un signal : soit le périmètre de la feature était mal défini, soit l'architecture a besoin d'évoluer — mais pas dans ce pipeline, pas maintenant.

Le kill switch : quand reprendre la main

Il y a quatre situations où j'arrête le pipeline et reprends le clavier :

1. L'agent modifie des fichiers hors périmètre. Si l'agent Green touche à un handler existant pour "améliorer" quelque chose, c'est un Ctrl+C immédiat. L'agent optimise localement ; vous gérez le système.

2. Les tests passent mais le modèle de domaine est faux. Les noms de classe ne correspondent pas au langage ubiquitaire. Le domaine s'appelle "Bénéficiaire" et l'agent a créé UserCapService. Les tests sont verts, le code est mensonger.

3. L'agent Security signale un contournement délibéré. L'agent Green a parfois tendance à "simplifier" les vérifications d'autorisation pour que les tests passent plus vite. Si la sortie Security mentionne un contournement, c'est une régression de sécurité introduite par l'IA elle-même.

4. La couverture est artificielle. Si git log --oneline montre que les commits red: et green: ont le même timestamp à quelques secondes près, l'agent a probablement écrit les tests après le code. Contre-mesure : vérifier que le commit red: fait échouer les tests avant de lancer la phase Green.

Breakdown temporel réel

• PO Agent — 8 min (dont 3 min de votre validation/challenge)
• Archi Agent — 12 min (dont 5 min de votre décision sur les interfaces)
• Red Agent — 12 min (scaffolding pur — vous vérifiez que tous les tests échouent)
• Green Agent — 18 min (implémentation + debug si un test résiste)
• Refactor Agent — 10 min (vous supervisez — pas de fonctionnalité ajoutée)
• Review + Security + Perf (parallèle) — 20 min (8 min d'exécution + 12 min de triage des findings)
• Fix loop — 10 min (en moyenne 3-4 findings actionnables)
• Total — ~90 minutes pour une feature de complexité moyenne

Le vrai gain n'est pas dans la vitesse des agents — c'est dans l'élimination du coût de commutation cognitive. Sans pipeline, vous passez de la spec au code à la review à la sécurité en portant tout le contexte dans votre tête. Avec le pipeline, chaque phase est atomique et documentée.

Ce que ce pipeline ne résout pas

Je vais être honnête sur les limites. Le pipeline ne remplace pas la modélisation du domaine — aucun agent ne peut décider que "plafond annuel" est un Value Object ou une propriété de l'agrégat. Ce choix a des conséquences sur trois ans et demande une compréhension métier réelle.

Il ne remplace pas non plus la lecture des signaux faibles. Quand l'agent Green introduit un await Task.WhenAll() "pour optimiser", il ne sait pas que votre base de données Oracle ne supporte pas les transactions parallèles sur cet agrégat. Vous le savez.

Enfin, il ne remplace pas la décision d'arrêter. Parfois la user story est mal découpée, l'architecture cible n'est pas encore stabilisée, ou les prérequis métier sont contradictoires. Le pipeline vous le signale plus tôt — mais c'est vous qui décidez d'abort.

"Le pipeline multi-agents compresse le cycle de delivery. Il ne remplace pas le jugement — il le libère pour les décisions qui comptent vraiment."

Pour aller plus loin

Si vous voulez mettre en place ce workflow, commencez par une seule chose : séparer vos commits par phase. Même sans agents, le fait de committer red: avant d'écrire une ligne de production vous force à clarifier ce que vous construisez avant de le construire. Les agents viennent ensuite — la discipline vient d'abord.

Le CLAUDE.md complet que j'utilise en production est disponible sur demande. Il couvre les 27 skills agents, les guardrails par phase, et les règles de style C# non-négociables qui empêchent les agents de polluer votre base de code avec leurs propres conventions.