Auditer une architecture avec un agent : ce qu'un LLM voit que les outils statiques ne voient pas
Un outil comme dependency-cruiser sait très bien détecter un cycle de dépendances. Ce qu'il ne sait pas faire, c'est répondre à la question qu'un client ou un recruteur se pose réellement : est-ce que cette base de code est saine, et si non, par où commencer ? C'est cet écart, entre la métrique brute et la décision à prendre, que j'ai voulu combler avec Hexray, un outil en ligne de commande qui audite une architecture TypeScript ou Kotlin.
Ce que l'outil détecte, sans agent#
Hexray s'appuie sur des analyseurs statiques classiques pour produire quatre familles de résultats :
| Vérification | Ce qu'elle détecte |
|---|---|
| Violations de couches | Le domaine importe une dépendance d'infrastructure |
| Cycles de dépendances | Deux modules dépendent l'un de l'autre, directement ou indirectement |
| Ratio de la pyramide de tests | Trop de tests d'intégration lents, pas assez de tests unitaires rapides |
| Fraîcheur des dépendances | Des packages significativement en retard sur leur dernière version |
Jusqu'ici, rien qui nécessite une IA : c'est exactement ce que fait dependency-cruiser, appliqué à un projet réel. La différence commence après.
Là où l'agent intervient : la synthèse, pas la détection#
Le rôle de l'agent n'est jamais de décider si un cycle de dépendances existe. C'est un fait, produit par un outil déterministe, pas une opinion. Le rôle de l'agent est de prendre cette liste de faits bruts, la prioriser par sévérité, et la reformuler en résumé exécutif compréhensible sans connaître le nom du deuxième outil d'analyse statique.
domain/
Finding, priorisation par sévérité (aucune dépendance externe)
application/
RunAudit (cas d'usage), StaticAnalyzerPort (port)
infrastructure/
Adapters concrets : dependency-cruiser, Claude pour la synthèse,
générateur de rapport HTML
presentation/
Point d'entrée CLI
Cette séparation n'est pas accessoire, elle protège justement contre le risque principal d'un audit assisté par IA : que le modèle invente un finding qui n'existe pas. StaticAnalyzerPort garantit que chaque violation citée dans le rapport final provient d'un outil déterministe, jamais d'une hallucination du modèle de synthèse. L'agent ne voit jamais le code source directement, seulement la liste de findings déjà produite.
Un exemple concret de ce que ça change#
Une liste brute dit : « 12 violations de couches, 3 cycles de dépendances, ratio pyramide 15/60/25 ». Un résumé exécutif dit : « Le domaine de facturation importe directement le client HTTP de paiement à trois endroits, ce qui rend impossible de tester la logique de facturation sans mocker un service externe : c'est le point le plus risqué à corriger avant d'ajouter une nouvelle fonctionnalité ». La deuxième version demande du contexte métier que dependency-cruiser n'a pas et n'a pas besoin d'avoir : ce n'est pas son travail.
Ce que ça change concrètement#
Sans la couche de synthèse, un rapport d'audit reste un artefact pour développeurs : utile, mais illisible en dehors de l'équipe technique. Avec elle, le même audit devient un livrable qu'un client ou un recruteur peut lire en quelques secondes, avec une recommandation priorisée plutôt qu'une liste plate. La leçon générale dépasse l'outil lui-même : un agent apporte le plus de valeur quand on lui confie exactement ce qu'un LLM fait bien, synthétiser et prioriser, et rien de ce qu'un outil déterministe fait déjà mieux, détecter et compter.
