J'ai installé un graphe de connaissances sur Claude Code. 14 jours plus tard, l'audit a tué mon enthousiasme.

Quand j'ai entendu parler de graphify, j'étais convaincu que ça allait améliorer mon code et réduire mes tokens. Il y a 15 jours, je l'ai installé sur 2 projets en production. J'étais sûr d'avoir upgradé mon agent. Deux semaines plus tard, j'ai audité les transcripts JSONL. J'ai dû relire les chiffres deux fois.

Sur 60 sessions, l'agent a déclenché environ 1 500 rappels de hook et invoqué le graphe exactement 0 fois. Le grep a gagné l'arbitrage à chaque fois, pas parce que le graphe était mauvais mais parce que le graphe demandait une étape supplémentaire.

TLDR : Tu peux écrire la plus belle règle du monde dans ton CLAUDE.md, déclarer ton serveur MCP, poser un hook qui ping à chaque commit. L'agent acquiesce, puis fait autre chose. Ce qui change le comportement d'un agent, ce n'est pas le contexte que tu lui donnes. C'est ce que tu retires de son chemin.

J'Avais Vraiment Envie Que Ça Marche

Je me suis donné à fond sur graphify. Triple promesse : mémoire persistante de la codebase, graphe auditable que tu peux lire comme une carte, surprises cross-document que le cache LLM ne peut pas voir. Chiffres publiés dans la fourchette 49-71x d'économies de tokens sur les requêtes qui touchent le graphe proprement. Toutes les cases cochées.

J'ai fait le full pass sur les deux projets : une storefront Next.js sur un backend Convex (290 fichiers environ), et un pipeline de contenu sur lequel je reviens sans cesse (387 fichiers TypeScript). Un pass AST plus une couche d'extraction sémantique, environ 0,30 $ à 1 $ par projet sur Sonnet. Le hook git post-commit est entré, le serveur MCP a été déclaré, la règle CLAUDE.md a été injectée verbatim par graphify claude install. 7 outils visibles dans le panel. Propre.

Puis j'ai poussé plus loin. Fichier de log d'usage pour tracker les victoires. Mémoire Claude dédiée juste pour les retours graphify. Date de review à 7 jours, repoussée à 14 quand les données semblaient maigres. J'avais écrit le calendrier d'évaluation avant d'avoir un seul point de données, ce qui rétrospectivement est le move de quelqu'un qui veut déjà la réponse. (Tu as écrit un calendrier comme ça toi aussi, je ne suis pas le seul.)

J'étais sûr d'avoir juste upgradé mon agent. Le serveur MCP respirait. Le graphe était chaud. Le hook se déclenchait. Je n'avais plus qu'à attendre les gains.

L'Audit Qui A Tué Mon Enthousiasme

Claude Code garde un transcript de chaque session dans un fichier .jsonl sous ~/.claude/projects/<repo>/. Chaque appel d'outil est loggé avec son nom et ses inputs. Une vraie invocation ressemble à "type":"tool_use","name":"mcp__graphify__...". Le deferred_tools_delta de démarrage liste les outils disponibles mais n'est pas une invocation. J'ai grep le premier, ignoré le second.

Voici ce que 14 jours de "je suis sûr que ça marche" ont réellement produit.

grep "tool_use" ~/.claude/projects/pbn/*.jsonl | grep graphify
grep "tool_use" ~/.claude/projects/rentier/*.jsonl | grep graphify

Les chiffres, côte à côte :

• Appels CLI à graphify query / path / explain : 0 sur pbn, 0 sur rentier
• Outils MCP graphify invoqués par l'agent : 0 sur pbn, 0 sur rentier
• Lectures actives de GRAPH_REPORT.md : 1 sur pbn, 0 sur rentier
• Lignes ajoutées à mon log d'usage : 1 ligne sur pbn, fichier jamais créé sur rentier
• Mémoires de projet citant une insight du graphe : 0 sur les deux

L'infrastructure a fait son boulot parfaitement. 290 commits sur le pipeline de contenu et 38 sur la storefront ont été digérés par le hook post-commit sans un seul échec. Zéro dépassement de coût, zéro friction, le graphe est resté frais à travers chaque push. Le serveur MCP bootait proprement à chaque session, les 7 outils étaient visibles dans le panel, la règle était assise en haut de CLAUDE.md où l'agent est censé la lire à chaque cold start. Tout ce que je pouvais contrôler mécaniquement a marché. La seule chose que je ne pouvais pas contrôler, la lecture elle-même, ne s'est pas produite.

Le seul usage productif documenté était un bug 404 sur un site partenaire que je debuggais le 2 mai. Le rapport pointait vers le bon cluster de modules. Bien. Le diagnostic initial était quand même faux, l'agent a accusé humanize.ts, le vrai coupable était mesh.ts:tryInsertLink. Le graphe a aidé à réduire la zone. Il n'a pas résolu. J'ai dû vérifier contre les vrais fichiers .meta.json pour retourner le diagnostic. J'ai économisé peut-être 500 tokens de travail grep et 3 lectures de fichiers. Marginal comparé aux chiffres publiés autour de 49-71x d'économies de tokens, comme documenté par Mustafa Genc sur GoPenAI et le guide d'intégration CLSkills (avril 2026). Ces chiffres sont mesurés dans des benchmarks contrôlés où un agent doit utiliser le graphe. Mon audit mesure l'opposé. Ce qu'un agent fait quand il a le choix.

Le Grep A Gagné Parce Que Grep Est Plus Court

Un agent AI fait un arbitrage temps réel à chaque étape. Quel est le chemin le moins cher vers la solution ? Les règles texte entrent dans cet arbitrage comme des signaux, pas comme des lois. Yajin Zhou l'a dit clairement dans son post de mars 2026 : pour l'IA, les règles ne sont pas des lois, ce sont des suggestions. Christoph Schweres a documenté le côté architectural un mois plus tôt : après compression de contexte, CLAUDE.md change de statut, il cesse d'être une règle et devient une information que l'agent peut peser ou non. C'est exactement ce qui s'est joué à travers mes 1 500 rappels de hook ignorés.

Deux raisons concrètes pour lesquelles graphify a perdu l'arbitrage.

Raison 1, le chemin court gagne toujours. Pour répondre "où est défini X", "qui appelle Y", "qu'est-ce qui touche Z" : grep -r donne les lignes exactes en 1-2 secondes. Lire GRAPH_REPORT.md donne 500 tokens de résumé thématique, puis l'agent doit quand même ouvrir les fichiers. Une étape contre deux. L'arbitrage temps réel choisit le chemin court, peu importe ce que tu as écrit en caps dans CLAUDE.md. Ce n'est pas un bug. C'est le poids tel qu'il a été entraîné.

Raison 2, les règles texte n'ont pas de discipline persistante. Mon hook PreToolUse:Bash a déclenché plus de 1 500 rappels disant à l'agent "3 fichier(s) dans le scope ont changé, relance /graphify update". Pas un n'a déclenché une consultation du graphe. Les rappels sont devenus du bruit à parser et skip. Le pattern est maintenant largement documenté : GitHub issues #18660, #22022, #19635, et le très récent #57200 déposé le 8 mai (le reporter a brûlé 85K tokens à redécouvrir une décision qui était déjà en mémoire, parce que les règles laws.md n'ont pas survécu à la compression de contexte). Mustafa Morbel a bien cadré la distinction dans son article d'avril : CLAUDE.md est consultatif par nature, les hooks sont déterministes. Le texte se débat. La mécanique non.

J'ai écrit sur l'hygiène CLAUDE.md avant, 47 lignes dans mon CLAUDE.md et pourquoi Claude brûle 50 instructions avant même de charger les miennes. Cet article disait d'écrire de meilleures règles. Celui-ci dit que même la règle la mieux écrite reste consultative et perd face à l'arbitrage. Les deux sont vrais. Aucun n'est suffisant.

Où J'Aurais Dû L'Utiliser (Et Où Tu Devrais Probablement)

J'ai fait une erreur de setup. Deux en fait.

Erreur 1, j'ai installé un outil de découverte sur un terrain familier. Les docs graphify sont explicites sur les cas d'usage cibles : une codebase que tu touches pour la première fois, une liste de lecture (papers, tweets, notes), un corpus de recherche, un dossier personnel /raw où tu balances tout. Aucun de mes deux projets n'est dans ces cas. J'ai écrit la moitié du code et relu le reste plusieurs fois. Pareil pour Claude, la mémoire de travail du modèle sur ces repos était déjà chaude. Les surprises cross-document qu'un pass de détection de communauté est censé révéler ne surprennent personne qui connaît déjà les liens. J'ai installé une boussole dans un appartement où j'habite depuis 5 ans.

Erreur 2, je l'ai déployé à froid au lieu de chaud. Un outil de contexte gagne l'arbitrage temps réel quand l'agent n'a pas d'alternative moins chère. Sur un repo frais, grep est encore cher (l'agent balaye à l'aveugle), donc lire le graphe en premier devient le chemin court. Après 3-6 mois d'exposition, grep a un cache de chaleur, et le graphe redevient le détour. J'avais déjà franchi cette ligne il y a des mois sur les deux projets. Au moment où graphify est arrivé, l'agent avait déjà construit ce qui passe pour de la mémoire musculaire dans un système sans état, et cette mémoire musculaire disait "grep d'abord, questions jamais."

Voici la carte d'usage que j'aurais dû respecter dès le premier jour.

Onboarding sur un repo hérité que tu reprends sans le connaître. Le graphe gagne probablement, parce que grep est aveugle au début et une carte topique économise du vrai temps de lecture. C'est le cas que Jo Van Eyck a argumenté dans sa vidéo "AI coding agents are useless on large codebases", et sur ce cadre spécifique il a raison. Plus la surface inconnue est grande, plus une carte globale mérite sa place.

Audit sécurité cross-module sur un repo legacy où tu chasses les dépendances cachées. Cas explicite des docs graphify, et ça fait sens, puisque l'agent a besoin d'une vue globale qu'aucun grep unique ne donne. Tu ne cherches pas une string, tu cherches une topologie.

Liste de lecture mixte (papers + notes + tweets + code de référence) où la détection de communauté fait vraiment ressortir une vue qu'aucun grep ne peut produire. Probablement le cas d'usage le plus fort, et celui le plus proche de la philosophie /raw originale qui a lancé toute la conversation. Les corpus hétérogènes bénéficient le plus de l'extraction structurelle précisément parce que grep cross-formats est une blague.

Pas pour maintenir un projet que tu connais déjà. C'est ce que j'ai fait, et c'était la mauvaise application.

Cette nuance ne sauve pas mon expérience. Elle clarifie ce que j'aurais dû tester en premier. Rajistics a une pièce YouTube intitulée "GraphRAG (you probably don't need it)" qui arrive à une position similaire du côté RAG. La conclusion est la même sur les graphes de connaissance : cas par cas, pas toujours.

(Note de côté qui ne mène nulle part : je remarque sans cesse que les outils que j'installe avec le plus d'enthousiasme sont ceux sur lesquels je lis le moins avant. Les outils ennuyeux que je survole une fois et oublie sont généralement ceux que j'utilise encore 6 mois plus tard. Il y a probablement une leçon là-dessus sur comment l'enthousiasme déforme l'évaluation. Ou peut-être que j'ai juste mauvais goût en outils. Difficile à dire honnêtement.)

La Vraie Leçon : Le Texte Ne Change Pas Le Comportement De L'Agent. La Mécanique Oui.

Ce pattern est plus grand que graphify. Tu donnes à l'agent un nouvel outil, un nouveau doc, une nouvelle règle. Tu l'écris bien. Tu le rappelles dans CLAUDE.md. Tu poses un hook qui ping. L'agent acquiesce. Puis il fait autre chose. Le pattern apparaît dans les issues GitHub, les threads r/ClaudeAI, et au moins une douzaine d'articles Medium récents. C'est le mode d'échec dominant de l'outillage contextuel en 2026.

Ce qui marche vraiment, ce sont 3 leviers mécaniques.

Levier 1, bloquer au lieu de rappeler. Un hook PreToolUse qui refuse l'action alternative force le chemin. Mustafa Morbel a déjà documenté le contraste : CLAUDE.md est consultatif, les hooks sont déterministes. Toute règle qui peut être ignorée sera ignorée dès que l'arbitrage temps réel trouve une route plus courte. Le fix n'est pas une meilleure formulation. Le fix c'est retirer l'alternative du menu. Si ton hook ne fait que rappeler, tu as construit une voix polie que l'agent apprend à ignorer. Si ton hook bloque l'appel, tu as construit un mur.

Levier 2, faire de l'outil le chemin court, pas un détour. Un graphe de connaissance qui répond à la question gagne. Un graphe de connaissance qui pointe vers des fichiers que l'agent doit encore ouvrir perd, parce qu'il a ajouté une étape au lieu d'en retirer une. Même principe pour les serveurs MCP : un serveur qui élimine N appels d'outils gagne, un serveur qui ajoute N+1 perd. J'ai argumenté la même chose sur CLIs versus MCP dans pourquoi les CLIs battent MCP pour les agents AI : les CLIs gagnent précisément parce qu'ils s'insèrent dans le chemin natif de l'agent au lieu de lui demander de détourer dans un handshake JSON-RPC. Le mécanisme se généralise à tout outil contextuel. S'il ajoute une étape, il perd. S'il en retire une, il gagne. C'est tout le jeu.

Levier 3, introduire l'outil au bon moment. Un outil de contexte gagne au cold start, pas en maintenance chaude. C'est l'erreur que j'ai faite avec graphify, mais c'est aussi l'erreur que font les développeurs quand ils ajoutent 200 lignes à leur CLAUDE.md 6 mois dans un projet. Trop tard. À ce moment-là le pattern de comportement de l'agent sur ce repo est fixé par les outils existants (grep, ls, cat, l'arbre de fichiers qu'il a déjà appris à naviguer). Un nouvel outil ajouté par-dessus doit surmonter l'inertie, et l'inertie dans un arbitrage temps réel signifie "ce chemin était pas cher la dernière fois, reprends-le."

Les 3 leviers ont un coût. Ils rendent l'outillage plus invasif. Un hook bloquant t'agace quand tu veux faire une exception. Un outil chemin-court remplace la flexibilité de grep par la rigidité d'un schéma fixe. Un outil cold-start signifie que tu dois planifier ton outillage avant d'avoir un projet, ce que la plupart d'entre nous ne font jamais, parce qu'on installe les outils quand on ressent la douleur, pas avant. Alors tout le monde se tourne vers la couche consultative, écrit plus de lignes dans CLAUDE.md, pose un autre hook de rappel, et se dit que les règles sont assez claires cette fois. J'ai fait ça. Tu l'as probablement fait aussi. La couche consultative est confortable précisément parce qu'elle nous laisse prétendre qu'on a changé le comportement de l'agent sans payer le coût de le changer vraiment.

En fait, attends. Laisse-moi le dire différemment. La couche consultative c'est comme écrire un email bien senti à ton moi passé et t'attendre à ce que ton moi futur obéisse. Bonne chance avec ça. 😅

La leçon vaut au-delà de Claude Code. Si tu construis un workflow AI qui dépend du modèle suivant des règles écrites, tu paries sur une propriété que le modèle n'a pas. Le modèle a des poids, pas des lois. J'ai écrit sur un angle connexe dans Vibe Coding, For Real : les vibe-coders croient qu'écrire les bonnes règles à l'agent suffit pour shipper. Shipper vient de la mécanique du build, pas de la prose autour. Même principe ici, mis à l'échelle de la couche outillage.

Audite Tes Propres Transcripts Avant De Faire Confiance À Tes Propres Règles

Ma découverte sur graphify n'est pas que l'outil est mauvais. L'outil marche comme annoncé quand l'agent l'utilise vraiment. Le problème c'est que l'adoption d'outils par les agents est 10 fois plus dure que l'installation d'outils. Tout outil qui demande à un agent de changer son chemin par défaut passe par le même arbitrage temps réel. Mon CLAUDE.md y passe, mes hooks de rappel y passent, même les prompts dont je suis le plus fier y passent. Tout le monde a son graphify, et ils ne le savent pas jusqu'à ce qu'ils auditent.

Alors audite. La commande tient sur une ligne :

grep "tool_use" ~/.claude/projects/<repo>/*.jsonl | grep <tool_name>

Compte les vraies invocations. Compare avec ce que ton CLAUDE.md, tes hooks, et tes règles prétendent que l'agent devrait faire. L'écart c'est le coût réel de ce que tu as écrit en mots. Si l'écart est zéro, tu sais quoi faire ensuite : déplacer les règles qui comptent du texte vers la mécanique. Le reste peut rester consultatif, personne ne le lit de toute façon.

Un graphe de connaissance que l'agent ne lit pas n'est pas un outil. C'est de la documentation. Pareil pour tes règles. C'est la vie.

Sources

• Dépôt et docs graphify, github.com/safishamsi/graphify
• Christoph Schweres, Claude Code Ignores the CLAUDE.md, HOW Is That Possible? (Fév 2026)
• Yajin Zhou, Why an AI Agent Broke Its Own Rules (Mars 2026)
• Mustafa Morbel, Taming Claude Code: A Guide to CLAUDE.md and Hooks (Avril 2026)
• Mustafa Genc, Graphify: Build a Knowledge Graph From Your Entire Codebase (GoPenAI, Avril 2026)
• Issues GitHub anthropics/claude-code #18660, #22022, #19635, #57200
• Jo Van Eyck, AI coding agents are useless on large codebases. Unless you do THIS. (YouTube)
• Rajistics, GraphRAG (you probably don't need it) (YouTube)

Cet article peut contenir des liens d'affiliation. Si tu cliques dessus, je pourrais gagner une petite commission, ça ne te coûte rien, et ça m'aide à continuer à livrer des articles de qualité chaque jour pour ton plaisir de lecture.