Découverte d'architecture par IA : comment ça fonctionne

L'année dernière, j'ai hérité d'une codebase sans aucune documentation. 200 000 lignes de code réparties sur 15 services, écrites par une équipe qui était depuis partie. Ma tâche était de comprendre le système suffisamment bien pour ajouter une nouvelle intégration de paiement. L'entreprise estimait qu'il faudrait 2-3 semaines juste pour cartographier l'architecture.

Cette expérience est la raison pour laquelle j'ai construit la fonctionnalité de découverte IA d'Archyl. Et maintenant, après avoir passé des mois à travailler avec des modèles de langage pour analyser du code, je veux partager ce qui fonctionne vraiment, ce qui ne fonctionne pas, et pourquoi la découverte d'architecture par IA est puissante mais pas magique.

Le problème avec la découverte manuelle

Avant de plonger dans l'IA, reconnaissons pourquoi nous en avons besoin en premier lieu.

Quand j'ai fait face à cette codebase non documentée, voici à quoi ressemblait mon processus de découverte :

Semaine 1 : Grep à travers le code en cherchant des mots-clés. Trouver les points d'entrée principaux. Dessiner quelques boîtes sur un tableau blanc. Réaliser que j'avais mal compris les frontières des services. Effacer et redessiner.

Semaine 2 : Interviewer le seul ingénieur qui était là depuis assez longtemps pour se souvenir d'une partie de l'histoire. La moitié de ce qu'il me dit contredit ce que j'ai trouvé dans le code. Il s'avère que les choses ont changé mais personne n'a mis à jour son modèle mental.

Semaine 3 : Enfin avoir l'impression de comprendre le système suffisamment bien pour faire des changements. Créer une documentation que je jure de maintenir à jour. (Spoiler : je ne l'ai pas fait.)

Ce processus est lent, sujet aux erreurs, et ne scale pas. Chaque nouveau membre de l'équipe passe par la même découverte douloureuse. La documentation dérive et devient obsolète en quelques mois.

Comment fonctionne réellement la découverte par IA

Quand vous connectez un dépôt à Archyl et lancez la découverte, voici ce qui se passe sous le capot :

Étape 1 : Analyse du dépôt

D'abord, on construit une carte de votre codebase. Ce n'est pas encore de l'IA — c'est une traversée simple du système de fichiers :

• Lister tous les fichiers et répertoires
• Identifier les fichiers de configuration (package.json, go.mod, docker-compose.yml)
• Trouver les points d'entrée (fonctions main, fichiers index, routes API)
• Construire un graphe de dépendances à partir des imports

Ça nous donne le squelette. On sait quels fichiers existent et comment ils se référencent les uns les autres. Mais on ne comprend pas encore ce qu'ils font.

Étape 2 : Analyse par chunks

C'est là que les LLMs entrent en jeu, et aussi là où ça devient délicat.

Les modèles de langage modernes ont des limites de contexte. GPT-4 peut gérer environ 128K tokens, Claude peut faire 200K. Ça semble beaucoup, mais une codebase de taille moyenne dépasse facilement ça. Donc on ne peut pas juste tout mettre dans un prompt et demander "c'est quoi ?"

À la place, on découpe la codebase en morceaux digestibles :

1. Regrouper les fichiers par répertoire ou module
2. Envoyer chaque chunk au LLM avec du contexte sur sa position dans le projet
3. Demander au modèle d'identifier : De quoi ce code est-il responsable ? Quels patterns utilise-t-il ? Avec quels systèmes externes interagit-il ?

Les réponses reviennent sous forme de données structurées — du JSON décrivant des systèmes, containers et composants avec leurs relations.

Étape 3 : Agrégation et réconciliation

C'est la partie la plus difficile, et là où j'ai passé le plus de temps de développement.

Chaque analyse de chunk nous donne une vue partielle. Le chunk du service utilisateur connaît la base de données utilisateur. Le chunk de paiement connaît Stripe. Mais ni l'un ni l'autre ne connaît l'image complète.

On doit réconcilier ces vues partielles :

• Fusionner les entités dupliquées ("UserDB" est-il le même que "users_database" ?)
• Inférer les relations entre chunks (le service de commandes appelle le service utilisateur, mais ils ont été analysés séparément)
• Résoudre les conflits (un chunk dit qu'on utilise PostgreSQL, un autre dit MySQL — lequel a raison ?)

Cette réconciliation utilise un autre tour d'analyse LLM, plus des heuristiques basées sur des patterns communs. C'est imparfait. Parfois l'IA se trompe. C'est pourquoi la découverte produit des suggestions que les humains révisent, pas de la documentation finale.

Étape 4 : Génération du modèle C4

Enfin, on mappe les entités découvertes aux éléments du modèle C4 :

• Systèmes externes (APIs tierces, bases de données qu'on ne gère pas)
• Containers (nos unités déployables)
• Composants (modules majeurs dans les containers)
• Relations (qui appelle qui, quelles données circulent où)

Le résultat est un ensemble de diagrammes C4 en brouillon qui capturent la compréhension de l'IA de votre architecture.

Ce que l'IA fait bien

Après avoir lancé la découverte sur des dizaines de codebases pendant le développement, voici ce qui m'a impressionné :

Détection de la stack technologique

Les LLMs sont remarquablement bons pour identifier quelles technologies un projet utilise. Ils reconnaissent les patterns de framework, les idiomes de bibliothèques, et les formats de fichiers de configuration. Quand GPT voit une annotation @Controller, il sait que vous utilisez Spring. Quand il voit fiber.New(), il sait que vous utilisez Go Fiber.

Détection des frontières de services

Dans les architectures microservices, l'IA identifie de manière fiable les frontières de services. Elle comprend que le code dans /services/user/ est probablement un service séparé de /services/order/. Elle reconnaît les fichiers Docker Compose comme indicateurs de topologie de services.

Reconnaissance de patterns communs

L'IA a vu des millions de codebases dans ses données d'entraînement. Elle reconnaît les patterns repository, les structures MVC, les architectures event-driven, et les configurations d'API gateway. Quand votre code suit des patterns communs, l'IA les identifie rapidement.

Découverte d'intégrations externes

Chaque constante de clé API, URL de webhook, ou import de SDK est un indice sur les intégrations externes. L'IA en attrape la plupart, construisant une image des services tiers dont votre système dépend.

Ce que l'IA fait mal

Voici où j'ai dû définir des attentes réalistes :

Logique métier personnalisée

L'IA ne comprend pas votre domaine métier. Elle peut dire que vous avez une fonction processOrder, mais elle ne sait pas ce que "traiter une commande" signifie dans votre contexte métier spécifique. Elle pourrait mal identifier le but de composants spécifiques au domaine.

Architectures inhabituelles

Si votre architecture ne suit pas des patterns communs, l'IA galère. Un système de plugins personnalisé, une structure de dossiers non conventionnelle, ou un framework maison la confondra. L'IA s'attend à ce que les apps Rails ressemblent à des apps Rails.

Dépendances cachées

Toutes les dépendances ne sont pas explicites dans le code. Peut-être que votre service nécessite une version spécifique de Redis qui n'existe qu'en production. Peut-être qu'il y a un container sidecar que l'IA ne voit jamais. Les dépendances runtime sont souvent invisibles à l'analyse statique.

Chemins de code obsolètes

L'IA ne sait pas quel code est activement utilisé versus lequel est du legacy que personne n'a touché depuis des années. Elle pourrait mettre en évidence un service déprécié qui est encore dans la codebase mais plus déployé.

Faire mieux fonctionner la découverte IA

Par essais et erreurs, j'ai trouvé des moyens d'améliorer la précision de la découverte :

Fournir du contexte

Avant de lancer la découverte, dites à l'IA quelque chose sur votre système. "C'est une plateforme e-commerce avec traitement de paiements" donne au modèle un cadre de référence. Sans contexte, il devine à l'aveugle.

Commencer avec la structure

Si vous avez une documentation existante — même un README avec un croquis d'architecture approximatif — fournissez-la. L'IA utilise ça comme a priori pour guider son analyse.

Réviser de manière incrémentale

Ne lancez pas la découverte sur toute votre codebase d'un coup. Commencez avec un service. Révisez et corrigez les résultats. Puis étendez au service suivant. Les corrections que vous faites informent les futures analyses.

Faire confiance mais vérifier

Traitez les suggestions de l'IA comme un point de départ, pas la réponse finale. L'IA pourrait être précise à 80%. Vous devez vérifier les 20% restants. Cliquez sur les liens vers le code source, confirmez que les relations ont du sens, et corrigez les erreurs.

Les détails techniques

Pour les curieux de l'implémentation :

Stratégie de chunking

On utilise un chunking sémantique plutôt que des chunks de taille fixe. Un chunk est typiquement un module, un service, ou un arbre de répertoires. Ça garde le code lié ensemble, ce qui améliore la compréhension de l'IA.

Ingénierie de prompts

Les prompts ont significativement évolué. Les premières versions produisaient des descriptions verbeuses et narratives. Les prompts actuels demandent une sortie structurée avec des champs spécifiques. On utilise des exemples few-shot pour démontrer le format attendu.

Concurrence

Les grandes codebases ont des milliers de fichiers. Traiter séquentiellement prendrait une éternité. On analyse les chunks en parallèle, avec des limites de concurrence configurables pour éviter les limites de taux d'API.

Sélection de modèle

Différents modèles ont différentes forces. GPT-4 produit une analyse plus précise mais coûte plus cher. Claude est meilleur pour suivre les exigences de sortie structurée. On supporte les deux, plus les modèles locaux via Ollama pour les équipes qui ne peuvent pas envoyer du code à des APIs externes.

L'avenir de la découverte par IA

Ce qu'on a aujourd'hui est la version 1. Voici vers quoi je travaille :

Découverte continue

Au lieu d'une analyse ponctuelle, surveiller votre codebase en continu. Quand le code change, mettre à jour les diagrammes pertinents automatiquement. Détecter la dérive architecturale avant qu'elle ne devienne un problème.

Compréhension plus profonde

L'analyse actuelle est principalement structurelle. Les versions futures pourraient comprendre le comportement : "Ce endpoint valide l'entrée, appelle le service de paiement, puis envoie un email de confirmation." Des diagrammes de séquence générés à partir du code.

Analyse cross-repository

La plupart des organisations ont plusieurs repositories. La découverte devrait comprendre comment ils se connectent — quels services dans le repo A appellent des services dans le repo B.

Scores de confiance

Toutes les découvertes ne sont pas également certaines. On ajoute des scores de confiance pour que vous sachiez quelles suggestions examiner plus attentivement.

Conclusion

La découverte d'architecture par IA n'est pas de la magie. C'est un outil qui accélère les parties fastidieuses de la compréhension d'une codebase tout en nécessitant toujours le jugement humain pour les parties nuancées.

Quand je lance la découverte sur cette codebase de 200K lignes aujourd'hui, j'obtiens un brouillon de diagramme d'architecture en 10 minutes au lieu de 3 semaines. Ce n'est pas parfait — je dois toujours réviser et corriger. Mais c'est un point de départ dramatiquement meilleur qu'un tableau blanc vide.

Si vous vous noyez dans du code non documenté, essayez la découverte par IA. Allez-y avec des attentes réalistes : elle ne comprendra pas votre domaine métier, elle pourrait rater des patterns inhabituels, et elle nécessite définitivement une révision humaine. Mais elle vous fera 80% du chemin en une fraction du temps.

Envie d'en savoir plus ? Consultez notre introduction au modèle C4 que la découverte IA génère, ou lisez pourquoi la documentation d'architecture compte en premier lieu.