ÉTUDE D’ARCHITECTURE · Cohérence
Utiliser l'IA comme moteur de cohérence pour le travail d'architecture
Les exemples utilisent les mécanismes de Salesforce Commerce Cloud. Le raisonnement vaut pour toute plateforme de commerce de cette taille. Le générateur de TSD de ce site est cette idée, construite comme un outil utilisable.
Pourquoi c'est important
Les décisions d'architecture sont écrites pour qu'une équipe puisse construire à partir d'elles. Quand plusieurs personnes rédigent ces documents à la main, ils sortent différents à chaque fois, et des sections disparaissent discrètement. Une section manquante n'est pas un problème de rédaction. C'est ainsi qu'un risque arrive en production sans que personne ne le remarque.
La décision — Fixer la structure du document, pas les mots. Laisser un assistant produire un premier brouillon dans cette forme fixe, et garder chaque jugement chez l'architecte.
Ce que cela apporte — Chaque conception examine les mêmes questions : paiements, consentement, cas de panne, contrats d'intégration. La partie lente — la page blanche — devient la partie rapide.
Le risque évité — Une conception qui saute en silence la section qui aurait détecté le problème, parce que rien n'a invité l'auteur à y penser.
En une phrase : on ne peut pas convaincre un modèle de ne pas poser la question difficile, alors encodez les questions et laissez l'assistant remplir la forme — mais ne le laissez jamais trancher.
Le problème
Un document de conception technique décrit comment une chose sera construite, et pourquoi. Rédigés par plusieurs personnes au fil du temps, ces documents divergent. Structure différente, niveau de détail différent, et parfois une section importante — paiements, consentement, comportement en cas de panne — est simplement absente.
L'incohérence est le vrai problème, et il est facile de mal la diagnostiquer. Si une conception traite les cas de panne et que la suivante ne le fait pas, la deuxième équipe n'est en général pas négligente. Rien ne l'a invitée à y penser. Rien devant elle ne posait la question.
C'est donc un problème de gouvernance plutôt que de rédaction. On ne le corrige pas en demandant aux gens de faire plus attention, car l'échec est silencieux : personne ne remarque la section qui n'est pas là.
La question qui structure la conception
Demandez ce qu'il est réellement sûr d'automatiser.
La structure est sûre. Elle est la même à chaque fois. Une conception pour une fonctionnalité de fidélité et une conception pour une intégration de paiement demandent que les mêmes questions soient posées, même si les réponses diffèrent complètement. On ne perd rien à la fixer.
Le jugement ne l'est pas. Garder un appel synchrone ou non, quel marché passe en premier, que faire quand un système partenaire est indisponible — ce sont des décisions à conséquences, et elles appartiennent à une personne qui peut en répondre.
La conception en découle : automatiser la première, refuser d'automatiser la seconde.
L'approche
Un modèle réutilisable en Markdown qui définit chaque section qu'une conception doit couvrir. Une seule exigence peut alors produire un premier brouillon complet dans cette forme, avec un assistant comme GitHub Copilot.
Le mécanisme qui fait fonctionner l'ensemble est simple : chaque section que l'auteur n'a pas écrite porte une note visible indiquant ce qui doit y figurer. Pas un titre suivi d'un vide — une instruction précise, dans le fichier, sur laquelle un assistant peut agir et qu'un humain peut lire.
## Cache
> **Ce qu’il faut écrire ici.** Décris la stratégie de cache pour « Adhésion au
> programme de fidélité lors du paiement ». Indique ce qui est mis en cache,
> pour combien de temps, et ce qui ne doit jamais l’être parce que c’est
> personnalisé.
Cette note fait deux choses. Elle dit à l'assistant exactement quoi rédiger et — si personne n'utilise jamais d'assistant — elle dit au prochain humain à quoi sert la section. Le document est utile dans les deux cas.
Elle est volontairement visible plutôt que cachée dans un commentaire. Une instruction cachée disparaît de tous les aperçus : le fichier paraît vide à qui le parcourt, et une section que personne n'a écrite ressemble exactement à une section dont personne n'avait besoin. Laissée dans le document final, une note visible dit clairement que cette partie n'a pas encore été rédigée.
La limite la plus importante
Un assistant à qui l'on demande de remplir trente sections en remplira trente. Il produira un texte assuré et fluide pour chacune, y compris celles où il n'en sait rien.
C'est le mode d'échec que cette approche crée, et il faut le nommer plutôt que le cacher. Le fait que la structure soit automatique fait paraître le résultat uniformément réfléchi, ce qui est précisément ce qui rend dangereuse une section non relue : elle ressemble aux autres.
La discipline est donc : chaque section développée par un assistant est relue par l'auteur avant de compter comme écrite. L'outil l'indique dans le document généré lui-même, au bas de chaque fichier produit, car un avertissement qui ne vit que sur une page web est un avertissement que personne ne voit au moment où il compte.
Options envisagées
| Option | Décision | Raisonnement |
|---|---|---|
| Modèle fixe, brouillon par l'assistant, relecture par l'auteur | Retenue | On ne peut pas convaincre la structure de ne pas poser une question difficile, et le premier brouillon coûte peu. Accepte que relire un texte généré est un vrai travail, et que certaines sections seront fausses. |
| Demander aux gens d'écrire plus soigneusement | Rejetée | Traite un problème de système comme un problème de discipline. Échoue exactement dans le cas qui compte — la section à laquelle personne n'a pensé — car faire plus attention ne révèle pas un angle mort. |
| Laisser l'assistant trancher aussi les compromis | Rejetée | La version séduisante. Elle produit un document qui se lit bien et prend des positions que personne n'assume. Une conception que personne ne peut défendre en revue est pire que pas de conception. |
| Un formulaire rigide à compléter avant de commencer | Rejetée | Charge tout le document au moment où l'on en sait le moins. Certaines sections ne peuvent honnêtement être renseignées qu'une fois la réalisation entamée ; les forcer produit du remplissage, ce qui est pire qu'un manque assumé. |
Ce que je surveillerais en pratique
- Un texte fluide qui ne dit rien. L'échec caractéristique est une section grammaticale, dans le sujet, et vide de décisions. Relisez pour savoir si un choix a été fait, pas si cela se lit bien.
- Le modèle qui grossit sans fin. Chaque incident donne envie d'ajouter une section. Un modèle qui pose quatre-vingts questions finit ignoré : dimensionnez-le au changement — un petit correctif et une intégration majeure ne méritent pas le même document.
- Des sections « non applicable » sans raison. « Non applicable » est une réponse utile et honnête. « Non applicable » sans raison est une réponse non examinée : la raison doit être obligatoire.
- Le commentaire qui s'éloigne de la réalité. Le guidage est l'actif. Si un commentaire décrit une préoccupation que la plateforme n'a plus, il enseigne la mauvaise chose à tous ceux qui l'utiliseront ensuite.
- L'adoption, qui est la partie difficile. La technique est la moitié facile. Amener les gens à partir du modèle plutôt que du dernier document qu'ils ont écrit est le vrai problème, et cela se gagne en faisant du modèle le chemin le plus rapide, pas le chemin imposé.
Ce que cela apporte
- Chaque conception examine les mêmes questions : celles qui évitent les incidents en production cessent d'être facultatives.
- La page blanche — de loin la partie la plus lente — devient une relecture, plus rapide et plus facile à bien faire.
- Une équipe peut utiliser ces outils sans que chaque résultat soit différent, parce que la forme est partagée.
- Le jugement reste visible et assumé, car les parties qui demandent une décision sont celles que l'outil refuse de remplir.
Le modèle n'est pas la partie astucieuse. La partie astucieuse est d'être honnête sur la moitié du travail qu'il est sûr d'automatiser — et de construire l'outil pour que l'autre moitié ne puisse pas être sautée par accident.
L'outil : le générateur de TSD est cette étude rendue utilisable. Écrivez l'exigence une fois et il produit le squelette complet, commentaires de guidage compris, dans votre navigateur.