Après avoir fait coder l'agent IA, le travail de l'humain est la visualisation

J’ai fait refactoriser tout un ensemble de microservices par un agent. La PR est arrivée en vingt minutes, propre, bien structurée. Mais le flux d’appels entre services ne se dessinait pas dans ma tête. J’ouvrais les fichiers un par un, je traçais mentalement les dépendances, je relisais les logs ligne par ligne en me demandant “est-ce que c’est correct ?” Le temps passé à comprendre le code dépassait largement le temps qu’il avait fallu pour le générer. C’est à ce moment que j’ai compris : le goulot d’étranglement n’est plus l’écriture du code. C’est sa compréhension. La visualisation a tout changé pour moi, et cinq outils abordent ce problème sous des angles différents.

visual-explainer : du terminal ASCII vers du HTML interactif

visual-explainer part d’un constat simple. Quand un agent produit un diagramme Mermaid dans le terminal, c’est du texte brut. Personne ne zoome dans du texte brut. Cet outil transforme la sortie en HTML interactif avec dark mode, zoom et navigation panoramique, sans étape de build.

Ce qui m’a convaincu, c’est la polyvalence des commandes intégrées.

• /diff-review analyse un diff Git et génère un diagramme du flux de changements, idéal pour les revues de PR où l’agent a touché plusieurs fichiers
• /project-recap produit une vue d’ensemble de l’architecture du projet, exactement ce qu’il manquait quand je fixais ma refactorisation de microservices
• /generate-slides crée des présentations à partir du code, utile pour les démonstrations d’équipe
• Conversion automatique en HTML pour tout tableau dépassant 4 lignes, ce qui élimine les tableaux ASCII illisibles dans le terminal

L’outil ne demande aucune configuration lourde. On l’installe, on l’utilise. C’est le type d’outil qui fait gagner du temps dès la première utilisation.

Excalidraw MCP : des diagrammes en temps réel dans le chat

Excalidraw MCP adopte une approche différente. Au lieu de produire des fichiers statiques, il génère des diagrammes directement dans la conversation avec l’agent, que ce soit dans Claude Desktop ou VS Code.

Le style croquis à main levée n’est pas qu’esthétique. Il rend les diagrammes moins intimidants pour les non-développeurs, ce qui est précieux quand on présente l’architecture à un product manager ou à un nouveau membre de l’équipe. Le viewport s’ajuste automatiquement au contenu, et on peut éditer le résultat de manière interactive après génération.

• Intégration native avec Claude Desktop et VS Code, pas besoin de quitter son environnement
• Viewport automatique qui cadre le diagramme sur le contenu pertinent
• Édition interactive après génération, on peut déplacer les blocs et ajuster les connexions

Une limite à connaître : pour les diagrammes de séquence complexes avec de nombreux participants et messages imbriqués, Mermaid reste plus adapté. Excalidraw excelle pour les vues d’architecture de haut niveau et les flux simples, mais il atteint ses limites quand la logique séquentielle devient dense. Ce n’est pas un défaut, c’est un choix de conception. Chaque outil a son terrain.

beautiful-mermaid : styliser Mermaid sans se battre avec le CSS

beautiful-mermaid résout un problème que tout utilisateur de Mermaid connaît : les diagrammes par défaut sont fonctionnels mais visuellement austères. L’approche ici est minimaliste. On choisit deux couleurs (fond et premier plan), et l’outil génère automatiquement toute la palette intermédiaire via color-mix(). Quinze thèmes sont disponibles pour ceux qui préfèrent ne pas choisir.

• Deux couleurs suffisent pour produire un thème cohérent grâce au calcul automatique des nuances
• Synchronisation SVG en React via useMemo, ce qui évite les re-rendus inutiles dans les applications web
• Mode ASCII/CLI pour les environnements sans DOM, parfait pour l’intégration dans des pipelines CI
• Support Shiki/VS Code pour la coloration syntaxique des blocs Mermaid directement dans l’éditeur

C’est le genre d’outil qu’on ne sait pas qu’on veut jusqu’à ce qu’on ait passé une heure à modifier manuellement les styles d’un diagramme Mermaid pour une documentation.

La méthode “Claude Teacher” de Zara Zhang : faire enseigner l’architecture à l’IA

Zara Zhang propose une approche qui ne repose pas sur un outil mais sur une convention de fichiers. Son concept de “Claude Teacher” utilise deux types de documents : un CLAUDE.md pour le contexte global du projet, et des fichiers FOR[nom].md destinés à des personnes spécifiques.

L’idée est de demander à l’agent non pas de coder, mais d’expliquer. On lui fait documenter l’architecture, les décisions techniques, les bugs connus et les pièges à éviter. Le résultat devient un guide personnalisé pour chaque membre de l’équipe.

• CLAUDE.md contient le contexte architectural, les conventions de code et les décisions de conception
• FOR[nom].md adapte l’explication au niveau et au rôle de chaque personne
• Documentation des pièges : l’agent liste les bugs subtils et les cas limites qu’il a rencontrés pendant le développement
• Transmission de la mentalité ingénieur : au-delà du code, on capture le raisonnement derrière les choix

Cette méthode transforme l’agent en outil de transfert de connaissances. C’est particulièrement utile dans les équipes où le turnover est fréquent ou quand un développeur senior veut transmettre le contexte d’un projet complexe.

Les modes de Boris Cherny : basculer entre explication et apprentissage

Boris Cherny a formalisé une idée complémentaire. Plutôt que de laisser l’agent choisir comment il s’exprime, on définit explicitement des styles via /config. Le mode “explanatory” produit des commentaires détaillés et des comparaisons avant/après. Le mode “learning” pousse l’agent à poser des questions et à guider la réflexion plutôt que de donner des réponses directes.

• /config pour basculer entre les styles selon le contexte : revue de code, onboarding, exploration
• Comparaisons avant/après qui montrent visuellement l’impact d’un changement
• Mode apprentissage qui transforme l’agent en mentor plutôt qu’en exécutant

La combinaison de ces deux modes couvre la majorité des situations. Quand on revoit une PR générée par un agent, le mode explanatory clarifie chaque décision. Quand on forme un junior sur le projet, le mode learning le pousse à comprendre par lui-même.

Faire travailler l’IA ne suffit plus. Le code généré par un agent est un artefact brut. Sans visualisation, sans explication structurée, il reste opaque. Le rôle de l’humain dans cette boucle n’est pas de réécrire le code. C’est de le comprendre, de le valider et de le transmettre. Ces cinq outils couvrent le spectre : du diagramme interactif au transfert de connaissances ciblé. L’investissement se mesure en minutes, le retour en heures récupérées sur chaque PR.