Créer un outil local de graphe de code que les agents IA peuvent interroger

## Construire le graphe de code en local à partir de l’arbre syntaxique, pas de résumés IA Conservez une analyse du projet locale et déterministe. Déduisez les symboles, les relations et les fichiers à partir des arbres syntaxiques plutôt que des résumés d’un modèle de langage, stockez l’état propre au projet dans une base de données locale indexée et exposez le graphe de connaissances obtenu au moyen d’une bibliothèque, d’une interface en ligne de commande ou d’un protocole pour agents. Organisez le système sous la forme d’une chaîne de traitement en couches : - l’extraction analyse le code source et produit des symboles canoniques ; - la résolution relie les importations, les noms, les frameworks et les autres relations ; - les requêtes de graphe répondent aux questions sur les appelants, les appelés, les chemins et les incidences ; - le formatage du contexte prépare du Markdown ou du JSON compact pour les systèmes consommateurs. Maintenez les analyses lourdes hors du fil d’exécution principal. Faites passer les couches par un unique point d’entrée public et faites-en la seule interface de bibliothèque prise en charge. Si un même exécutable sert intentionnellement d’installateur, d’indexeur et de serveur de protocole, testez tous ces rôles avec ce même artefact. Maintenez une seule source de référence pour les instructions des outils destinées aux agents, de préférence la réponse d’initialisation du protocole. Ne dupliquez pas les mêmes instructions dans le fichier de dépôt de chaque client, car les copies divergent et rendent les mises à niveau ou la désinstallation incomplètes. ## Fixer la version de l’environnement d’exécution et inclure dans le build les fichiers autres que le code Identifiez et utilisez les commandes documentées du dépôt pour la compilation, le développement, le nettoyage, les tests, l’évaluation et la CLI locale. Respectez la plage fixée de l’environnement d’exécution et signalez clairement tout échec en dehors de celle-ci ; une version majeure plus récente n’est pas automatiquement compatible, et l’exécution depuis le code source peut exiger une version minimale plus stricte qu’une distribution empaquetée. Traitez les ressources nécessaires à l’exécution comme une partie du contrat de compilation. Copiez les schémas de base de données, les grammaires d’analyseurs, les modules WebAssembly et les autres fichiers sans code dans la distribution. Chaque fois qu’une nouvelle ressource est ajoutée, actualisez l’étape de copie, sinon elle ne sera pas distribuée. Commencez la vérification par un fichier de test ciblé ou un motif de nom, puis exécutez la suite directement concernée. Maintenez les suites d’évaluation séparées lorsqu’elles créent des jeux de test ou notent un comportement au lieu d’exécuter des tests unitaires ordinaires. Utilisez le comportement réel du stockage lorsque sa sémantique est importante. Créez des répertoires temporaires isolés, nettoyez-les après chaque test et vérifiez le mode réel de la base de données au lieu de le masquer par des simulations. ## Unifier les types de nœuds et d’arêtes et garder l’API publique réduite Définissez les types canoniques de nœuds et d’arêtes dans un schéma unique. Les extracteurs et les résolveurs doivent produire exactement ces chaînes ; n’introduisez pas de variantes presque identiques qui diviseraient silencieusement les requêtes, les parcours ou les données sérialisées. Gardez l’API publique restreinte. Réexportez les types pris en charge depuis le point d’entrée public et imposez aux adaptateurs de ligne de commande et de protocole d’utiliser le même service central au lieu de le contourner. Formulez les affirmations sur le stockage de manière explicite et vérifiable. Si le produit dispose d’un seul moteur de base de données pris en charge avec journalisation anticipée des écritures et recherche en texte intégral, indiquez ce moteur réellement actif, gardez tout adaptateur de compatibilité léger et ne laissez pas entendre qu’une solution de repli native ou WebAssembly non mise en œuvre existe. Lorsque vous ajoutez un langage, un framework, une requête ou un champ de schéma, mettez à jour ensemble l’extracteur ou le résolveur responsable, le contrat public, la sérialisation, les tests et les instructions destinées aux utilisateurs. ## Installer dans plusieurs clients IA sans casser leurs réglages et désinstaller proprement Modélisez chaque client pris en charge comme une cible disposant de son propre emplacement de configuration, de son format et de ses arguments de protocole. Ajoutez un nouveau client au moyen d’une implémentation de cible et d’une entrée de registre, plutôt que de disperser des conditions dans l’installateur. Modifiez la configuration avec précision. Préservez les tables et les listes TOML sans rapport, conservez la mise en forme et les commentaires du JSON avec commentaires, privilégiez une variante de fichier prise en charge qui existe déjà et ne créez la valeur par défaut documentée que pour une nouvelle installation. L’installation doit être idempotente, la réinstallation doit réparer automatiquement un état partiel et la désinstallation ne doit annuler que les modifications appartenant à l’installateur. Utilisez des marqueurs stables pour supprimer les blocs d’instructions obsolètes, mais conservez les instructions actuelles des agents dans leur source unique lors de l’exécution au lieu d’en écrire une autre copie. Couvrez chaque cible au moyen de tests de contrat paramétrés portant sur la préservation des réglages voisins, les réexécutions identiques octet par octet, la désinstallation réversible et la récupération d’un état partiel. Préservez les corrections du répertoire de travail propres à chaque client, par exemple l’insertion d’un chemin de projet explicite lorsqu’un client lance les sous-processus du protocole depuis le mauvais répertoire. ## Améliorer les outils de recherche que les agents utilisent déjà Avant de créer une fonction de recherche, demandez-vous si elle permet à un outil que l’agent appelle déjà d’en faire davantage avec les données qu’il fournit déjà. Ne comptez pas sur le fait que l’agent apprenne à utiliser un nouvel outil, adopte un autre style de requête ou remarque des exemples et des textes d’initialisation peu visibles. Utilisez des entrées précises pour obtenir des réponses précises. Un outil principal d’exploration doit accepter un ensemble compact de noms de symboles, y compris des noms qualifiés, et relier le flux entre eux. Un outil secondaire consacré aux nœuds doit renvoyer le code source complet ainsi que le contexte des appelants et des appelés ; lorsqu’un nom est ambigu, il doit renvoyer toutes les surcharges plausibles dans une seule réponse. N’intégrez pas de réponses précises sur les flux dans un outil imprécis en langage naturel qui ne peut pas distinguer les points de terminaison. Améliorez la couverture au sein des outils que les agents choisissent déjà, notamment par l’extraction statique et les relations dynamiques fondées sur des preuves. Optimisez la latence réelle et le nombre d’appels d’outils ainsi que l’utilisation des jetons. Mesurez l’utilisation totale sur l’ensemble des tours, et pas seulement dans la réponse finale, car les économies proviennent d’un nombre réduit de tours avec un contexte accumulé plus restreint. ## Renvoyer des réponses qui évitent à l’agent de revenir à la lecture directe des fichiers Présentez les situations attendues sous la forme de réussites. Un projet non indexé, un symbole manquant ou un fichier situé hors de l’index doit renvoyer des instructions concrètes sans indicateur d’erreur. Réservez les véritables erreurs aux refus de sécurité et aux dysfonctionnements réels, et n’ajoutez une consigne de nouvelle tentative limitée que lorsqu’une nouvelle tentative est appropriée. Exposez l’interface des outils même lorsque la racine actuelle n’est pas indexée. Expliquez comment sélectionner un projet indexé, mais laissez l’indexation à la décision de l’utilisateur. Masquer les outils au démarrage peut perturber les dépôts monolithiques et les sessions commencées avant l’indexation. Augmentez de manière monotone les budgets d’appels d’exploration et de sortie en fonction de la taille du dépôt : - moins de 500 fichiers : 1 appel, environ 18 000 caractères et 3 800 caractères par fichier ; - 500 à 4 999 fichiers : 2 appels, environ 28 000 caractères et 6 500 caractères par fichier ; - 5 000 à 14 999 fichiers : 3 appels, environ 35 000 caractères et 7 000 caractères par fichier ; - 15 000 à 24 999 fichiers : 4 appels, environ 38 000 caractères et 7 000 caractères par fichier ; - 25 000 fichiers ou plus : au maximum 5 appels, environ 38 000 caractères et 7 000 caractères par fichier. Une tranche supérieure ne doit jamais recevoir un budget par fichier inférieur à celui d’une tranche inférieure. Ne dites jamais à l’agent de revenir à la lecture directe des fichiers ; dirigez-le vers un autre appel au graphe et précisez que le code source renvoyé doit être considéré comme déjà lu. ## Relier de bout en bout les flux de callbacks et d’événements L’analyse statique ne détecte pas les fonctions de rappel, les observateurs, les émetteurs d’événements, le rendu réactif, les descripteurs et les autres formes de répartition indirecte. Ajoutez des synthétiseurs à portée étroite ou des résolveurs de frameworks uniquement lorsqu’ils peuvent relier le flux canonique avec des preuves défendables. Marquez chaque arête synthétisée comme heuristique, consignez le mécanisme qui l’a produite et incluez le site d’enregistrement ou de raccordement. Présentez cette provenance avec le flux afin que les systèmes consommateurs puissent distinguer les faits analysés des relations déduites. Une couverture partielle est pire qu’une absence de couverture lorsqu’elle expose un saut indirect, mais laisse la limite suivante rompue. Fermez le flux depuis l’action qui le déclenche jusqu’à son effet visible, mesurez de nouveau l’agent et ne distribuez pas un chemin relié à moitié qui impose encore une reconstruction manuelle. Aux limites de l’environnement d’exécution qui ne peuvent pas être déduites de manière sûre, préférez le silence à une arête incorrecte. Vérifiez que la réindexation ne gonfle pas le nombre de nœuds et contrôlez par sondage la précision des arêtes synthétisées avant d’étendre un résolveur. ## Tester le comportement de l’agent sur de vrais dépôts, sous Windows et Linux Pour chaque langage et chaque framework, testez de petits, moyens et grands dépôts réels avec au moins 3 questions distinctes sur les flux. Choisissez un flux canonique de bout en bout pour chaque framework plutôt que des symboles isolés qui évitent ses limites difficiles de répartition des appels. Exécutez des sondes déterministes sur l’artefact compilé. Confirmez que l’exploration relie les points de terminaison attendus dans les limites du budget, que le nombre de nœuds reste stable après réindexation et que les arêtes heuristiques disposent d’une provenance précise. Exécutez des tests A/B avec agents au moins 2 fois par branche expérimentale, en utilisant le même modèle minimal choisi délibérément et le même effort de raisonnement. Consignez la durée, le nombre total d’appels d’outils, les lectures directes de fichiers et les recherches textuelles ; communiquez des fourchettes plutôt qu’une unique exécution favorable. Préchauffez un processus de protocole persistant lorsque la latence de démarrage masquerait autrement l’outil, et évaluez la connexion à partir des appels réels plutôt que d’une capture d’initialisation. Exigez approximativement zéro lecture directe et zéro recherche dans les limites du budget d’exploration du dépôt, une exécution plus rapide que celle du groupe témoin et aucune régression dans un dépôt témoin. Validez le comportement propre à chaque plateforme sur la plateforme réelle. Séparez explicitement les affirmations qui ne valent que sous Windows de celles qui valent hors de Windows. Sous Linux, compilez avec des dépendances natives de la plateforme nouvellement installées dans un conteneur jetable et utilisez un processus init afin que les processus enfants terminés soient récupérés. Sous Windows, utilisez un système de fichiers local et des dépendances nouvellement installées dans une véritable machine virtuelle ; comparez les échecs suspects à la branche par défaut avant d’en attribuer la cause. ## Rédiger les notes de version et laisser la publication au processus de release automatique Consignez les changements à venir dans une section Unreleased. Ne créez pas à l’avance le prochain bloc de version lorsque le processus de publication promeut automatiquement le contenu de la section Unreleased. Rendez les notes de publication utiles aux utilisateurs : - ne regroupez le contenu sous des titres destinés aux utilisateurs pour les fonctionnalités, les corrections, la sécurité ou les changements incompatibles que lorsque cela s’applique ; - rédigez pour chaque puce une phrase en langage clair expliquant la fonctionnalité ou le symptôme corrigé ; - omettez les chemins internes, les symboles d’implémentation, les détails des mesures de performance et les sections vides ; - conservez les références utiles aux tickets, les noms des plateformes prises en charge et les commandes réellement saisies par les utilisateurs. Laissez le processus automatisé de publication synchroniser les versions du fichier de verrouillage, promouvoir le journal des modifications, créer les paquets propres aux plateformes, générer les sommes de contrôle, publier la version et publier les paquets. N’incrémentez les versions que sur demande explicite et ne publiez pas manuellement les paquets, ne poussez pas les commits de publication et ne créez pas de balises lorsque ces actions appartiennent au processus. Avant d’agir sur un ticket, un commentaire de revue ou un rapport externe, associez-le à une date et comparez l’état publié, l’état fusionné mais non encore publié et la branche actuelle. N’attribuez pas une correction en cours à ce que l’auteur du rapport pouvait voir auparavant. Traitez les exigences du produit comme des décisions des utilisateurs et non comme des faits déduits du graphe de code. Versionnez chaque URL d’image de la documentation et incrémentez son identifiant de requête chaque fois que la ressource change afin que les caches ne continuent pas à servir des octets périmés.