Graphify pour Claude Code : transformer votre dépôt en graphe interrogeable

Graphify Claude Code : transformer un dépôt en graphe interrogeable

Dans un dépôt contenant 800,000 lignes de code, la réponse à une question apparemment simple peut se trouver à six endroits différents : un module Terraform, une migration de base de données, un client généré, un document OpenAPI, un manifeste de déploiement et un guide d’exploitation rédigé il y a deux ans.

Claude Code peut rechercher et lire ces fichiers, mais le travail à l’échelle d’un dépôt est souvent limité par la rapidité avec laquelle l’agent peut découvrir les relations entre eux. Une recherche textuelle de customer_id trouve des occurrences. Elle n’explique pas automatiquement que cet élément :

• customer_id est déclaré dans une migration de base de données,
• exposé par un schéma d’API,
• mappé dans un modèle ORM,
• copié dans la charge utile d’un événement,
• consommé par un processus de traitement en arrière-plan,
• et mentionné dans une procédure de retour arrière en production.

Graphify aborde ce problème en convertissant le contenu du dépôt en un graphe de connaissances : les entités deviennent des nœuds, les références et les dépendances deviennent des arêtes, et Claude Code peut interroger cette structure pour obtenir du contexte supplémentaire.

Il faut toutefois préciser qu’un graphe n’est pas une seconde source de vérité magique. C’est une interprétation indexée de votre dépôt. Sa valeur dépend de la couverture des analyseurs, de la rigueur des mises à jour, des permissions et de la capacité des relations obtenues à répondre à de véritables questions d’ingénierie.

Ce que Graphify apporte à Claude Code

Claude Code dispose déjà de plusieurs moyens utiles pour comprendre un projet :

• Lecture directe des fichiers
• rg et autres recherches dans le shell
• Historique et différences Git
• Instructions du projet dans CLAUDE.md
• Compétences pour les procédures reproductibles
• Serveurs MCP pour les outils et les données externes

Graphify ajoute un mode d’accès différent : la recherche d’informations fondée sur les relations.

Une recherche classique pose la question :

Où ce symbole apparaît-il ?

Une requête sur un graphe pose la question :

Quels services dépendent de ce schéma, quelle infrastructure déploie ces services et quels documents décrivent les conséquences opérationnelles ?

Cette distinction est importante lorsque la tâche couvre plusieurs périmètres de responsabilité ou formats de fichiers.

Un graphe typique peut contenir des nœuds tels que :

Les arêtes peuvent représenter des relations telles que :

• imports
• calls
• implements
• extends
• reads_from
• writes_to
• publishes
• consumes
• deploys
• configured_by
• documented_by
• owned_by
• depends_on

Le vocabulaire exact des nœuds et des arêtes dépend des indexeurs actuels de Graphify et de sa configuration. Considérez le schéma du graphe comme une composante du produit à examiner, et non comme une hypothèse. Avant de construire des prompts autour d’une relation telle que publishes, vérifiez que la version installée la produit effectivement.

Installer Graphify pour Claude Code

Graphify est un projet actif ; les modalités d’installation et les noms des lanceurs peuvent donc changer. Partez du dépôt et utilisez la commande d’installation documentée pour la version que vous adoptez :

git clone https://github.com/Graphify-Labs/graphify.git
cd graphify

Si vous utilisez un paquet publié, il est préférable d’employer la commande du gestionnaire de paquets documentée par le projet plutôt que de copier celle d’un ancien article de blog. Après l’installation, vérifiez trois points avant d’indexer un grand monorepo :

graphify --help
graphify version
graphify config --help

Les commandes ci-dessus illustrent les vérifications à effectuer ; utilisez l’exécutable et les sous-commandes fournis par la version installée.

Pour limiter les risques, une première exécution doit cibler un petit dépôt de test :

mkdir -p /tmp/graphify-fixture
cd /tmp/graphify-fixture

git init
printf 'def charge(order):\n    return order.total\n' > billing.py
printf 'from billing import charge\n' > worker.py

graphify index .

L’indexation initiale combine généralement la découverte, l’analyse, l’extraction des relations et la persistance du graphe. Sur un dépôt réel, examinez la configuration générée et l’emplacement de stockage avant de l’ajouter à la CI. Vous devez savoir si l’index est :

• Local ou hébergé
• Mis à jour de manière incrémentale ou entièrement reconstruit
• Stocké dans une base de données, des fichiers ou un système de stockage embarqué
• Utilisable sans risque en parallèle avec un autre indexeur
• Capable d’exclure les secrets, les artefacts de compilation et les arborescences de dépendances tierces

Pour une intégration à Claude Code, Graphify doit être accessible par le mécanisme d’intégration pris en charge par le projet, généralement MCP. Un fichier local .mcp.json pourrait ressembler à ceci :

{
  "mcpServers": {
    "graphify": {
      "command": "graphify",
      "args": ["mcp", "--project", "."],
      "env": {
        "GRAPHIFY_INDEX": ".graphify/index"
      }
    }
  }
}

Ne considérez pas cette sous-commande précise comme universelle. Confirmez le point d’entrée MCP avec :

graphify mcp --help

Validez ensuite le serveur depuis Claude Code :

/mcp

Vous devriez voir le serveur Graphify et ses outils disponibles. Les noms des outils et la syntaxe des requêtes dépendent de la version. La vérification utile est opérationnelle : demandez à Claude Code de lister les outils du graphe, d’exécuter une requête ciblée et d’indiquer quelle révision du dépôt a été indexée.

Un piège courant consiste à lancer Claude Code depuis le mauvais répertoire. Les chemins relatifs du projet dans .mcp.json, les fichiers d’exclusion et la configuration de Graphify sont résolus à partir du répertoire de travail du processus serveur, qui n’est pas nécessairement celui que vous aviez en tête.

Les relations qui comptent en pratique

Le graphe est particulièrement utile lorsqu’il met en évidence des relations fastidieuses à reconstituer à partir du texte.

Traçabilité du code aux données

Supposons qu’une migration renomme accounts.status à accounts.lifecycle_state. Une recherche textuelle peut identifier les références, mais un graphe peut structurer le périmètre des impacts :

table accounts
  -> column lifecycle_state
  -> migration 2025_04_rename_status
  -> model Account
  -> repository AccountRepository
  -> API response AccountSummary
  -> dashboard query active_accounts

Cela donne à Claude Code un meilleur point de départ pour examiner une migration. Il peut consulter les fichiers réels une fois que le graphe a identifié les éléments qui en dépendent probablement.

Topologie des services et de l’infrastructure

Les relations d’infrastructure sont particulièrement précieuses dans les monorepos où le code applicatif et le code de déploiement cohabitent :

service payments-api
  -> container image payments-api
  -> Kubernetes deployment payments
  -> reads secret PAYMENTS_DATABASE_URL
  -> writes queue payment-events
  -> consumed by reconciliation-worker

Cela aide à répondre à des questions telles que :

• Quel déploiement doit être modifié si un port change ?
• Qu’est-ce qui consomme les messages de cette file d’attente ?
• Quels services partagent cette base de données ?
• Quelle configuration est propre à chaque environnement ?
• Quelle ressource Terraform crée la dépendance ?

Graphify ne peut pas déduire parfaitement le comportement à l’exécution à partir de fichiers statiques. La découverte dynamique des services, la réflexion, la configuration générée et les indirections par variables d’environnement peuvent laisser des lacunes. Utilisez les résultats de topologie comme une carte des impacts, puis vérifiez les arêtes critiques dans la configuration de déploiement et d’exécution.

De la documentation à l’implémentation

La documentation est souvent déconnectée de la recherche dans le code, car la relation est sémantique plutôt que syntaxique. Un guide d’exploitation peut faire référence au « processeur de règlement », alors que le dépôt l’appelle reconciliation-worker.

Si Graphify relie les références de la documentation aux entités du code ou de l’infrastructure, Claude Code peut répondre aux questions opérationnelles avec moins de navigation manuelle :

"Where is the rollback procedure for the component that consumes payment-events?"

La réponse n’est fiable que si les noms utilisés dans la documentation sont associés avec précision aux bonnes entités. Une terminologie obsolète crée des arêtes plausibles mais incorrectes, ce qui est plus dangereux qu’une recherche manifestement infructueuse.

Graphify, les compétences et MCP constituent des couches distinctes

Graphify doit compléter les points d’extension existants de Claude Code plutôt que les remplacer.

Voici une architecture utile :

1. Graphify découvre des entités et des dépendances potentielles.
2. Claude Code utilise ces résultats pour sélectionner les fichiers.
3. Les outils natifs de gestion des fichiers vérifient l’implémentation actuelle.
4. Une compétence applique la procédure de revue ou de modification de l’équipe.
5. Les tests, les linters et les contrôles de déploiement fournissent les éléments de validation finaux.

Par exemple, une compétence de revue des migrations pourrait se trouver dans .claude/skills/review-migration/SKILL.md:

# Review Database Migration

When reviewing a migration:

1. Identify renamed, removed, or changed columns.
2. Query Graphify for code, schema, event, and infrastructure dependents.
3. Read each high-confidence dependent from the working tree.
4. Check backward compatibility for deployed application versions.
5. Run the repository migration and contract tests.
6. Report uncertain graph relationships separately from verified findings.

La compétence définit le processus. Graphify fournit le contexte des relations. MCP assure le transport et délimite les outils.

Cette séparation est importante. Intégrer toutes les connaissances du graphe dans une compétence produirait des instructions statiques qui vieilliraient mal. Intégrer toutes les règles du processus dans Graphify rendrait l’indexeur responsable de décisions qu’il ne peut pas prendre de manière fiable.

Gérer le coût et l’actualisation de l’index

L’indexation a un coût en ressources de calcul, en espace disque, en latence et en complexité opérationnelle. Ce coût ne se limite pas à l’analyse initiale. Les grands dépôts nécessitent également des mises à jour lorsque les branches changent, que les fichiers générés sont reconstruits ou que les graphes de dépendances sont invalidés.

Commencez par les exclusions :

# .graphifyignore
.git/
node_modules/
vendor/
dist/
build/
coverage/
tmp/
*.min.js
*.map
.env
*.pem

La syntaxe peut différer de celle de .gitignore, vérifiez donc la manière dont Graphify gère les fichiers d’exclusion. Excluez explicitement les identifiants d’authentification et les exports sensibles, même s’ils sont déjà ignorés par Git. Un outil qui indexe un fichier peut exposer son contenu par le biais d’une requête.

Adoptez une politique d’indexation par étapes :

• Indexez le code source de l’application, les schémas, l’infrastructure et la documentation tenue à jour.
• Excluez les fichiers générés, sauf s’ils constituent l’artefact de référence.
• Construisez un index complet en CI ou au moyen d’une tâche planifiée.
• Mettez à jour l’index d’une branche de manière incrémentale lorsque cette fonctionnalité est prise en charge.
• Enregistrez le commit source avec les métadonnées du graphe.
• Reconstruisez l’index après toute modification de l’analyseur ou de la configuration.

La révision source doit être visible par l’agent. Une structure de réponse comme celle-ci est bien plus sûre qu’une liste sans précisions :

{
  "query": "dependents of table accounts",
  "indexed_revision": "9f31a7c",
  "generated_at": "2025-05-14T10:22:11Z",
  "results": [
    {
      "entity": "AccountRepository",
      "relationship": "reads_from",
      "target": "accounts",
      "confidence": "high",
      "path": "src/accounts/repository.py"
    }
  ]
}

Lorsque Claude Code modifie un arbre de travail après la dernière indexation, les résultats du graphe constituent un contexte historique. Les fichiers actuels font foi. En pratique, je demande à l’agent d’inclure indexed_revision dans son raisonnement et de revérifier chaque affirmation issue du graphe en la confrontant à l’arbre de travail.

Exactitude, confidentialité et limites en production

Un graphe peut donner à des informations incomplètes l’apparence d’une source faisant autorité. Plusieurs modes de défaillance sont à anticiper :

• Les imports dynamiques et la réflexion ne sont pas détectés.
• Les scripts shell masquent les relations derrière l’expansion des variables.
• Les clients générés masquent le schéma source.
• Les liens de la documentation utilisent des alias que l’analyseur ne reconnaît pas.
• Les fichiers supprimés restent présents jusqu’à l’exécution d’un nettoyage ou d’une reconstruction.
• L’index d’une branche est interrogé alors que l’agent travaille sur une autre branche.
• Les modules d’infrastructure sont interprétés sans les valeurs propres à l’environnement.

Pour les processus en production, exposez le niveau de confiance et la provenance dès que possible. Une relation sans chemin de fichier, révision ou méthode d’extraction est difficile à auditer.

La confidentialité exige la même attention. Les graphes de dépôt peuvent révéler :

• Les noms des services internes
• Les modèles de données des clients et des paiements
• La topologie du réseau
• Des secrets par le nom des fichiers ou les références de configuration
• Des dépendances sensibles du point de vue des vulnérabilités
• De la documentation propriétaire

Conservez les index sensibles en local ou dans le même périmètre de confiance que le dépôt. Configurez MCP selon le principe du moindre privilège, excluez les éléments contenant des secrets et évitez d’envoyer le contenu du graphe à un service hébergé sans l’approbation de l’organisation pour ce flux de données. La capacité de Claude Code à interroger un graphe ne change pas les exigences de contrôle d’accès du dépôt.

La popularité n’est pas non plus synonyme de fiabilité. Un projet peut attirer beaucoup d’attention tout en ayant une couverture d’analyse encore immature, des schémas de graphe instables, des garanties de mise à niveau limitées ou un comportement insuffisant face au volume de changements d’un monorepo. Évaluez-le avec un corpus de cas de test tirés de votre propre dépôt :

• Identifie-t-il les imports et les dépendances de services connus ?
• Supprime-t-il les relations supprimées ?
• L’indexation incrémentale converge-t-elle vers le résultat d’une reconstruction complète ?
• Les utilisateurs peuvent-ils distinguer les résultats obsolètes de ceux dont le niveau de confiance est faible ?
• Le serveur MCP signale-t-il clairement un échec lorsque l’index est indisponible ?
• Les requêtes sont-elles assez rapides pour un travail interactif avec l’agent ?
• Pouvez-vous reproduire l’index en CI ?

Ne faites pas de Graphify un prérequis incontournable pour chaque action de l’agent. Un mode dégradé qui se rabat sur la recherche classique dans les fichiers est essentiel.

Une démarche d’adoption pratique

Commencez par un processus dans lequel la découverte des relations est coûteuse et les erreurs sont visibles, comme les modifications d’API, les migrations de bases de données ou les refactorisations d’infrastructure.

Mesurez les résultats utiles plutôt que la taille du graphe :

• Temps nécessaire pour identifier les composants affectés
• Nombre de composants dépendants manqués lors de la revue
• Taux de relations obsolètes ou incorrectes
• Temps d’indexation après des commits courants
• Échecs des requêtes et fréquence du recours à la solution de repli
• Données supplémentaires exposées au modèle

Utilisez Sonnet 4.6 pour les investigations étendues dans le dépôt lorsque la profondeur du raisonnement compte, Haiku 4.5 pour les tâches de classification légères ou les recherches répétées, et Fable 5, doté d’un contexte plus étendu, lorsque le processus du projet avec un contexte de 1M bénéficie réellement de la conservation de nombreux éléments probants. Le choix du modèle ne corrige pas un mauvais graphe. Un modèle plus petit disposant de relations précises et à jour peut être plus utile qu’un modèle plus grand recevant un export non filtré de l’index.

Le principe pratique pour formuler le prompt consiste à expliciter la provenance :

Use Graphify to identify likely dependents of the `accounts.lifecycle_state`
column. For every result, include its path, indexed revision, relationship,
and confidence. Then read the current files and discard relationships that
do not exist in the working tree. Do not treat graph results as proof.

Cette dernière phrase n’est pas une simple formalité. Elle empêche une couche de contexte obsolète de devenir une autorité incontestée.

Conseils pratiques

• La valeur principale de Graphify réside dans la recherche de relations entre le code, les schémas, l’infrastructure et la documentation.
• Installez l’outil dans une version précise, examinez ses commandes CLI et MCP réelles et testez-le sur un cas de test avant d’indexer un monorepo.
• Laissez Graphify prendre en charge le contexte du dépôt ; utilisez les compétences de Claude Code pour les procédures d’ingénierie reproductibles.
• Incluez la révision de l’index, la provenance et le niveau de confiance dans les réponses du graphe.
• Excluez les secrets, les éléments générés sans intérêt et le contenu tiers inutile.
• Traitez les résultats du graphe comme des pistes à vérifier dans l’arbre de travail actuel.
• Testez l’indexation incrémentale, la gestion des suppressions, l’isolation des branches et le fonctionnement en mode dégradé avant toute adoption en production.
• La popularité peut justifier une évaluation, mais seuls l’exactitude sur votre dépôt et le comportement opérationnel justifient d’en dépendre.