De l'user story au design
technique en 30 minutes
avec des agents IA spécialisés

La phase de planning n'est pas lente parce que le travail est difficile. Elle est lente parce que le processus est manuel, non structuré, et parce qu'on saute des étapes quand on est pressé. J'ai perdu des sprints entiers à cause d'une user story mal décortiquée — des hypothèses implicites, des cas limites non documentés, des décisions d'architecture prises dans le brouillard de la réunion de sprint. Tout senior dev a cette cicatrice. Ce que j'ai trouvé avec un pipeline de trois agents IA spécialisés, c'est non pas une IA qui remplace la réflexion, mais une IA qui impose la discipline que l'on s'autoriserait à sauter quand on est pressé.

La session de planning typique : où les heures disparaissent

Voici ce qui se passe en réalité dans la plupart des équipes. Un ticket Jira arrive avec une description de deux lignes et trois acceptance criteria vagues. Le développeur lit le ticket, a cinq questions, envoie un message Slack au PO. Le PO est en réunion, répond le lendemain avec deux précisions qui en soulèvent trois nouvelles. Une réunion de 30 minutes est planifiée. Pendant cette réunion, les deux tiers des décisions importantes sont prises oralement et ne sont jamais documentées. Le développeur commence à coder avec une compréhension partielle. Deux jours plus tard, en PR review, le Tech Lead découvre que le comportement implémenté ne correspond pas à ce que le PO avait en tête — mais ni l'un ni l'autre ne peut pointer vers un document qui aurait clarifié l'ambiguïté, parce que ce document n'existe pas.

La vraie durée d'un planning non structuré n'est pas la réunion de 30 minutes. C'est la réunion + les allers-retours Slack + la PR review étendue + le correctif + la re-livraison. Soit souvent 3 à 4 heures de travail distribué sur plusieurs jours.

Le pipeline 3 agents : architecture et rôles

Le principe est celui de la séparation des responsabilités appliqué à la phase d'analyse. Trois agents spécialisés, chacun avec un contexte précis et un output structuré, qui se chaînent. Chaque agent prend l'output du précédent en entrée, l'enrichit, et passe au suivant.

Agent 1 — Le PO Agent

Il prend une user story brute — aussi vague soit-elle — et produit une spec d'une page directement exploitable en code review. Son travail n'est pas de deviner les règles métier : c'est de forcer la structure que vous auriez dû formaliser de toute façon.

L'output du PO Agent contient systématiquement :

• Critères d'acceptation précis — rédigés comme des contraintes vérifiables, pas comme des intentions
• Scénarios Gherkin — minimum 3, maximum 5, avec happy path, cas limites et cas d'erreur
• Cas limites explicites — ce qui se passe quand les données sont nulles, vides, hors bornes
• Exigences non-fonctionnelles — performance, sécurité, pagination si applicable
• Hors-scope documenté — ce que la story ne couvre pas, pour éviter le scope creep en cours de dev

Agent 2 — L'Architecture Agent

Il prend la spec du PO Agent et lit la structure du projet pour proposer le design technique. Il ne lit pas tout le code — il lit les contrats : les interfaces publiques, les namespaces, les dépendances entre couches. Sur une base .NET Clean Architecture, c'est précis et rapide.

L'output de l'Architecture Agent contient :

• Liste de fichiers à créer ou modifier — avec leur couche (API, Application, Infrastructure, Domain) et leur responsabilité
• Patterns à appliquer — Command/Handler vs Query/Handler, event de domaine vs appel direct, nouveau Value Object vs propriété simple
• Décisions avec rationale — pourquoi ce pattern ici, quelle alternative a été écartée et pour quelle raison
• Breaking changes à surveiller — changements de contrat API ou d'événements de domaine qui impactent d'autres équipes

Agent 3 — Le Plan-writer

Il prend la spec et l'architecture, et produit une liste ordonnée de tâches de 2 à 5 minutes chacune, structurée en cycles Red → Green → Refactor. Le développeur peut exécuter cette liste sans se demander "quelle est la prochaine étape" — c'est le Plan-writer qui a résolu ce problème en amont.

Quand une tâche du plan-writer dépasse mentalement les 5 minutes à l'estimation, c'est un signal : soit la spec n'est pas assez découpée, soit l'architecture n'est pas assez précise. Le Plan-writer révèle les manques des étapes précédentes.

Exemple bout en bout : export Excel par centre de coût

Voici la story brute telle qu'elle arrive dans le backlog :

Story brute — input du pipeline
────────────────────────────────
En tant que responsable facturation,
je veux exporter un récapitulatif mensuel de factures
au format Excel groupé par centre de coût,
afin de pouvoir l'envoyer à la comptabilité sans retraitement manuel.

Notes PO : "comme l'export CSV existant mais en Excel avec des onglets"
Priorité : haute — demandée par 3 clients grands comptes

Trois lignes, une comparaison vague avec un autre outil, aucun critère d'acceptation. C'est la réalité quotidienne. Voici ce que le PO Agent produit :

Output PO Agent — spec structurée
──────────────────────────────────
CRITÈRES D'ACCEPTATION
AC1 : Le fichier généré est un .xlsx valide (format Office Open XML)
AC2 : Chaque centre de coût correspond à un onglet nommé avec le code du centre de coût
AC3 : Chaque onglet contient les colonnes : Date facture | Référence | Fournisseur | Montant HT | TVA | Montant TTC
AC4 : Les lignes sont triées par date de facture ascendante dans chaque onglet
AC5 : Le nom du fichier suit le pattern : recap-factures-{YYYY-MM}-{userId}.xlsx
AC6 : Si aucune facture n'existe pour un centre de coût sur la période, l'onglet est absent (ne pas créer un onglet vide)
AC7 : La génération est limitée à un mois calendaire — les requêtes multi-mois sont rejetées avec HTTP 400

SCÉNARIOS GHERKIN

Scenario: Export standard avec plusieurs centres de coût
  Given un responsable facturation authentifié avec accès aux centres de coût CC01 et CC03
  And des factures existent pour CC01 (3 factures) et CC03 (1 facture) en mars 2026
  When il demande l'export pour la période 2026-03
  Then le fichier recap-factures-2026-03-{userId}.xlsx est retourné
  And le fichier contient exactement 2 onglets nommés "CC01" et "CC03"
  And l'onglet CC01 contient 3 lignes de données (hors en-tête)
  And les lignes de CC01 sont triées par date ascendante

Scenario: Centre de coût sans facture sur la période
  Given un responsable facturation avec accès aux centres CC01, CC02 et CC03
  And aucune facture n'existe pour CC02 en mars 2026
  When il demande l'export pour 2026-03
  Then le fichier ne contient pas d'onglet "CC02"
  And les onglets CC01 et CC03 sont présents normalement

Scenario: Requête sur une plage multi-mois rejetée
  Given un responsable facturation authentifié
  When il demande l'export avec dateDebut=2026-01-01 et dateFin=2026-03-31
  Then la réponse est HTTP 400
  And le corps contient "La génération est limitée à un seul mois calendaire"

Scenario: Aucune facture sur la période demandée
  Given un responsable facturation authentifié
  And aucune facture n'existe pour ses centres de coût en avril 2026
  When il demande l'export pour 2026-04
  Then la réponse est HTTP 204 (No Content)
  And aucun fichier n'est retourné

Scenario: Responsable sans accès à un centre de coût
  Given un responsable facturation avec accès uniquement à CC01
  When il demande un export incluant le centre CC99
  Then la réponse est HTTP 403
  And l'audit log enregistre la tentative d'accès non autorisé

HORS-SCOPE (cette story)
- Mise en forme conditionnelle ou graphiques dans le fichier Excel
- Export de plusieurs mois en un seul fichier
- Envoi automatique par email à la comptabilité
- Filtrage par fournisseur ou par seuil de montant

EXIGENCES NON-FONCTIONNELLES
- Génération en moins de 5 secondes pour jusqu'à 500 lignes par onglet
- Le fichier est streamé directement en réponse HTTP — pas de stockage intermédiaire
- L'endpoint requiert le rôle BillingManager

Cette spec est rédigée en 4 minutes. Elle peut aller directement dans le ticket Jira et servir de base à la PR review. L'Architecture Agent reçoit cette spec et l'output suivant :

Output Architecture Agent — design technique
─────────────────────────────────────────────
FICHIERS À CRÉER

src/Api/BillingExports/
  ExportMonthlyInvoiceSummary.cs         — Request + Response (record, [Spannable])
  ExportMonthlyInvoiceSummaryController.cs — endpoint GET /billing/exports/monthly

src/Application/BillingExports/
  ExportMonthlyInvoiceSummaryQuery.cs    — Query record avec Mois (YearMonth value object)
  ExportMonthlyInvoiceSummaryHandler.cs  — IRequestHandler
  MonthlySummaryRow.cs                   — DTO interne (date, ref, fournisseur, HT, TVA, TTC)

src/Infrastructure/BillingExports/
  BillingExportService.cs                — IBillingExportService (interface en Application)
  ExcelMonthlySummaryGenerator.cs        — génération du .xlsx via ClosedXML

FICHIERS À MODIFIER

src/Application/BillingExports/
  → Créer IBillingExportService.cs (interface + contrat du service infra)

src/Infrastructure/DependencyInjection.cs
  → Enregistrer ExcelMonthlySummaryGenerator comme IBillingExportService

PATTERNS APPLIQUÉS

Query/Handler (MediatR) — pas Command : pas d'effet de bord sur l'état du domaine
  Rationale : un export est une lecture — Command serait sémantiquement incorrect
              et rendrait le handler non testable via QueryBus

Value Object YearMonth — pas DateTime pair (début/fin)
  Rationale : AC7 impose une contrainte métier "un seul mois calendaire"
              YearMonth encode cette contrainte dans le type → impossible de créer
              une requête multi-mois ; rejet par le constructeur, pas par validation ad hoc

Stream direct en réponse — pas de IFormFile ou base64
  Rationale : NFR "pas de stockage intermédiaire" → FileStreamResult depuis le handler
              évite d'allouer un byte[] complet en mémoire pour les gros exports

BREAKING CHANGES
  Aucun — nouvel endpoint, pas de modification de contrats existants

DÉPENDANCES À AJOUTER
  ClosedXML (NuGet) → projet Infrastructure uniquement

Le Plan-writer reçoit la spec et l'architecture et produit le checklist d'implémentation :

Output Plan-writer — checklist TDD Red → Green → Refactor
──────────────────────────────────────────────────────────
[ ] RED  — Test YearMonth : constructeur accepte mois valide (2026-03)
[ ] RED  — Test YearMonth : constructeur lève ArgumentException si jour != 1er du mois
[ ] RED  — Test YearMonth : constructeur lève ArgumentException si mois dans le futur
[ ] GREEN — Implémenter YearMonth value object (record, validation en constructeur)

[ ] RED  — Test Handler : retourne 204 si aucune facture sur la période
[ ] RED  — Test Handler : retourne FileResult avec nom correct pour happy path
[ ] RED  — Test Handler : retourne FileResult avec un onglet par centre de coût distinct
[ ] RED  — Test Handler : retourne FileResult sans onglet si centre de coût sans facture
[ ] RED  — Test Handler : lève UnauthorizedAccessException si centre de coût hors accès
[ ] GREEN — Implémenter ExportMonthlyInvoiceSummaryHandler (stub IBillingExportService)

[ ] RED  — Test ExcelMonthlySummaryGenerator : fichier .xlsx valide parseable par ClosedXML
[ ] RED  — Test ExcelMonthlySummaryGenerator : 1 onglet par centre de coût distinct
[ ] RED  — Test ExcelMonthlySummaryGenerator : lignes triées par date ascendante dans chaque onglet
[ ] RED  — Test ExcelMonthlySummaryGenerator : colonnes dans l'ordre défini par AC3
[ ] GREEN — Implémenter ExcelMonthlySummaryGenerator

[ ] REFACTOR — Extraire la logique de nommage des onglets en méthode privée nommée
[ ] REFACTOR — Vérifier qu'aucun stream n'est laissé ouvert (using / MemoryStream)

[ ] RED  — Test Controller : route GET /billing/exports/monthly?mois=2026-03 → 200 + Content-Disposition
[ ] RED  — Test Controller : mois multi-mois → 400 avec message AC7
[ ] GREEN — Implémenter ExportMonthlyInvoiceSummaryController

[ ] Enregistrer IBillingExportService → ExcelMonthlySummaryGenerator dans DI
[ ] Ajouter [Spannable] sur Request et Response
[ ] rtk dotnet build + rtk dotnet test — tous verts avant commit

La porte qualité : challenger les outputs avant de coder

Le pipeline produit de la structure, pas de la vérité. Avant de commencer l'implémentation, je passe 8 à 10 minutes à valider chaque output avec une liste de questions standardisées.

Pour le PO Agent : les scénarios Gherkin sont-ils tous testables automatiquement ? Y a-t-il un scénario qui suppose une règle métier que je n'ai pas en contexte ? Le "hors-scope" contient-il quelque chose qui devrait être dans scope (signal : si le PO humain lit le hors-scope et dit "ah mais ça on en a besoin pour le MVP") ?

Pour l'Architecture Agent, la liste rouge :

• Nouvel agrégat non anticipé — arrêt immédiat. Soit le domaine est plus riche qu'attendu, soit l'agent hallucine de la complexité. Une conversation de 5 minutes avec le PO humain est obligatoire.
• Dépendance circulaire entre couches — l'agent propose parfois d'ajouter une référence Infrastructure → Application ou Domain → Infrastructure. Rejet systématique.
• Trop de fichiers créés pour une story simple — plus de 10 fichiers pour une story "moyenne" est un signal que la story devrait être découpée.
• Pattern proposé qui ne correspond pas au vocabulaire du domaine — si l'agent propose un "ExportService" dans une base de code où tout est "Handler", questionner pourquoi.

Pour le Plan-writer : une tâche qui prend mentalement plus de 5 minutes signifie que l'étape précédente n'a pas été assez précise. Je retourne au PO Agent ou à l'Architecture Agent pour affiner avant de continuer.

Ce que les agents ne savent pas — et c'est important

Je préfère être direct sur les limites, parce que c'est là que les équipes se font piéger.

Les règles métier implicites. Le PO Agent a produit la spec sur la base de la story et des conventions du projet. Mais il ne sait pas que le centre de coût CC-HOLDING suit des règles TVA différentes des autres centres, parce que cette règle est dans la tête du contrôleur de gestion et n'a jamais été documentée. Ces règles apparaissent au moment de la recette — pas avant. La seule mitigation : pointer vers les règles métier quand elles existent quelque part dans la documentation, et s'assurer que le PO humain relit la spec avant implémentation.

Les contraintes politiques. L'Architecture Agent propose d'utiliser ClosedXML. Si votre organisation a une décision d'architecture qui impose EPPlus pour raisons de licence, l'agent ne le sait pas. Le contexte politique et contractuel reste une connaissance humaine.

La dette technique localisée. L'agent lit les interfaces et les namespaces. Il ne lit pas les commentaires "TODO: refactorer avant d'ajouter une feature ici" qui traînent dans le code depuis 6 mois. Il peut vous diriger vers un fichier qui va rendre l'implémentation trois fois plus complexe que prévu — sans vous prévenir.

L'histoire du pourquoi. Pourquoi ce module utilise-t-il un pattern différent des autres ? Parce qu'il y a eu un incident en production il y a deux ans et une contrainte a été ajoutée. L'agent voit le résultat, pas la cause. Cette connaissance contextuelle du système vivant reste le domaine du Tech Lead humain.

Découpage du temps : les 30 minutes en détail

Voici la réalité d'un passage complet, sans accélérer ni tricher :

• 5 min — PO Agent : input de la story brute, génération de la spec structurée
• 3 min — Revue humaine de la spec : valider les Gherkin, corriger les règles métier manquantes, ajuster le hors-scope
• 5 min — Architecture Agent : input de la spec, lecture de la structure du projet, génération des décisions
• 5 min — Revue humaine de l'architecture : vérifier les patterns, challenger les nouveaux agrégats, valider les dépendances
• 10 min — Plan-writer : input de la spec + archi, génération du checklist TDD
• 2 min — Vérification finale : toutes les tâches correspondent à un critère d'acceptation ? Le checklist est exhaustif sans être redondant ?

Total : 30 minutes. Versus la session habituelle de 2 à 3 heures distribuées sur 2 jours. La différence n'est pas que les agents sont plus intelligents — c'est qu'ils refusent de sauter des étapes. Ils ne vont pas plus vite parce qu'ils sont pressés. Ils ne simplifient pas les Gherkin parce que la réunion tire en longueur. La structure est non-négociable.

"Les agents ne pensent pas à votre place. Ils vous forcent à penser à des endroits où vous vous seriez autorisé à ne pas penser parce que vous étiez en retard."