BiblioCQRS — Épisode 2 : Remettre l’IA à l’école du métier (IREB)

Tag de référence : Second_IT — commit « feat: add barcode support and enhance domain logic »

Dans l’épisode 1, l’IA avait montré sa première limite : livrée à elle-même, elle code tout, tout de suite, sans discipline d’itération. La parade trouvée était mécanique — découper en baby steps. Mais un baby step mal cadré reste un pas dans la mauvaise direction. L’épisode 2 raconte ce qui s’est passé quand on a arrêté de corriger l’IA au fil de l’eau pour, en amont, lui imposer un cadre méthodologique complet : l’ingénierie des exigences (IREB).

1. Le symptôme : une bonne idée, mal posée

Le Product Owner annonce vouloir cadrer la feature suivante : l’emprunt. Premier réflexe à corriger : ne pas sauter dans le code. La bascule de posture est immédiate — passage explicite en rôle de Business Analyst, avec un principe directeur simple, mais que l’IA ne respecte jamais spontanément :

Séparer l’espace du problème (le métier, la bibliothèque réelle) de l’espace de la solution (le logiciel BiblioCQRS).

C’est tout le sujet de cet épisode : sans ce garde-fou, l’IA confond en permanence « ce que fait la bibliothèque » et « ce que doit faire le programme ».

2. Schéma n°1 — Qui sont les parties prenantes, et que veulent-elles vraiment ?

Premier travers observé : une cartographie des parties prenantes plate, sans hiérarchie ni tension d’intérêts. Recadrage du PO, réponse en deux temps : un diagramme relationnel, puis une matrice attentes / risques / ROI.

flowchart TD
    DIR[Direction de la Bibliothèque]
    BIB[Bibliothécaire / Documentaliste]
    US[Usager / Adhérent]
    DIR -->|" Lien hiérarchique / Employeur "| BIB
    DIR -->|" Recherche la satisfaction "| US
    BIB -->|" Accompagne et sert "| US

Partie Prenante	Attentes	Risques	ROI
Direction Bibliothèque	Statistiques fiables, respect du règlement	Perte financière (vols), mécontentement usager	Pilotage par la donnée (CQRS Query)
Bibliothécaire	Outil rapide, fiable	Complexité, perte de temps au guichet	Gain de temps, moins de stress opérationnel
Adhérent	Emprunter vite, règles transparentes	Oubli des dates, blocage injustifié	Expérience fluide, accès garanti

Ce tableau n’est pas du remplissage : c’est lui qui, plus tard, justifie pourquoi certaines règles métier (quota, tolérance de retard) doivent exister — elles découlent directement du risque identifié ici pour la Direction et le Bibliothécaire.

3. Schéma n°2 — Ne pas confondre la bibliothèque et le logiciel

Deuxième erreur typique de l’IA : elle dessine un système où l’usager « interagit » avec le logiciel comme s’il empruntait directement un livre depuis une interface. Le PO recadre : le système informatique n’a jamais vu un livre. Il n’existe qu’à travers la saisie du bibliothécaire.

flowchart TD
    subgraph Metier ["La Bibliothèque (Système Métier)"]
        US((Usager))
        BIB((Bibliothécaire))
        LIVRE[Exemplaires Physiques]
        US -->|" Rend / Emprunte physiquement "| LIVRE
        US -->|" Demande au guichet "| BIB
    end

    subgraph Solution ["Périmètre de la Solution"]
        BiblioCQRS[Système Informatique BiblioCQRS]
    end

    BIB -->|" Saisie des actes (Emprunts, Retours, Catalogue) "| BiblioCQRS
    US -.->|" Notifications / Consultation (Futur) "| BiblioCQRS

C’est un schéma trivial en apparence. Mais c’est précisément le genre de nuance qu’une IA, optimisant pour « produire un diagramme plausible », efface en premier si on ne le lui impose pas explicitement.

4. Une lacune trouvée en creusant : l’exemplaire sans identité

En posant le scénario nominal d’emprunt (le documentaliste fournit l’ID de l’exemplaire et l’ID de l’adhérent), le PO pose une question simple qui fait tout basculer :

« Est-ce que ta documentation fait ressortir que actuellement les exemplaires n’ont pas d’ID explicite ? »

Réponse honnête : non. Le système existant ne permettait pas de distinguer quel exemplaire physique précis était emprunté. Ce n’est pas un détail — sans identifiant, aucune règle de prêt n’est implémentable. La discipline IREB paie immédiatement : on documente le manque (Plan d’Élicitation) plutôt que de le corriger en douce dans le code, et on crée une User Story dédiée (US-CAT-03 : identifier un exemplaire par un ID explicite, code-barre ou RFID).

Conséquence directement visible dans le commit Second_IT : « feat: add barcode support and enhance domain logic ». L’écart documenté précède le code, pas l’inverse.

5. Schéma n°3 — De l’objectif métier au cas d’utilisation

Autre recadrage du PO : l’arbre des objectifs ne parlait pas le même langage que le backlog (pas d’Epic en commun). Mise en cohérence stricte Objectif Entreprise → Epic → Use Case.

mindmap
  root((Exploiter une bibliothèque))
    Epic 1_ Gestion du Catalogue
      Référencer un nouvel ouvrage abstrait
      Ajouter un exemplaire physique
      Identifier un exemplaire par ID
    Epic 2_ Gestion des Adhérents
      Inscrire un adhérent
    Epic 3_ Gestion des Prêts
      Enregistrer un emprunt
      Enregistrer un retour

flowchart LR
    Actor((Bibliothécaire))

    subgraph "Gestion du Catalogue"
        direction TB
        UC1([Référencer un nouvel ouvrage abstrait])
        UC2([Ajouter un exemplaire physique])
    end

    subgraph "Gestion des Prêts"
        direction TB
        UC3([Enregistrer un emprunt])
        UC4([Inscrire un adhérent])
    end

    Actor --> UC1
    Actor --> UC2
    UC2 -. " << require >> " .-> UC1
    Actor --> UC3
    Actor --> UC4
    UC3 -. " << require >> " .-> UC4
    UC3 -. " << require >> " .-> UC2

Les flèches << require >> ne sont pas cosmétiques : elles formalisent que l’on ne peut pas enregistrer un emprunt sans qu’un exemplaire et un adhérent existent déjà. Sans ce schéma, rien n’empêchait l’IA de générer un endpoint d’emprunt totalement déconnecté du reste du domaine.

6. L’erreur de persona : quand « le Système » devient acteur

Le recadrage le plus instructif de l’itération porte sur l’écriture des User Stories. L’IA avait rédigé des US de blocage (« Quota atteint », « Trop de retards ») avec, en persona, le Système. Le PO arrête tout :

Le « Système » ne peut pas être l’acteur d’une User Story, car il ne retire aucune valeur métier. L’US doit se placer du point de vue de l’acteur opérationnel.

Correction : les US sont réécrites du point de vue du Documentaliste, qui veut être empêché de réaliser l’emprunt, afin de garantir l’équité d’accès aux ressources (quota) et la bonne circulation des ouvrages (retards). Un changement de sujet grammatical, en apparence anodin, qui force en réalité à exprimer la valeur métier — exactement ce que l’IA, focalisée sur la fonctionnalité technique, avait omis.

7. Restructurer plutôt qu’empiler

Documentation jugée trop monolithique → éclatement en cinq fichiers spécialisés sous docs/requirements/ : vision/contexte, glossaire (langage omniprésent), scénarios/règles, plan d’élicitation, backlog. Chaque fichier a une responsabilité unique — la même logique de séparation des préoccupations qu’on applique au code, appliquée à la documentation.

8. Granularité sémantique : Business Case, Use Case, User Story

Dernier recadrage, le plus fin : le PO rejette le verbe « Gérer » (« Gérer les emprunts »), jugé trop fourre-tout, et distingue :

le Business Case : le processus métier de bout en bout (« Opérer un prêt ») ;
le Use Case : l’interaction unitaire d’un acteur avec le système à un instant T (« Prendre en compte un emprunt », « Effectuer une restitution ») — documentation pérenne ;
la User Story : un artefact de planification éphémère, qui disparaît une fois implémentée.

Conséquence concrète : le domaine des prêts, qu’on s’apprêtait à coder comme un seul « gérer l’emprunt », est décomposé en deux Use Cases temporels distincts. C’est exactement le genre de découpage qui, en aval, évite à l’IA de recréer le piège de l’épisode 1 — un agrégat qui voudrait tout faire d’un coup.

9. Industrialiser le recadrage : des skills, pas des répétitions

Répéter les mêmes corrections à chaque conversation n’est pas un cadrage, c’est une fuite en avant. Le PO pose la question qui clôt l’itération côté méthode :

Comment pérenniser toutes ces règles (pas de persona « Système », traçabilité IREB, historique automatique) pour ne plus avoir à les répéter à l’avenir ?

Réponse : la création d’un skill business-analyst-ireb, qui encapsule ces règles d’or et les rend réutilisables à la demande, sur n’importe quel futur cadrage. Puis, au moment de basculer en réalisation, un second skill, techlead-bdd-tdd, fige cette fois la méthodologie de code : Double Loop TDD (BDD à l’extérieur, TDD strict à l’intérieur), Clean Architecture, TDA, YAGNI.

flowchart LR
    A[Scénario Gherkin] -->|Rouge| B[Step Definitions]
    B --> C{Domaine seul<br/>pas de Spring, pas de DB}
    C -->|TDD interne: Red/Green/Refactor| D[Code de production]
    D --> E[Scénario BDD Vert]

10. Ce que ça change par rapport à l’épisode 1

L’épisode 1 concluait : « c’est au développeur de l’arrêter ». L’épisode 2 va plus loin : il ne s’agit plus seulement de freiner l’IA en cours de route, mais de lui donner, en amont, une grammaire métier suffisamment rigoureuse pour qu’elle n’ait plus l’occasion de dériver. Chaque recadrage du PO — parties prenantes, frontière métier/logiciel, identité des exemplaires, traçabilité Epic → UC, persona des US, granularité Business Case / Use Case / US — n’est pas une correction ponctuelle : c’est une règle qui survit, encapsulée dans un skill, au-delà de la conversation qui l’a fait naître.

Le commit Second_IT est la preuve par le code que ce travail de cadrage n’était pas que de la paperasse : le support code-barre de l’exemplaire, repéré comme lacune dès l’étape 3 de l’atelier, est livré et testé (tests d’intégration sur OuvrageRepositoryAdapter et OuvrageCommandController).

11. Le backlog priorisé (US-CAT, US-ADH, US-PRT)

Voici le backlog tel qu’issu de l’atelier, traduit en tableau après le recadrage sur la modularité documentaire (étape 4). Les User Stories de blocage (US-PRT-02, US-PRT-03) sont déjà écrites du point de vue du Documentaliste, conformément au recadrage sur les personas (section 6) :

ID	Epic	En tant que…	Je veux…	Afin de…	Statut
US-CAT-01	Catalogue	Bibliothécaire	Ajouter une référence abstraite (ISBN, Titre, Auteur)	Préparer le catalogue pour recevoir des exemplaires	Implémenté
US-CAT-02	Catalogue	Bibliothécaire	Ajouter un exemplaire physique pour un ouvrage donné	L’intégrer au stock empruntable	Implémenté
US-CAT-03	Catalogue	Bibliothécaire	Saisir l’identifiant unique (code-barre/RFID) lors de l’ajout d’un exemplaire	Permettre sa traçabilité individuelle physique	Implémenté (`Second_IT`)
US-ADH-01	Adhérents	Documentaliste	Enregistrer un nouvel adhérent dans le système	Lui permettre de commencer à emprunter	À faire
US-PRT-01	Prêts	Documentaliste	Enregistrer un emprunt nominal d’un exemplaire à un adhérent	Lui confier l’ouvrage pour 3 semaines (géré par le système)	À faire
US-PRT-02	Prêts	Documentaliste	Être bloqué si je tente d’enregistrer un emprunt pour un adhérent ayant atteint son quota (5)	Garantir que tous les adhérents puissent accéder à un choix d’ouvrages riche	À faire
US-PRT-03	Prêts	Documentaliste	Être bloqué si je tente d’enregistrer un emprunt pour un adhérent avec > 1 livre en retard	Favoriser le retour rapide des exemplaires en circulation	À faire

Trois lignes seulement passent au vert dans cette itération : US-CAT-01, US-CAT-02 et US-CAT-03, la dernière étant directement la traduction de la lacune débusquée à l’étape 4 (l’exemplaire sans identité). Le reste — adhérents et prêts — reste cadré mais non codé : c’est tout l’objet de l’épisode 3.

12. La matrice CRUD de ce qui est réellement implémenté

La matrice de traçabilité ci-dessous reprend la documentation d’architecture (01_use_cases_crud.md). Seul UC-CAT-01 (Référencer un ouvrage), en gras, correspond à du code livré dans Second_IT ; les lignes liées aux Prêts (en italique dans la doc projet) restent des cas d’usage anticipés, pas encore couverts par une seule ligne de domaine :

Entité Informationnelle	Cas d’Usage (UC)	C (Create)	R (Read)	U (Update)
Ouvrage	UC-CAT-01 (Référencer un ouvrage) — implémenté	X (Création)	X (Validation unicité)	X (Ajout exemplaire)
	UC-PRT-01 (Prendre en compte emprunt) — futur		X
Exemplaire	UC-CAT-01 (Référencer un ouvrage) — implémenté	X (Ajout physique + code-barre)
	UC-PRT-01 / UC-PRT-02 — futur		X	X (Changement statut)
Adhérent	UC-PRT-01 (Prendre en compte emprunt) — futur		X (Vérif. Quotas)
Emprunt	UC-PRT-01 (Prendre en compte emprunt) — futur	X (Créer)
	UC-PRT-02 (Effectuer restitution) — futur		X	X (Clôturer)

Seules deux entités — Ouvrage et Exemplaire — ont une colonne C/R/U réellement adossée à du code de production et des tests d’intégration (OuvrageRepositoryAdapterTest, OuvrageCommandControllerTest). Le reste de la matrice, en italique, documente déjà l’attendu pour ne pas repartir d’une page blanche au prochain épisode — c’est l’IREB qui prépare le terrain avant que l’IA ne touche au code.

Pour la suite

Épisode 3 : la bascule en TechLead. Comment le Double Loop TDD a été appliqué à la couche infrastructure pour boucler la tranche verticale du domaine — et ce que l’IA, livrée au code cette fois avec un cadre métier solide derrière elle, a fait de mieux (et de moins bien) que dans l’épisode 1.