Claude Code est amnésique. Understand-Anything le soigne.

À chaque session, Claude Code rouvre votre codebase comme un visiteur qui n’y aurait jamais mis les pieds. Il lit le README, déplie les package.json, parcourt l’arborescence avec ls -R, lance des grep sur des termes qu’il devine, ouvre des fichiers entiers pour reconstituer ce qu’il a déjà reconstitué la veille. Sur un projet personnel de quinze fichiers, c’est invisible. Sur une codebase d’entreprise de cinquante mille lignes, c’est le poste de coût numéro un ; bien avant la longueur des réponses ou la verbosité des prompts.

Un projet open source publié sur GitHub en mars 2026 propose une autre voie. Il s’appelle Understand-Anything, il fonctionne sur Claude Code, Codex, Cursor, Copilot et Gemini CLI, et son ambition n’est pas d’optimiser des tokens. Son ambition est de changer ce qu’un agent fait quand il rencontre votre code. Et derrière le gadget apparent « un plugin de plus » se loge un déplacement architectural que personne n’a encore nommé en français.

Claude Code lit votre code comme un humain qui n’aurait jamais ouvert un IDE

Un développeur expérimenté qui rejoint un projet n’ouvre pas tous les fichiers un par un. Il interroge l’architecture : où vit l’authentification, comment circulent les requêtes, quelles couches dépendent de quoi. Il navigue par concepts, pas par chemins. C’est ce que fait un IDE moderne avec son indexation symbolique : Goto Definition, Find Usages, Call Hierarchy. Personne n’écrit du code en lançant grep toutes les trente secondes ; sauf Claude Code.

Le System Prompt de Claude Code, dont j’ai déjà disséqué la directive d’exécution rapide qui supplante la réflexion approfondie, pousse l’agent à agir avant d’avoir cartographié. Et comme il n’a pas d’index symbolique préalable, il agit en explorant. Sur une codebase neuve, c’est dix à vingt fichiers ingérés avant la première ligne écrite. Chaque session reproduit ce travail. Chaque session le facture.

Le problème n’est pas la voracité de l’agent. Le problème est qu’on lui demande de comprendre une structure complexe en lui présentant un système de fichiers à plat. Le code, contrairement à un article ou à un PDF, n’est pas un texte. Et le traiter comme un texte est l’erreur de conception qui rend l’exploration aveugle inévitable.

Ce que le code a en plus du texte : une structure qui se moque du chunking

Le RAG classique repose sur une chaîne que j’ai détaillée ailleurs : on découpe le corpus en morceaux, on les transforme en vecteurs, on les stocke, on les récupère par similarité cosine. Cette mécanique fonctionne sur du texte, où la proximité sémantique est une heuristique honnête : deux paragraphes parlant du même sujet ont de bonnes chances d’avoir des embeddings voisins.

Sur du code, l’heuristique s’effondre. Deux fonctions homonymes dans deux modules sans rapport produisent des vecteurs proches. Une classe abstraite et son implémentation concrète peuvent être éloignées dans l’espace vectoriel alors qu’elles sont littéralement la même chose pour qui veut comprendre l’architecture. Le auth.middleware.js qui appelle JwtService.verify() qui hérite de BaseAuthService n’est pas une chaîne sémantique : c’est un graphe d’appels, un graphe d’héritage, un graphe de dépendances qui se superposent. Le chunking par tokens fait disparaître cette topologie. Le cosine ne sait pas qu’un héritage existe. Le re-ranking ne sait pas qu’une fonction est appelée.

J’ai déjà argumenté que la base vectorielle s’est imposée comme réponse par défaut au RAG non parce qu’elle était universellement supérieure, mais parce qu’elle était arrivée au bon moment et avait hérité de l’aura des LLMs. Sur du code, ce constat devient brutal : la bonne représentation n’est ni un index BM25, ni une base vectorielle. C’est un graphe. Un graphe de symboles, de relations, de couches. Et ce graphe existe déjà ; chaque IDE le construit silencieusement à chaque ouverture de projet. Le rendre disponible à un agent IA est, à bien y regarder, le minimum syndical.

Understand-Anything : anatomie d’un GraphRAG sur AST

Le projet Understand-Anything, publié par Yuxiang Lin sous licence open source, fait précisément ce que devrait faire n’importe quel agent de code sérieux : il indexe la codebase en amont et matérialise sa structure dans un fichier interrogeable. Concrètement, l’utilisateur installe le plugin via le marketplace de Claude Code (/plugin marketplace add Lum1104/Understand-Anything), puis lance la commande /understand à la racine du projet.

Ce qui se passe ensuite n’est pas trivial. Un pipeline en cinq phases s’exécute localement : DETECT identifie les langages et frameworks présents, SCAN parcourt l’arborescence et extrait les symboles, ANALYZE mobilise des agents spécialisés pour comprendre les relations implicites, MERGE consolide les analyses partielles, SAVE persiste le résultat dans .understand-anything/knowledge-graph.json. Le résultat n’est pas une liste de fichiers ni une base vectorielle. C’est un graphe avec, dans la version actuelle, vingt-et-un types de nœuds (function, class, file, domain, flow, step, entity, claim, source, topic, article…) et trente-cinq types d’arêtes (structurelles, comportementales, flux de données, dépendances, sémantiques, infrastructure, domaine, knowledge).

Ce graphe est ensuite consultable de deux manières : un dashboard web local, qui affiche la codebase comme une carte navigable avec regroupement automatique par couche architecturale (API, Service, Data, UI, Utility), et (surtout) l’agent Claude Code lui-même, qui interroge le graphe au lieu d’attaquer directement le système de fichiers. Quand vous demandez « quelles parties gèrent l’authentification ? », Claude ne lance pas un grep -r auth. Il interroge les nœuds dont le type ou les arêtes pointent vers le domaine concerné.

C’est, mot pour mot, du GraphRAG appliqué au code. La différence avec le GraphRAG textuel de Microsoft Research, c’est que le graphe ne dérive pas de l’extraction d’entités d’un corpus de prose : il dérive d’une analyse structurelle déterministe (parsing AST) augmentée par des agents qui repèrent les relations implicites ; celles qu’un parseur syntaxique ne voit pas, comme la relation conceptuelle entre un service et son consommateur indirect via injection de dépendances.

Les agents qui construisent le graphe : la mise en abyme

C’est ici que l’architecture devient intéressante. La commande /understand n’est pas un script monolithique. Elle orchestre cinq agents spécialisés, et /understand-domain en ajoute un sixième dédié à l’extraction des flux métier. Chaque agent a sa responsabilité étroite : un agent de détection, un agent d’analyse de fichiers, un agent d’extraction de relations, un agent de consolidation, un agent de revue qui rattrape les nœuds abandonnés et les types inconnus, et pour la version domaine, un agent qui extrait les concepts métier.

Ce découpage n’est pas un détail d’implémentation. C’est la mise en abyme de la définition même de l’agent que j’ai posée dans « Le RAG est mort, vive l’Agent » : un modèle qui raisonne, des outils pour agir, une mémoire pour progresser, une boucle pour itérer. Chaque sous-agent d’Understand-Anything coche les quatre cases dans son périmètre. Et le pipeline lui-même, considéré globalement, est un méta-agent qui orchestre les six.

Cette décomposition révèle quelque chose qu’on voit rarement aussi proprement : la spécialisation par sous-agent n’est pas un nice-to-have d’optimisation, c’est ce qui rend la tâche faisable. Demander à un seul agent généraliste de lire toute la codebase, d’en extraire les symboles, de deviner les relations implicites, de consolider, de réviser et de produire un JSON cohérent ; c’est exactement ce que fait Claude Code aujourd’hui sans graphe. Et c’est précisément ce qu’on cherche à éviter. La pipeline démontre que la bonne unité d’exécution n’est pas le LLM, c’est l’agent à mission étroite, multiplié et orchestré.

Le graphe comme actif versionné : la rupture que personne ne nomme

Voici le point que j’ai cherché en vain dans la documentation, dans les threads LinkedIn et dans les retours d’usage : le knowledge graph d’Understand-Anything n’est pas un index volatile. Il est écrit dans .understand-anything/knowledge-graph.json, et la documentation recommande explicitement de le commiter dans le repository Git ; avec git-lfs au-delà de dix mégaoctets. Un post-commit hook (/understand --auto-update) le met à jour incrémentalement à chaque commit, pour qu’il reste synchrone avec le code qu’il décrit.

Ce détail change tout. Dans le RAG d’entreprise classique, l’index est une infrastructure : une base vectorielle hébergée quelque part, qu’il faut maintenir, ré-indexer périodiquement, surveiller, sauvegarder. C’est un système. Dans Understand-Anything, l’index est un fichier. Il vit dans le repo comme package-lock.json ou Cargo.lock. Il est versionné, diffable, partageable, reproductible. Quand un nouveau développeur clone le projet, il récupère le graphe en même temps que le code. Quand une PR modifie l’architecture, le graphe est modifié dans le même commit.

C’est l’équivalent conceptuel d’un schema.lock appliqué à la connaissance : un contrat versionné qui dit voici la cartographie partagée entre les développeurs humains et l’agent IA, et tant que ce fichier n’a pas changé, tout le monde travaille sur la même carte. Le lock-file de dépendances garantit que vous installez les mêmes versions de bibliothèques que vos collègues. Le knowledge graph commité garantit que Claude Code raisonne sur la même architecture que vous. C’est la même mécanique de reproductibilité, étendue à la sémantique du projet.

C’est un déplacement majeur. La connaissance structurée du projet n’est plus un service périphérique, c’est un artefact du projet lui-même. Le graphe devient de la documentation exécutable. Et cette documentation est consommée, non pas par un humain qui la lit, mais par un agent qui l’interroge.

Cela rejoint, sous un autre angle, ce que j’écrivais sur MCP comme problème d’architecture : pour un projet donné, vous n’avez pas besoin de découverte dynamique d’outils, vous avez besoin de navigation déterministe dans un espace fini et connu. Understand-Anything matérialise cet espace dans un JSON. Plus besoin de redécouvrir à chaque session ce que le graphe sait déjà.

Pourquoi c’est cohérent avec « Le RAG est mort, vive l’Agent »

Reprenons la thèse. Dans le RAG classique, la base de connaissance est une muraille : elle se dresse entre le LLM et le monde, et le modèle ne fait que recevoir des chunks pré-filtrés qu’il assemble en réponse. Dans le modèle agentique, la base de connaissance devient un outil parmi d’autres que l’agent appelle quand il en a besoin, dans l’ordre qu’il décide, avec des paramètres qu’il choisit.

Understand-Anything applique exactement ce schéma au code. Avant : Claude Code reçoit (ou réclame) des dumps de fichiers, qu’il agrège mentalement pour reconstruire l’architecture. Après : Claude Code dispose d’un graphe interrogeable, qu’il consulte ciblement. La codebase n’est plus dans son contexte. Elle est atteignable depuis son contexte. C’est la bascule fondamentale.

Et cette bascule n’est pas un détail d’implémentation : c’est la condition pour que les sessions longues redeviennent viables. Tant que comprendre le code consiste à le lire, chaque session est une réinitialisation. Quand comprendre le code consiste à le naviguer via un graphe persistant, la session devient incrémentale. Pour reprendre la formule sur la mémoire persistante, l’amnésie devient optionnelle.

Ce que ça consomme vraiment : l’économie comparée

Soyons honnête sur les chiffres, parce que les retours marketing tournent vite à l’embellie. L’indexation initiale d’Understand-Anything mobilise des agents LLM qui tournent sur le modèle de la CLI qui les invoque ; Claude Sonnet pour Claude Code, GPT pour Codex, Gemini pour Gemini CLI. Sur une codebase de taille moyenne, c’est plusieurs centaines de milliers de tokens consommés à l’indexation, l’équivalent d’une demi-journée d’usage intensif facturée d’un coup.

Le compromis à arbitrer est le suivant : soit l’indexation passe par un modèle haut de gamme et le graphe capte les relations implicites avec finesse (au prix d’un investissement initial réel) soit on redirige la CLI vers un modèle local via ANTHROPIC_BASE_URL (Ollama, llama.cpp), et l’indexation devient gratuite mais la qualité décroche. Un Llama 3.x local rate les inférences subtiles qu’un Sonnet attrape : fonctions sémantiquement liées sans appel direct, héritages traversant plusieurs couches d’abstraction, dépendances injectées via container DI. Et un graphe avec des trous est pire qu’un graphe absent ; l’agent y croit, et il a tort.

En entreprise, le frottement est souvent plus institutionnel que technique : installer un Ollama sur un poste de développement passe par les équipes sécurité, qui bloquent ou imposent une liste de modèles approuvés. Le scénario pragmatique reste celui du coût mutualisé : indexer une fois via une API payante, commiter le graphe, et l’exploiter ensuite à coût marginal pour toute l’équipe. La facture d’indexation devient un investissement projet, pas un coût récurrent par développeur.

Une fois le graphe construit, les requêtes Claude Code remplacent des lectures de fichiers entiers par des consultations ciblées de nœuds.

Le gain réel dépend de trois variables : la taille de la codebase (l’effet est linéaire, voire super-linéaire au-delà d’un certain seuil), le type de tâche (un debug ciblé sur une fonction y gagne moins qu’un refactoring qui touche plusieurs couches), et la longueur de la session (sur une session courte, l’overhead d’indexation initial peut ne jamais être amorti ; sur une session de plusieurs heures, l’économie est mécanique). La règle de pouce honnête : sous mille fichiers, le bénéfice est marginal. Au-dessus, il devient structurant.

À cela s’ajoute la complémentarité avec le prompt caching d’Anthropic : les deux mécanismes attaquent des coûts différents. Le caching réduit le coût des tokens répétés (system prompt, instructions, contexte stable. Le graphe réduit le volume de tokens exploratoires) les lectures de fichiers que l’agent fait pour comprendre. Les deux sont additifs, et activer l’un ne remplace pas l’autre.

Le vrai gain, cela dit, n’est pas chiffré en dollars économisés. Il est qualitatif : Claude Code arrête de tâtonner, ses réponses gagnent en pertinence parce qu’elles s’appuient sur la vraie structure du projet plutôt que sur une reconstruction approximative. C’est une amélioration de la qualité de l’agent, dont la baisse de coût est un effet de bord.

Les limites (parce qu’il y en a)

Tout cela mérite une douche froide. Understand-Anything est un projet open source de mars 2026, qui évolue vite, dont la maturité n’est pas celle d’un produit Anthropic intégré. Plusieurs faiblesses sont connues.

D’abord, la qualité du graphe dépend du modèle utilisé pour l’indexation. Les phases d’analyse mobilisent des agents qui s’appuient sur un LLM ; un modèle faible produit un graphe avec des relations bancales, des nœuds manquants, des types mal attribués. La phase de revue (assemble-reviewer) corrige une partie des problèmes mais ne résout pas tout. Sur un modèle haut de gamme, la qualité est correcte ; sur un modèle local de petite taille, elle décroche.

Ensuite, la synchronisation graphe-code peut désaligner silencieusement. Si le post-commit hook plante, si un développeur commit sans le déclencher, si une fusion mal résolue casse le JSON, le graphe diverge du code. Et un graphe désynchronisé est pire qu’un graphe absent : il fait que l’agent fait confiance à une carte fausse. La discipline de mise à jour est non négociable.

Troisièmement, la valeur ajoutée chute sur les codebases atypiques : scripts, configurations, infrastructure-as-code, projets polyglottes mal délimités. L’AST n’a plus de sens stable, les types de nœuds standards ne capturent plus les relations qui comptent. Sur un repo de DevOps mêlant Terraform, Ansible, Bash et docker-compose, le graphe risque de ne rien révéler que vous ne sauriez déjà.

Quatrièmement, le graphe décrit l’existant, pas le futur. Quand vous attaquez une refonte radicale (passer d’un monolithe à des micro-services, casser une couche d’abstraction obsolète, migrer vers une nouvelle architecture), le graphe est une carte du présent qu’il s’agit précisément de démanteler. Si l’agent s’y fie pour proposer des modifications, il optimise dans la cohérence de la topologie actuelle ; celle que vous voulez quitter. Le risque : un assistant trop docile devient un facteur de conservatisme architectural, suggérant des patches là où il faudrait reconstruire. La parade est doctrinale plutôt que technique : pendant une refonte, le graphe sert à comprendre ce qu’on casse, pas à prescrire ce qu’on construit. Et si vous comptez sur l’agent pour penser une architecture neuve, c’est sans doute que ce n’est pas son rôle.

Cinquièmement, pas de gestion native du multi-repo. Beaucoup d’organisations ne vivent pas dans un monorepo : leur connaissance technique est éclatée entre dix, vingt, cent repositories distincts : un par micro-service, un par client interne, un par bibliothèque partagée. Understand-Anything fonctionne aujourd’hui sur un repository à la fois. Le .understand-anything/knowledge-graph.json est local au repo. Aucune fédération entre projets, aucune résolution cross-repo des appels HTTP entre services, aucun « graphe de graphes » qui matérialiserait l’architecture distribuée. La fonction Subdomain graph merging (Phase 0) que le projet propose ne résout que la fusion de plusieurs sous-domaines à l’intérieur d’un même repo. Pour une équipe qui pense en micro-services, c’est une limite structurante et un rappel que le projet, à six mois d’existence en mai 2026, n’a pas encore mûri sur ce front.

L’écosystème, lui, prend cette direction. Fin avril 2026, un projet adjacent baptisé GitNexus a publié exactement ce qui manque ici : un knowledge graph engine MCP-native, qui expose ses graphes via un serveur MCP standardisé et gère plusieurs repositories indexés en parallèle. Que la convergence vienne d’une évolution d’Understand-Anything, d’une victoire de GitNexus, ou d’un standard MCP partagé entre projets concurrents, la trajectoire est tracée. Le graphe va devenir un service exposé via MCP, exactement comme l’analyse architecturale que je posais sur MCP comme question d’architecture, pas de protocole, le laissait pressentir.

Enfin, et c’est le plus important : un graphe ne remplace pas un bon design de code. Si votre projet est un plat de spaghettis avec des dépendances circulaires, des classes de mille lignes et des conventions de nommage instables, Understand-Anything va vous produire un plat de spaghettis en JSON. L’outil rend lisible ce qui est lisible. Il ne refactorise pas à votre place.

Comment l’intégrer dans un workflow Claude Code propre

L’intégration tire parti de ce que vous avez déjà documenté ailleurs dans votre stack et c’est là que l’avantage se compose.

Un CLAUDE.md minimal cesse de décrire l’architecture en prose : il se contente de pointer vers le knowledge graph et d’indiquer à l’agent qu’il doit l’interroger en priorité. Vous gagnez les centaines de lignes que coûtait la description manuelle, et vous gagnez surtout en fraîcheur ; le graphe est à jour, votre prose ne l’est jamais.

Un Skill dédié explique à Claude quand invoquer /understand plutôt que de partir en exploration. C’est le rôle même des Skills tels que je les ai décrits : un déclencheur conditionnel qui mobilise une compétence spécialisée. Le frontmatter précise que la Skill s’active sur les requêtes architecturales, sur les tâches de refactoring inter-modules, sur les questions du type « où vit la logique X ? ».

Un hook PostToolUse déclenche /understand --auto-update après chaque commit qui touche au code, garantissant que le graphe ne décroche jamais du repository. Pour aller plus loin, un hook PreToolUse peut intercepter les commandes Read, Grep et Glob et rediriger l’agent vers le graphe quand la requête peut être satisfaite par lui.

Vous remarquerez ce qui se passe : aucun de ces points n’est une réécriture des guides existants. Ce sont des activations de ce que votre stack documentaire couvre déjà. C’est ce qui rend cette intégration impossible à reproduire pour quelqu’un qui n’a pas posé les fondations en amont.

Le code n’est plus un texte, et l’agent ne lit plus

La conclusion qui se dessine déborde d’Understand-Anything. La rupture conceptuelle, c’est que la codebase devient un objet consultable plutôt qu’un objet lu. Et que l’agent n’est plus un lecteur véloce mais un navigateur informé.

Cela ne s’arrête pas au code. Le pattern (un index structuré, versionné, interrogé par un agent) vaut pour les schémas SQL, pour la documentation technique, pour les contrats d’API, pour l’infrastructure. Partout où la connaissance d’un projet a aujourd’hui la forme d’un texte plat éparpillé entre Confluence, Notion, GitHub Wiki et les commentaires en-tête de fichier, il existe une version structurée qui ne demande qu’à être extraite et mise à disposition.

L’optimisation des tokens, qui occupe les listicles tech à longueur de mois, est un signal faible. Le signal fort, c’est qu’une génération entière d’outils qui traitaient les bases de connaissance comme des bibliothèques à dévorer est en train de céder la place à des outils qui les traitent comme des cartes à parcourir. Et la différence entre un agent qui dévore et un agent qui parcourt n’est pas de quelques pourcents sur la facture. C’est la différence entre un assistant qui simule la compétence et un assistant qui s’appuie sur une cartographie partagée du projet.

Pour le reste, le repository GitHub attend votre clone et votre /understand. Le ticket d’entrée est gratuit. Le coût de ne pas essayer, lui, continue de grimper à chaque session.