De la doc qui pilote une IA à une carte vivante de l’architecture

Plusieurs dépôts indépendants, pas un monorepo

Je développe un produit découpé en plusieurs dépôts git indépendants : application web, application mobile, vitrine, package partagé, générateur de données, backend. Pas un monorepo.

Le premier risque n’est pas la qualité du code, c’est l’endroit

Dupliquer un comportement partagé dans une application au lieu du package commun, et deux plateformes divergent silencieusement. Ça m’est arrivé.

La réponse : une table d’aiguillage, et des hooks

Un fichier de règles à la racine, écrit comme une table d’aiguillage (« cette demande, ce dépôt, ce piège »), plus un fichier par dépôt, et des hooks qui rappellent la règle et modifient la documentation.

Chaque règle vient d’un incident réel : ça évite de reperdre du temps sur la même erreur.

Ce que ça ne résout pas

Les tests, la CI et la procédure par changement protègent la correction du code. Rien ne protège la charge cognitive de savoir qui a touché quoi, ni ne garantit que l’agent a eu le bon contexte plutôt qu’un fichier voisin qui ne dit plus la vérité.

La carte, faite des fichiers eux-mêmes

Pour ça, j’ouvre ces mêmes fichiers Markdown dans Obsidian, un outil pensé pour relier des notes personnelles, pas de la documentation technique.

La carte est synchronisée avec les fichiers de documentation du code, les CLAUDE.md, les skills, les agents et le code lui-même. Pas un schéma dessiné à part, déconnecté dès le lendemain.

Cliquer un nœud pour corriger une incohérence sur place est possible, mais accessoire.

Le vrai gain est visuel

Un texte lu ligne par ligne ne montre pas ce qu’un œil capte en une fraction de seconde : un nœud isolé sans arête, une couleur qui ne devrait pas être là. Une anomalie structurelle qu’aucune lecture séquentielle ne fait ressortir aussi vite.

Ce que ça donne, concrètement :

• Chaque dépôt a sa couleur, façon étiquettes macOS.
• Les dossiers de documentation sont en pastel de la couleur de leur dépôt : on voit où la documentation est dense et où elle est maigre.
• Les liens ne sont posés qu’aux endroits d’usage réel, vérifiés avant d’être écrits, ce qui a révélé une dépendance déclarée jamais importée.
• Ça montre ce qu’un agent a sous les yeux sur une tâche : ni noyé sous une documentation entière, ni privé de la règle critique.

Le principe n’a pas changé, la vitesse si

Ne pas se répéter (DRY) existe depuis toujours en programmation. Ce qui a changé, c’est la vitesse à laquelle on peut le violer sans s’en apercevoir.

Et rien qu’en construisant cette visualisation, la carte m’a déjà donné une liste de choses à reprendre. Visiblement, j’ai du boulot devant moi…