Le diagramme d'architecture était magnifique : des dizaines de boîtes, des flèches nettes, trois couleurs, une légende. Je l'ai fixé dix minutes, et je ne savais toujours pas répondre à la question la plus bête qui soit : ce système, il fait quoi, et pour qui ? Il me montrait des services, des files d'attente, des bases de données. Pas une ligne sur ce que l'utilisateur, au bout, en retirait. J'avais sous les yeux un plan du métro sans le nom des stations, et on venait de me demander d'y conduire.
Un diagramme technique répond à une seule question : comment le système est-il construit. Quels composants, quels appels, quels tuyaux. C'est utile, mais quand tu hérites d'un système, ce n'est pas la question que tu te poses en premier. Celle qui te presse, c'est l'autre : qu'est-ce qu'il fait, pour qui, et avec quels mots. Un système que tu ne sais décrire qu'en services et en flèches est un système que tu ne comprends pas encore. Tu en connais la plomberie, pas la ville.
Deux cartes pour le même système
Il existe deux façons de cartographier un système, et on ne t'a montré que la mauvaise pour débuter.
La carte technique liste les services, les bases, les flux entre eux. C'est celle des diagrammes d'archi. Elle a deux défauts quand tu découvres. D'abord elle ment sur l'intention : un service appelé OrderService peut faire trois choses sans rapport, et un nom de fichier ne t'a jamais dit pourquoi il existe. Ensuite elle bouge tout le temps : un refacto, un service qui se scinde, et ta carte est périmée. Tu cartographies du sable.
La carte fonctionnelle liste autre chose : ce que le système fait (ses capacités), pour qui (ses acteurs), et dans quels mots (le vocabulaire du métier). Pas « POST /v2/process », mais « un client annule une commande ». Cette carte-là est stable, parce que ce qu'un système rend à ses utilisateurs change lentement, bien plus lentement que la façon dont c'est codé. Et c'est la seule que tu peux montrer à quelqu'un qui n'est pas dev, la seule qui te dise, quand tu t'apprêtes à toucher un bout : quelle capacité je casse si je me trompe, et qui va hurler.
Le code te donne le comment. La carte fonctionnelle récupère le quoi et le pour-qui, c'est-à-dire précisément ce que le code a effacé en cours de route.
La tracer en un après-midi, seul
Bonne nouvelle : tu n'as besoin de personne pour la première version. Pas des experts (souvent introuvables ou déjà partis), pas d'une réunion. Juste du dépôt et d'un après-midi. Voici la méthode.
Commence par les points d'entrée. Tout ce qui fait entrer quelque chose dans le système est une chose qu'il fait pour quelqu'un : les écrans, les routes d'API, les tâches planifiées, les messages consommés dans une file, les webhooks. Ça se trouve mécaniquement, en listant les routes et les jobs, sans rien comprendre encore. C'est ta liste brute de capacités.
Ensuite, nomme chaque capacité dans les mots de l'utilisateur, pas dans ceux du code. POST /v2/proc devient « un client passe une commande ». Si tu n'arrives pas à nommer une entrée en français simple, note-la comme une zone d'ombre : c'est une capacité que tu ne comprends pas encore, et c'est une information précieuse, pas une honte.
Pour chacune, demande pour qui. Un utilisateur final ? Un admin ? Un autre système ? Un traitement de nuit ? Les acteurs révèlent à qui le système rend service, et donc qui appeler le jour où ça casse.
Récolte le vocabulaire au passage. Les noms qui reviennent dans les routes, les tables, les logs, ce sont les mots du métier. Fais-en un mini-lexique. Et guette les frottements : quand deux mots désignent la même chose, ou qu'un mot désigne deux choses selon l'endroit, tu viens de trouver une couture, la frontière entre deux territoires du système.
Enfin, relie. Pas les services entre eux, les capacités entre elles : « passer une commande » a besoin de « vérifier le stock ». Ces dépendances-là, fonctionnelles, te donnent l'ordre des dominos.
Au bout de l'après-midi, tu as une page : une vingtaine de capacités, leurs acteurs, leurs mots, leurs dépendances. Seul, à partir du code. Prends une app de réservation fictive : « réserver un créneau », « annuler une réservation », « relancer un client sans réponse » (déclenchée par un traitement de nuit, pas par un humain), avec le lexique qui distingue le « créneau » côté client du « slot » côté technique. En une page, tu en sais plus sur ce que fait ce système que la plupart des gens qui vivent dedans depuis six mois sans l'avoir jamais posé à plat.
Ce que l'IA en fait, et ce qu'elle n'en fait pas
L'assistant lit le code plus vite que toi et te dessinera une carte technique en un instant : le graphe d'appels, les services, qui parle à qui. Utilise-le pour la corvée, justement, pour aspirer les points d'entrée et les noms qui reviennent.
Mais la carte fonctionnelle lui échappe là où ça compte. Nommer une route dans les mots du métier, savoir que cette annulation-là est un drame pour la compta et une broutille pour le support, distinguer le mot qui cache deux réalités : tout ça, c'est du sens, et le sens ne vit pas dans le code. Il vit dans les gens qui s'en servent. L'IA voit que proc appelle stock ; elle ne sait pas que « passer une commande » est la promesse autour de laquelle toute la boîte tourne.
C'est là que tu restes indispensable. Dans un monde où le code se génère et s'accumule plus vite que jamais, celui qui sait transformer ce tas en une carte de ce qu'il signifie, celui-là tient vraiment le système. La génération produit du comment à la chaîne. Le quoi et le pour-qui, il faut encore quelqu'un pour les nommer.
Par quoi commencer demain matin
Ne lis pas le code de haut en bas. N'ouvre pas le diagramme d'archi du wiki. Ouvre le fichier des routes, ou la liste des tâches planifiées. Liste chaque point d'entrée, nomme-le en français, mets un acteur en face. C'est ton après-midi, et ce soir tu auras une carte que le code ne dessinait pas.
Un système que tu ne sais décrire que dans les mots du code est un système que tu ne comprends pas encore, quelle que soit la beauté de son diagramme. Le jour où tu peux le raconter dans les mots de ceux qui s'en servent, tu as pris la main.
Ce satellite fait partie du dossier Lire un système qu'on n'a pas écrit. Le vocabulaire à emporter : la cartographie fonctionnelle, la dépendance, le domaine, le langage ubiquitaire et le bounded context.