Les diagrammes meurent pour une raison banale : ils n'ont qu'une seule forme, et c'est la mauvaise pour au moins la moitié de vos besoins. Un dessin est parfait pour un lecteur et inutile dans une pull request. Un bloc de code de diagramme se relit à merveille et ne dit rien à une partie prenante. Les équipes en choisissent donc un, et l'autre besoin reste insatisfait jusqu'à ce que le diagramme prenne du retard et que plus personne ne lui fasse confiance.
La solution n'est pas de choisir. C'est de garder les deux formes et de passer librement de l'une à l'autre. Le code devient un diagramme quand vous voulez le voir ; un diagramme devient du code quand vous voulez le relire ou le stocker. L'IA facilite le trajet dans les deux sens, et c'est l'aller-retour qui rend le diagramme durable.
Premier sens : du code au diagramme
Vous avez déjà du texte qui décrit une structure, qu'il s'agisse de Mermaid, de D2 ou d'un artefact comme un fichier Compose ou un schéma SQL. Importez-le et il devient de vraies formes modifiables, disposées pour vous. Vous pouvez alors faire ce que le texte ne permet pas : mettre en évidence le chemin risqué, regrouper un bounded context, déposer une note là où se trouve la partie délicate.
graph LR
client --> api
api --> cache
api --> db
worker --> queue
Collez cela : ce n'est pas une image rendue, c'est un ensemble de boîtes et de flèches que vous pouvez saisir et déplacer. Le code vous a donné la structure gratuitement. Vos modifications y ajoutent le sens.
Second sens : du diagramme au code
Inversez maintenant. Vous avez façonné un diagramme sur le canevas et vous le voulez dans le dépôt, à côté du code qu'il décrit, là où il peut être relu et versionné. Réexportez-le en Mermaid ou en D2 et commitez le texte. La prochaine fois que quelqu'un ouvrira une pull request qui modifie le système, le code du diagramme changera dans la même revue, sous les mêmes yeux.
Là où l'IA facilite l'aller-retour
Les deux sens deviennent plus faciles avec un modèle dans la boucle, mais pas de la manière que suggère l'engouement ambiant. L'IA n'est pas là pour remplacer le code ou le dessin. Elle est là pour combler les écarts désordonnés :
- D'une saisie approximative à un code propre. Décrivez un flux en une phrase et obtenez une première version de code de diagramme que vous pouvez rendre et affiner.
- D'un diagramme brouillon à un code net. Demandez que le texte exporté soit simplifié ou renommé pour que la version commitée se lise bien.
- De la dérive à une nouvelle ébauche. Quand le système a évolué, régénérez à partir de la source actuelle et réconciliez, au lieu de rapiécer à la main une vieille image.
Deux formes d'une même vérité. Le code la garde relisible ; l'image la garde lue.
Pourquoi c'est mieux que de choisir un camp
Le diagramme à forme unique impose un mauvais compromis. Le diagramme en tant que code seul vous donne la relecture et une image que personne n'aime lire. Un dessin seul vous donne une image agréable qui s'éloigne silencieusement du code. Garder les deux, avec un aller-retour facile, vous donne la relisibilité du texte et la clarté d'un visuel à partir de la même source. Aucun des deux n'est relégué au second rang.
L'habitude qui vaut la peine d'être prise
Traitez les deux formes comme un seul artefact avec deux vues. Faites l'ébauche dans celle qui est la plus rapide sur le moment, en esquissant visuellement ou en tapant la structure, puis faites l'aller-retour pour obtenir l'autre forme gratuitement. Faites-le systématiquement et l'éternel problème du diagramme obsolète disparaît en grande partie, car il existe toujours un chemin peu coûteux pour revenir à un état correct.
Collez du code de diagramme et façonnez-le, ou dessinez quelque chose et exportez le code. Une fois que vous aurez ressenti l'aller-retour, tenir un diagramme à jour cessera d'être une corvée que vous évitez.