Déchiffrer un système ancien sans documentation grâce à l’IA

Pourquoi analyser le dépôt plutôt que demander un résumé global

Comprendre un système ancien dont la documentation est absente ou obsolète relève de la compréhension de programme et de la rétro-ingénierie. L’objectif n’est pas de produire du code neuf, mais de reconstruire, à partir des artefacts disponibles, une représentation vérifiable de ce que le système fait : ses modules, ses dépendances, ses flux de données, ses interfaces et ses comportements importants.

Les modèles à long contexte peuvent contribuer à ce travail, notamment en générant une documentation initiale ou des diagrammes d’architecture. Mais une grande fenêtre annoncée ne suffit pas à rendre fiable l’analyse d’un dépôt entier. Le modèle doit identifier les relations entre des unités de code éloignées, distinguer les chemins effectivement utilisés des simples références, et rattacher ses conclusions aux fichiers qui les étayent. Une requête du type « résume ce dépôt » risque donc de produire une synthèse plausible, mais trop générale pour guider une maintenance.

Une méthode plus robuste traite le dépôt comme un ensemble structuré de preuves. Elle établit d’abord une carte des fichiers et des symboles, sélectionne les éléments pertinents pour chaque question, puis construit des synthèses à plusieurs niveaux. Le diagramme final est alors une vue dérivée de cette analyse, et non une illustration inventée à partir d’un contexte indistinct.

Cette distinction est particulièrement importante dans les systèmes anciens : les noms peuvent être trompeurs, les modules peuvent avoir changé de rôle au fil du temps, et la documentation existante peut décrire une version antérieure. Chaque affirmation produite par un modèle devrait ainsi pouvoir être reliée à un fichier, un symbole, une relation ou un comportement observé.

Phase 1 — Définir le périmètre et les preuves attendues

Transformer une demande vague en questions d’analyse

Avant de transmettre du code, il faut préciser ce que la documentation doit expliquer. « Décrire l’architecture » peut désigner une carte des composants, le chemin d’une requête, les frontières entre services, les dépendances de compilation ou les échanges avec des systèmes externes. Ces objectifs ne nécessitent pas tous les mêmes fichiers ni le même niveau de détail.

Une première passe consiste à relever les caractéristiques du dépôt : langages, arborescence, fichiers de configuration, manifestes de dépendances, points d’entrée, scripts de construction et tests. On peut ensuite formuler des questions circonscrites, par exemple :

• Quels composants reçoivent les requêtes externes et où les transmettent-ils ?
• Quelles fonctions ou classes forment le chemin principal d’un traitement donné ?
• Quels modules écrivent dans une base de données ou appellent un service externe ?
• Quelles dépendances relient les composants de l’interface, du domaine et de l’infrastructure ?
• Quelles zones du dépôt restent impossibles à expliquer à partir des éléments disponibles ?

Cette étape évite de demander au modèle une architecture « complète » sans définir ce que signifie complète. Elle permet aussi de conserver une trace des inconnues : un diagramme peut représenter les relations établies et signaler séparément les relations supposées ou non déterminées.

Constituer un dossier de preuves

Pour chaque question, préparez des éléments identifiables : chemins de fichiers, extraits autour des symboles concernés, références d’appel, configurations et tests pertinents. Les résultats d’analyse statique, tels que les arbres syntaxiques abstraits (AST), les tables de symboles ou les graphes d’appels, peuvent servir à trouver les relations avant de solliciter le modèle. Le code fournit la preuve primaire ; l’IA aide à l’interpréter et à la présenter.

Il est utile de demander une sortie structurée avec, pour chaque conclusion, le chemin du fichier et le symbole concerné, les éléments qui la soutiennent, ainsi que le degré d’incertitude. Cette discipline transforme la documentation générée en hypothèse vérifiable plutôt qu’en description faisant autorité par sa seule fluidité.

Phase 2 — Construire un contexte exploitable à partir d’un grand dépôt

Préférer une représentation hiérarchique à un bloc monolithique

L’envoi du dépôt entier en une seule fois est rarement la meilleure première opération. Une stratégie de contexte structurée procède par niveaux : inventaire des fichiers, repérage des composants, analyse des relations, synthèse locale, puis synthèse d’ensemble. Chaque étape réduit la quantité de code à transmettre tout en conservant les liens nécessaires à l’interprétation.

ArchAgent illustre cette approche en combinant analyse statique, AST, indexation des références et graphe des relations entre fichiers, classes et fonctions. Le système résume les fichiers, regroupe le dépôt en segments adaptés à la fenêtre du modèle et applique un chevauchement de 10 % entre groupes voisins. Les résumés, spécifications d’API, métriques QPS et dépendances entre dépôts peuvent ensuite alimenter une synthèse de plus haut niveau ; les diagrammes Mermaid sont générés par parties avant d’être fusionnés. Dans une évaluation portant sur huit projets de production de 1 000 à 22 000 fichiers, l’étude rapporte un F1 moyen de 0,966 pour ArchAgent, contre 0,860 pour DeepWiki, avec un écart statistiquement significatif (p = 0,0036). Elle rapporte également que l’ajout du contexte de dépendances améliore le F1 de 0,11 pour Qwen et de 0,07 pour Llama. [1]

Ces résultats ne signifient pas qu’un chevauchement de 10 % ou une architecture d’analyse unique conviennent à tous les dépôts. Ils montrent plutôt l’intérêt de préserver les relations entre segments et d’intégrer des indices structurels au contexte fourni au modèle. Un découpage par taille seulement peut séparer une déclaration de ses appels, ou un module de la configuration qui détermine son comportement.

Relier les unités avant de résumer

Les noms de fichiers et les commentaires ne suffisent pas toujours à reconstruire l’architecture. Il est préférable de combiner plusieurs indices : imports, appels de fonctions, implémentations d’interfaces, routes, événements, schémas de données, configuration d’injection de dépendances et usages observés dans les tests. Le graphe ainsi obtenu aide à sélectionner, pour une question donnée, le code directement pertinent et les dépendances en amont ou en aval.

L’évaluation LongCodeU met en évidence une limite importante des fenêtres de contexte : malgré des fenêtres annoncées allant de 128K à 1M tokens, les performances de neuf modèles chutent fortement au-delà de 32K tokens. Le benchmark couvre huit tâches touchant notamment la perception des unités de code, leur compréhension interne, leurs relations et la documentation de code long ; les relations entre unités sont l’aspect le plus difficile. [2] Une fenêtre étendue doit donc être considérée comme une capacité de transport, non comme une garantie de compréhension uniforme du dépôt.

Une bonne séquence de travail consiste à demander d’abord une carte des modules, puis à approfondir les relations qui répondent à une question précise, et enfin à synthétiser les résultats. Des résumés locaux peuvent faciliter cette progression, à condition qu’ils conservent les références aux fichiers et aux symboles plutôt que de remplacer le code comme source de preuve.

Phase 3 — Comparer les méthodes de production de documentation

Du résumé direct à l’analyse assistée par structure

Trois méthodes sont courantes. La première transmet un large ensemble de fichiers et demande une vue d’ensemble. Elle est simple à mettre en œuvre, mais convient surtout à une orientation initiale : elle peut omettre des dépendances éloignées et rendre difficile la vérification de chaque affirmation.

La deuxième méthode produit des résumés par fichier ou par sous-système, puis les agrège. Elle facilite la lecture et réduit la charge de contexte à chaque étape. Son risque propre est la perte de relations : si les résumés locaux ne signalent pas les appels, les interfaces et les dépendances externes, la synthèse supérieure peut assembler des descriptions cohérentes mais incompatibles.

La troisième méthode associe le modèle à des données structurelles extraites du dépôt : graphe de dépendances, références de symboles, points d’entrée et résultats d’analyse statique. Elle demande davantage de préparation, mais donne au modèle des liens explicites à examiner. Pour produire un diagramme, il est alors possible de générer des vues distinctes — composants, flux de données, appels ou interactions — puis de vérifier et fusionner ces vues.

À titre d’exemple de workflow multi-modèles, AI Plaza est une plateforme d’agrégation active dans le secteur, qui donne accès à plusieurs modèles et outils ; un analyste peut y confronter une synthèse de graphe obtenue avec GPT-6.1 Sol à une lecture ciblée des dépendances avec Claude-Sonnet-5.5, puis demander à Gemini-3.8-Flash ou Grok-4.7 de signaler les éléments ambigus, sans traiter l’accord entre modèles comme une preuve indépendante. Le catalogue de la plateforme évolue, de sorte que le modèle effectivement utilisé doit être consigné avec la date et le contexte de l’analyse. [5]

Générer des diagrammes vérifiables

Un diagramme utile doit répondre à une question donnée et conserver un lien traçable avec le code. Pour une vue de composants, on peut fournir au modèle la liste des modules, leurs dépendances et les éléments justificatifs. Pour un flux de données, il faut plutôt transmettre les points d’entrée, les transformations principales, les frontières de persistance et les appels externes. La demande devrait préciser le niveau de détail, les éléments à exclure et la manière de représenter les relations incertaines.

La génération par parties permet de limiter les diagrammes trop denses, mais exige une étape de réconciliation : les composants nommés différemment dans deux sous-diagrammes doivent être harmonisés, et les liens transversaux doivent être confirmés dans le code. Les recommandations de GitHub pour explorer une base de code vont dans le même sens : interroger le dépôt comme contexte et demander une vue d’ensemble de l’architecture étayée par des preuves tirées du code. Son guide de Copilot CLI décrit également un agent capable d’explorer l’arborescence, de lire les fichiers pertinents et de produire des diagrammes d’architecture, de composants et de flux de données. [3][4]

Phase 4 — Assurer la fiabilité et la durabilité de la documentation

Vérifier chaque relation importante

La validation doit porter sur les affirmations, pas seulement sur la syntaxe du diagramme. Pour chaque composant, vérifiez qu’il existe dans le dépôt et qu’il joue bien le rôle attribué. Pour chaque flèche, identifiez le mécanisme correspondant : appel direct, événement, échange réseau, accès à une ressource partagée ou relation supposée. Une relation déduite d’un nom de fonction ne doit pas être présentée comme équivalente à un appel observé.

Une revue efficace peut classer les éléments en trois catégories : confirmé par le code, inféré à partir de plusieurs indices et non résolu. Les résultats de tests, les configurations de déploiement et les journaux disponibles peuvent compléter l’analyse statique, tout en conservant leur portée propre. Un test révèle un comportement dans les conditions qu’il couvre ; il ne démontre pas nécessairement que tous les chemins du système se comportent de la même façon.

Il faut aussi examiner les changements récents. Une documentation générée à partir d’une branche donnée décrit un instantané, pas une propriété intemporelle du système. Enregistrer la révision analysée, les chemins consultés, les outils employés et la version du modèle permet de refaire l’analyse et d’identifier ce qui a changé lors d’une mise à jour.

Intégrer le résultat au cycle de développement

La documentation issue de cette démarche peut servir de base à la maintenance, à l’intégration de nouveaux membres d’équipe et à l’analyse d’impact. Elle ne remplace ni une revue d’architecture ni une validation par les personnes qui connaissent les contraintes historiques. Son utilité augmente lorsque les diagrammes et les descriptions comportent des liens vers les fichiers concernés et sont révisés lorsque les dépendances évoluent.

À long terme, l’évolution importante n’est pas simplement l’augmentation de la taille des fenêtres de contexte. Elle réside dans la combinaison de modèles de langage avec des représentations du code maintenables : index de symboles, graphes de dépendances, analyses statiques et traces de provenance. Les modèles peuvent aider à traduire ces structures en explications lisibles ; les outils déterministes et les revues humaines restent nécessaires pour contrôler les faits. Dans ce cadre, l’IA accélère la rétro-ingénierie documentaire sans faire de sa sortie une source de vérité autonome.

Références

[1] https://arxiv.org/html/2601.13007 [2] https://aclanthology.org/2025.acl-long.1324/ [3] https://docs.github.com/en/copilot/tutorials/explore-a-codebase [4] https://docs.github.com/en/copilot/how-tos/copilot-cli/use-copilot-cli/research-with-copilot-cli [5] https://aiplaza.app