Blog Maguyva

Un contexte qui voyage

Mon, 07 Sep 2026 00:00:00 GMT

L’indexeur de Cursor est excellent dans Cursor. La complétion, l’édition en ligne, le chat et l’agent dans cette fenêtre s’appuient déjà sur un index de projet que Cursor gère pour l’espace de travail ouvert. Si Cursor est la seule surface où vous écrivez, et que cet index trouve déjà les bons fichiers, restez-y. C’est le cas honnête du « restez où vous êtes » , et c’est à raison la première phrase de cette page.

Ce texte parle de l’autre moitié d’une semaine ordinaire. Le même dépôt est aussi ouvert dans Claude Code, interrogé depuis Codex CLI, revu sur une seconde machine, ou consulté par un agent tournant en CI. La question n’est pas « quel indexeur est le meilleur » . La question est de savoir si la carte à laquelle l’agent fait confiance dans une fenêtre est la même que celle à laquelle il fait confiance dans la suivante.

Maguyva est cette carte qui voyage. C’est une couche de contexte de code MCP distante. L’agent l’interroge de la même façon qu’il interroge tout autre outil MCP. Les résultats reviennent sous forme de chemins classés avec des numéros de ligne. Cursor reste l’éditeur. Le contexte est ce qui se déplace.

À quoi sert l’indexeur de Cursor

L’indexation intégrée de Cursor existe pour que le chat, l’agent et la recherche dans l’éditeur puissent récupérer du code pertinent au lieu de dépendre uniquement de ce qui tient dans la fenêtre de contexte brute du modèle. C’est le bon design pour un IDE. L’index est natif à Cursor. Ce n’est pas un serveur MCP et il n’est accessible depuis aucun autre client.

Voici comment cela fonctionne, tel que décrit dans la documentation publique de Cursor et par Cursor elle-même au moment de la rédaction : le chemin de recherche principal n’est plus un index d’embeddings dans le cloud. L’équipe de Cursor a déclaré sur son forum communautaire que la recherche sémantique/par embeddings dédiée est progressivement abandonnée au profit d’une récupération basée sur grep, car les modèles actuels explorent suffisamment bien un arbre vivant par eux-mêmes. À sa place se trouve Instant Grep, un index de recherche local construit à partir de n-grammes, de listes inversées et de filtres de Bloom, conservé dans une table de correspondance mappée en mémoire, de sorte que les requêtes se résolvent sur la machine du développeur plutôt que sur un serveur.

L’index lui-même vit dans le propre répertoire .git/cursor/ du dépôt, ancré à un commit git précis ; les modifications depuis ce commit se superposent au lieu de déclencher une nouvelle analyse, et l’index ne se reconstruit que lorsque l’état local a fortement dérivé de ce sur quoi il a été construit. Comme il se trouve dans .git, il n’est jamais suivi ni poussé — supprimez le dossier, et l’index disparaît. .gitignore est respecté par construction, puisque seul le contenu suivi par git est éligible, et .cursorignore est appliqué sur le chemin de lecture. Il n’y a plus d’étape d’embedding côté serveur ni de base de données vectorielle distante dans ce chemin. La documentation antérieure décrivait une conception assistée par le cloud — chiffrement des blocs, synchronisation par arbre de Merkle, réutilisation d’index entre coéquipiers — et l’équipe de Cursor a depuis indiqué que cette conception est abandonnée, donc ce texte ne la décrit plus comme actuelle.

Un atout dans l’éditeur est le sous-agent Explore de Cursor. Il peut lancer plusieurs recherches parallèles dans sa propre fenêtre de contexte, sur un modèle plus rapide, et ne renvoyer que les résultats pertinents, de sorte que la conversation principale ne gonfle pas avec des résultats de recherche. C’est une vraie force propre à l’éditeur. Gardez-la.

Les espaces de travail multi-racines sont pris en charge : le contexte de chaque dossier ouvert est disponible pour l’agent. Certaines fonctionnalités dépendantes de git, comme les worktrees, sont désactivées dans les configurations multi-racines, et les Cloud Agents ne prennent pas du tout en charge les espaces de travail multi-racines.

Rien de tout cela n’est une raison de quitter Cursor. C’est une description précise d’une carte excellente là où elle vit.

Ce que « voyager » signifie vraiment

Une carte voyage quand les mêmes questions renvoient le même type de réponse, avec des citations que vous pouvez ouvrir, depuis plus d’un client.

Dans Cursor : « Où parseConfig est-il défini, et qui l’appelle ? »
Dans Claude Code, sur le même dépôt : la même question.
Dans Codex CLI, sur une machine de revue qui n’a jamais ouvert la fenêtre Cursor : la même question.
Dans un agent CI qui parle MCP : la même question, contre le même instantané hébergé.

Si chaque surface construit son propre index privé, vous n’avez pas une carte. Vous avez plusieurs caches qui divergent. L’index de l’éditeur peut être à jour pour l’arbre sur le disque. La session CLI peut avoir un jour de retard. Le job CI peut regarder un checkout différent. L’agent continuera pourtant de paraître sûr de lui.

L’indexeur de Cursor n’est pas censé résoudre cela. Comme il vit dans l’éditeur, le contexte qu’il construit est pour cet éditeur. Un lecteur qui a aussi besoin d’une CLI, d’un pipeline CI ou d’un autre éditeur a besoin d’un outil séparé pour ces surfaces. C’est un fait de périmètre, pas un défaut. Maguyva est cet outil séparé.

Un nombre de langages publié pour l’indexeur de Cursor n’est pas indiqué dans les notes que ce texte est autorisé à utiliser. Maguyva publie plus de 279 langages et technologies textuelles. Les tarifs de Cursor ne sont pas non plus repris ici ; voir leur page de tarification. Maguyva facture par espace de travail, pas par siège, avec des offres publiées à 0 $, 19 $, 49 $ et 149 $ selon l’empreinte indexée et la taille de l’espace de travail.

Une carte hébergée, tous les clients MCP

Maguyva est un serveur MCP distant. Vous connectez GitHub, choisissez les dépôts, et le pipeline cloud construit les symboles, les arêtes du graphe et une carte classée. Vous ajoutez une clé API à la configuration MCP du client que vous utilisez déjà. Maguyva propose des guides de configuration pour 24 clients MCP documentés — Cursor inclus — et peut se connecter à d’autres clients compatibles MCP prenant en charge la configuration standard.

La page de configuration Cursor est le chemin spécifique à l’éditeur si c’est là que vous travaillez. Le même serveur répond à Claude Code, VS Code, Windsurf, Codex CLI et les autres. Vous ne changez pas d’éditeur. Vous donnez à chaque agent la même surface d’outils : 11 outils MCP orientés client à travers la recherche, les symboles, l’analyse de dépendances, la récupération de fichiers, le contexte de dépôt et des workflows utilitaires déterministes. Les récupérations sémantique, structurelle, par graphe et textuelle sont fusionnées en résultats classés.

C’est là l’avantage de la portabilité. Les citations que vous avez vérifiées dans Cursor ce matin ont la même forme que celles que Codex CLI renverra ce soir. Chemin de fichier et numéro de ligne. Ouvrez-les. Si elles sont fausses, vous le voyez. Si elles sont justes, la prochaine modification a un endroit où atterrir. L’affirmation validée est moins de modifications hallucinées, pas la promesse que chaque modification est correcte.

La fraîcheur est publiée. Les instantanés sont horodatés, afin que l’agent sache quelle version de l’arbre il lit. La cadence de reconstruction est quotidienne sur le plan gratuit et horaire sur les plans payants. La limite honnête est le travail local non synchronisé : une modification qui n’existe que dans un arbre de travail n’est pas encore dans la carte hébergée. Cette limite est la même quel que soit le client depuis lequel vous interrogez, et c’est justement le point. La dérive entre clients n’est plus une seconde limite cachée.

La documentation donne la boucle d’activation qui s’applique à chaque client : indexer un dépôt que vous connaissez déjà, connecter le client, poser une question que vous pouvez vérifier. Faites-le une fois dans Cursor. Refaites-le depuis la CLI que vous utilisez réellement les jours de revue. Si les deux réponses citent le même gestionnaire, la carte a voyagé.

Comment les deux cartes coexistent

Utilisez les deux. Ce ne sont pas des alternatives au sens d’une page de comparaison.

Gardez l’indexeur de Cursor actif pour le projet sur le disque. Laissez Explore, Instant Grep et l’agent dans l’éditeur l’utiliser. Cette boucle est native et rapide.
Ajoutez Maguyva comme serveur MCP dans Cursor pour que la même session puisse aussi interroger la carte d’espace de travail hébergée. Cursor est un client Maguyva documenté. Vous ne choisissez pas un index en supprimant l’autre.
Ajoutez le même serveur Maguyva à Claude Code, Codex CLI, ou tout autre client MCP qui touche le dépôt. Une seule forme de clé API. Un seul espace de travail.
Si un agent CI est compatible MCP, pointez-le vers le même serveur. Il lira le même instantané horodaté que le portable.

L’index de l’éditeur reste le meilleur outil pour « ce qui est sur le disque dans cette fenêtre, maintenant » . La carte hébergée est le meilleur outil pour « à quoi ressemble cet espace de travail pour chaque agent qui le touchera aujourd’hui » . Ces phrases ne sont pas en concurrence.

Les quotas d’espace de travail sont publiés sur la page de tarification : dépôts, lignes indexées et utilisateurs, facturés par espace de travail. Agents et humains partagent le même compte d’utilisateurs. Commencez gratuitement sur un dépôt que vous savez déjà évaluer. Augmentez l’espace de travail seulement après que les citations ont survécu au contact avec l’arbre.

Ce que cette page n’affirme pas

Elle n’affirme pas que l’indexeur de Cursor est faible, incomplet, ou une raison de changer d’éditeur. La première phrase de ce texte est l’inverse.

Elle n’affirme pas que Maguyva remplace Instant Grep ou le sous-agent Explore. Ce sont des fonctionnalités de Cursor. Elles restent dans Cursor.

Elle n’invente pas de nombre de langages, de chiffre de latence, ni d’économie de tokens pour l’un ou l’autre produit. Les chiffres inconnus restent non publiés.

Elle ne prétend pas que le travail local non poussé se trouve dans la carte hébergée. Les instantanés horodatés rendent cette limite visible. Ils ne la suppriment pas.

Le test est ordinaire. Indexez un dépôt que vous connaissez déjà. Posez une question que vous pouvez vérifier, d’abord dans Cursor, puis dans un second client MCP. Un contexte qui voyage, c’est la même citation aux deux endroits.

// same map, wherever you opened it.

D'abord la carte, ensuite la revue

Mon, 07 Sep 2026 00:00:00 GMT

Deux tâches différentes se situent de part et d’autre d’une pull request. Avant que l’agent n’écrive, il a besoin d’une carte de l’arbre qu’il s’apprête à modifier. Une fois que l’agent a ouvert une PR, quelque chose devrait lire ce changement au regard du reste du système et laisser des commentaires qu’un humain peut exploiter.

Ces tâches se ressemblent de loin car toutes deux impliquent de « comprendre la base de code » . Ce ne sont pas le même produit. L’une répond à « où cette modification devrait-elle atterrir ? » . L’autre répond à « qu’est-ce que ce diff a cassé qu’un linter ligne par ligne va manquer ? » . Les confondre produit un premier jet plus mauvais et une revue plus bruyante.

Ce texte est un guide de workflow conjoint. Maguyva est la carte que l’agent interroge en premier. Greptile est l’agent de revue qui commente la PR ensuite. Le duo est complémentaire par construction : Maguyva ne relit pas les pull requests, et Greptile ne remplace pas la couche de contexte que l’agent a utilisée pour les écrire.

Pourquoi cette répartition est utile

Un agent de code qui part de priors d’entraînement plus quelques fichiers collés inventera un chemin plausible et le modifiera. C’est l’échec du mauvais fichier, et c’est un problème de récupération. Maguyva est une couche de contexte de code MCP distante : récupération sémantique, structurelle (AST), par graphe/dépendance et textuelle, fusionnée en résultats classés, plus recherche de symboles et récupération de fichiers. Les réponses fondées reviennent sous forme de path/file.ext:line, afin que vous puissiez rejeter une erreur avant qu’un correctif n’existe. L’affirmation reste modeste : moins de modifications hallucinées. Le modèle peut toujours deviner. La première étape cesse simplement d’être une supposition.

Greptile est un agent de revue de code par IA. Selon leurs propres mots, il relit automatiquement chaque pull request avec une compréhension complète de la base de code, et positionne cela face aux linters traditionnels qui vérifient les fichiers isolément plutôt que le système entier. La configuration consiste à installer l’application GitHub ou GitLab et à sélectionner des dépôts. Il n’y a aucun index local à faire tourner. L’hébergement se fait sur Greptile Cloud (ils déclarent une conformité SOC 2 Type II, avec un rapport disponible sur demande), avec une option auto-hébergée offerte aux entreprises.

Leur propre déroulé numéroté est : se connecter et construire un graphe de dépendances de chaque fonction, classe et dépendance ; à chaque pull request, analyser le changement en utilisant ce graphe complet du dépôt et publier les résultats sous forme de commentaires de PR avec des corrections suggérées, en environ trois minutes ; chaque commentaire peut transmettre le problème à un agent de code que l’équipe utilise déjà. Ils déclarent aussi lire les commentaires humains passés sur les PR au fil du temps pour apprendre les standards de code d’une équipe et réduire les suggestions bruyantes. Leur système d’apprentissage aurait, selon eux, besoin de 2 à 3 semaines pour s’adapter.

C’est de la revue, pas de la rédaction. L’atout de Greptile est le contexte du graphe complet du dépôt sur le changement déjà atterri dans une PR, puis une boucle fermée qui envoie le résultat à Claude Code, Codex, Conductor, Cursor ou Devin. L’atout de Maguyva est la carte classée que l’agent a interrogée avant que ce changement ne soit écrit. Utilisez les deux. Ne demandez à aucun des deux de faire le travail de l’autre.

Une intégration produit de première partie Maguyva–Greptile n’est pas annoncée. Vous n’en avez pas besoin. Maguyva parle à l’agent via MCP. Greptile parle à GitHub ou GitLab via son application. Ils se rencontrent au niveau de la pull request. Pas de script de liaison, pas de cron qui relie un outil à l’autre. Le duo se passe de bash parce que chaque produit occupe déjà la surface qui lui appartient.

Ce que ceci n’est pas

Ce n’est pas un dénigrement de Greptile. Ce n’est pas une page « changez de relecteur » . Greptile a été lancé sur Hacker News le 5 mars 2024 en tant qu’entreprise Y Combinator W24, et ce fil de discussion est la façon dont beaucoup de gens ont découvert le produit. Si c’est comme cela que vous les avez trouvés, gardez-les. Cette page est la moitié avant manquante de cette boucle : ancrer l’agent pour que la PR que Greptile voit vise déjà les bons fichiers.

Les supports marketing de Greptile mettent en avant des affirmations de vitesse de revue et de détection de bugs. Traitez-les comme les propres affirmations de Greptile, pas comme des chiffres vérifiés indépendamment. Ce texte ne les répète pas comme des faits.

La couverture linguistique relève de la même honnêteté. Greptile présente son support comme couvrant tous les langages de programmation plutôt qu’une liste énumérée ; un chiffre précis n’est pas indiqué. Maguyva publie plus de 279 langages et technologies textuelles, avec une distinction technique (AST soutenu par un parseur contre texte seul) sur le site quand la question est technique. Ce sont des produits différents qui font des affirmations différentes. Ne les mélangez pas.

Les tarifs de Greptile ne sont pas indiqués dans les notes que ce texte est autorisé à utiliser. Des plans payants existent ; voir leur page de tarification. Maguyva facture par espace de travail, pas par siège. Les plans démarrent gratuitement. La page de tarification liste les niveaux publiés si vous avez besoin des chiffres d’espace de travail.

Workflow

Trois étapes nommées. Exécutez-les dans cet ordre. N’en sautez aucune la première fois que vous essayez ce duo.

1. Contexte Maguyva

Indexez un dépôt que vous connaissez déjà. Connectez le client MCP dans lequel vous écrivez déjà — Claude Code, Cursor, Codex CLI, VS Code, Windsurf, ou un autre client compatible MCP. Maguyva propose des guides de configuration pour 24 clients MCP documentés et peut se connecter à d’autres clients prenant en charge la configuration MCP standard.

Posez une question que vous pouvez évaluer avant que quiconque n’écrive une ligne. « Où l’expiration de session est-elle gérée, et qu’est-ce qui l’appelle ? » est un meilleur premier mouvement que « corrige l’authentification » . Exigez des citations. Ouvrez les résultats file.ext:line. Suivez le symbole. Confirmez la dépendance que vous êtes sur le point de toucher.

Maguyva expose 11 outils MCP orientés client à travers la recherche, les symboles, l’analyse de dépendances, la récupération de fichiers, le contexte de dépôt et des workflows utilitaires déterministes. Quatre modes de récupération sont fusionnés en résultats classés ; find_symbol est un outil séparé quand vous connaissez déjà le nom. La documentation décrit le chemin le plus court : commencer gratuitement, indexer un dépôt que vous connaissez déjà, connecter le client, puis poser une question que vous pouvez vérifier.

Les instantanés sont horodatés, afin que l’agent puisse dire quelle version de l’arbre il lit. La limite honnête est le travail local non synchronisé. Si la modification n’existe que dans un arbre de travail et n’a pas été poussée, la carte hébergée ne la contient pas encore. Les fichiers d’instructions (CLAUDE.md, AGENTS.md) ont toujours leur place ici, pour les conventions et ce qu’il ne faut pas toucher. Ce ne sont pas une carte vivante. Utilisez-les pour le comportement. Utilisez Maguyva pour les faits.

Ne laissez pas l’agent ouvrir une PR avant que les citations n’aient survécu au contact avec le dépôt. Cette barrière est tout l’intérêt de cette étape.

2. PR de l’agent

Le même agent écrit maintenant le changement dans le client pour lequel vous payez déjà. Maguyva n’est ni un éditeur ni un relecteur. L’agent produit toujours le diff. Vous ouvrez toujours la pull request sur GitHub ou GitLab comme vous le faites déjà.

Ce qui devrait être différent, c’est le premier fichier. La PR devrait nommer le gestionnaire qui implémente réellement le comportement, l’appelant qui va casser, et le test qui échouera si le changement est faux. Si l’étape 1 a été sautée, l’étape 3 passera ses commentaires sur un changement atterri dans le mauvais paquet. Greptile peut quand même trouver des problèmes systémiques. Il ne devrait pas en plus avoir à se remettre d’un chemin halluciné.

Gardez la PR ciblée. Un premier fichier fondé n’est pas une licence pour réécrire le module. Le duo complémentaire fonctionne quand l’agent a fait un travail avec une carte, puis a demandé à un relecteur de faire un autre travail sur un diff délimité.

3. Revue Greptile

Greptile est déjà connecté au dépôt via l’application GitHub ou GitLab. Sur la nouvelle pull request, il analyse le changement en utilisant le graphe complet du dépôt qu’il a construit et publie des résultats sous forme de commentaires avec des corrections suggérées. Leurs propres supports situent ce passage à environ trois minutes.

Lisez les commentaires comme vous liriez un coéquipier attentif : ouvrez l’emplacement cité, décidez si le constat est réel, puis agissez. Là où Greptile propose « Fix with your Agent » , il envoie le problème — chemins de fichiers, numéros de ligne, code suggéré — à Claude Code, Codex, Conductor, Cursor ou Devin. « Fix All » envoie tous les problèmes de la revue d’un coup. Ils livrent aussi un MCP Greptile et un plugin Claude Code pour cette transmission. Maguyva ne figure pas sur cette liste de cibles nommées ; cette absence n’est pas un problème. Maguyva a déjà fait son travail à l’étape 1. L’agent de code qui a écrit la PR est celui qui devrait recevoir la charge utile de correction.

Attendez-vous à du bruit pendant les 2 à 3 premières semaines pendant que le système d’apprentissage de Greptile s’adapte aux commentaires que votre équipe laisse réellement. C’est leur calendrier déclaré, pas un défaut du duo. La revue humaine reste dans la boucle. Greptile est le premier passage automatisé, pas le bouton de fusion.

Si un commentaire de Greptile pointe vers un fichier que l’agent n’a jamais interrogé à l’étape 1, c’est un signal utile. Soit la carte a manqué un appelant, soit l’agent a sauté une citation. Corrigez le brouillon en fonction du commentaire. Ne désactivez pas le relecteur.

Comment garder ce duo honnête

Maguyva d’abord, toujours. Une revue d’une PR au mauvais fichier reste une revue du mauvais fichier.
Greptile ensuite, toujours. Un brouillon bien cité a quand même besoin d’une lecture du diff à l’échelle du système entier.
Ne demandez pas à Maguyva de publier des commentaires de PR. Il ne le fait pas.
Ne demandez pas à Greptile d’être la première couche de récupération de l’agent pendant qu’il choisit encore un chemin. Ce n’est pas le travail pour lequel leur application GitHub ou GitLab est câblée.
N’inventez pas un pipeline bash qui les « synchronise » . La PR est l’interface.
Vérifiez les deux côtés indépendamment. Indexez un dépôt que vous connaissez déjà. Posez une question que vous pouvez vérifier. Puis ouvrez une petite PR et lisez ce que Greptile commente réellement.

La boucle est ordinaire une fois qu’on la nomme. D’abord la carte. Puis la PR de l’agent. Puis la revue. Chaque produit reste du côté de la pull request où il excelle.

// map first. review second. in that order.

Donner à un agent IA le contexte d'un grand dépôt sans indexeur local

Fri, 14 Aug 2026 00:00:00 GMT

Un grand dépôt ne tient pas dans une fenêtre de contexte, et si vous avez déjà pointé un indexeur local vers un vrai monorepo, vous savez qu’il n’y tient pas non plus confortablement — la RAM explose, le premier index prend une heure, et votre agent commence encore la session suivante en devinant quels fichiers comptent.

La réponse habituelle est de faire tourner un indexeur à côté de l’éditeur, et pour un dépôt qui tient confortablement sur une seule machine, c’est une bonne réponse. Si votre monorepo s’indexe déjà rapidement dans Cursor et que c’est le seul endroit où vous avez besoin de la carte, ce texte n’a rien à ajouter — passez votre chemin.

Ce texte parle de l’autre cas — quand un agent a besoin d’une carte interrogeable d’un grand dépôt, et que vous ne voulez pas faire tourner d’indexeur local pour l’obtenir.

Quand un indexeur local est le mauvais outil

Un index local suppose que le code vit sur la machine qui l’interroge, et à l’échelle d’un vrai monorepo, cette hypothèse tend même à l’intérieur d’un seul éditeur. Le dépôt est tout simplement plus grand que ce que vous voulez garder au chaud sur un portable : vous travaillez dans un paquet pendant que le rayon d’impact se trouve trois répertoires plus loin, et un premier index à froid d’un arbre de deux millions de lignes n’est pas quelque chose que vous voulez subir deux fois — ni sur votre machine, ni sur un runner CI qui n’a jamais cloné l’arbre auparavant. Ou un coéquipier devrait pouvoir interroger la même carte que vous, sans attendre que sa propre machine traverse péniblement le même index.

Rien de tout cela n’est une raison de jeter un bon indexeur d’éditeur. C’est une raison d’avoir aussi une carte hébergée que n’importe lequel de vos agents peut interroger via MCP.

Et le problème d’échelle va plus loin que « trop de fichiers à coller » . Sur un grand arbre, la question intéressante n’est presque jamais « montre-moi ce fichier » — c’est quel fichier, quel symbole, quels appelants, quels tests. Un agent qui commence en listant src/ et en lisant les trois premiers résultats manquera allègrement le gestionnaire dans apps/api et le client généré dans packages/sdk. Ce qu’il vous faut, c’est une récupération construite depuis l’arbre entier, puis classée, puis citée.

Ce que signifie vraiment « le contexte d’un grand dépôt »

Déverser des fichiers dans le prompt n’est pas du contexte — c’est une copie plus petite et moins bonne de l’arbre. Ce dont votre agent a réellement besoin, c’est de poser des questions et d’obtenir des réponses citées en retour : où ce symbole est-il défini et qui l’appelle, qu’est-ce qui dépend du module que je m’apprête à modifier, quel fichier de test couvre ce comportement, et à quoi ressemble l’arbre maintenant, pas le trimestre dernier.

Ces réponses doivent venir d’un index construit à partir de votre dépôt plutôt que de la mémoire du modèle sur les dépôts des autres, et l’index doit vivre ailleurs que dans la fenêtre de contexte de l’agent. Pour ce problème, il devrait aussi vivre ailleurs que sur votre portable.

Une autre chose que les fichiers d’instructions ne peuvent pas faire pour vous : CLAUDE.md et AGENTS.md sont le bon endroit pour les conventions et le comportement, mais ce ne sont pas une carte vivante, classée et interrogeable d’un arbre de deux millions de lignes. Utilisez les règles pour le comportement ; utilisez l’intelligence du dépôt pour les faits.

Construire la carte dans le cloud, l’interroger depuis n’importe quel client

Maguyva est une couche de contexte de code MCP distante. Vous connectez GitHub, choisissez vos dépôts, et vous partez pendant que les pipelines cloud analysent l’arbre, construisent les symboles et les arêtes du graphe, et maintiennent une carte classée — sans indexeur local, jamais.

Quand vous poussez du code, les fichiers modifiés sont analysés de façon incrémentale, et les couches de graphe et de classement se reconstruisent selon un calendrier : quotidien sur le plan gratuit, horaire sur les plans payants. Chaque instantané est horodaté, afin que votre agent puisse dire quelle version de l’arbre il lit. La limite honnête ici est le travail local non synchronisé — une modification qui n’existe que dans votre arbre de travail, jamais poussée, n’est pas encore dans la carte hébergée.

Ensuite, vous connectez le client que vous utilisez déjà en ajoutant une clé API à sa configuration MCP. Il existe des guides de configuration pour 24 clients MCP documentés, et tout autre client compatible MCP prenant en charge la configuration standard peut aussi se connecter. Si Cursor est votre environnement, la page Cursor trace ce chemin ; le même serveur répond à Claude Code, VS Code, Windsurf, Codex CLI et les autres.

Vous ne changez pas d’éditeur. Vous donnez à votre agent une surface d’outils — 11 outils MCP à travers la recherche, les symboles, l’analyse de dépendances, la récupération de fichiers et le contexte de dépôt — avec une couverture de plus de 279 langages et technologies textuelles, ce qui compte plus qu’on ne le pense sur un monorepo qui a cessé d’être un seul langage il y a des années.

Les réponses reviennent fondées, sous forme de chemins de fichiers avec numéros de ligne. Les récupérations sémantique, structurelle, par graphe et textuelle sont fusionnées en résultats classés, de sorte qu’une question comme « qu’est-ce qui dépend de parseConfig » ne vous donne ni un déversement grep ni un seul fragment sémantique, mais la poignée d’endroits qui comptent réellement.

Un guide concret

Ne commencez pas par indexer toute l’entreprise. Voici le chemin qui fonctionne :

Choisissez un dépôt que vous connaissez déjà bien — un paquet que vous pouvez évaluer à la main vaut mieux que le plus grand arbre que vous avez.
Commencez gratuitement : 3 dépôts, 50 000 lignes indexées, les 11 outils, aucun quota de requêtes mensuel. Si votre dépôt représentatif est plus grand, la page de tarification liste les niveaux d’espace de travail (0 $, 19 $, 49 $, 149 $) par empreinte indexée — pas par nombre de sièges.
Connectez GitHub et attendez la fin du premier index. Vous ne compilez rien localement.
Connectez le client MCP — quelques lignes de configuration. Maguyva est un serveur MCP distant, donc il n’y a ni plugins, ni extensions, ni second éditeur à adopter.
Posez une question que vous pouvez vérifier. « Qu’est-ce qui dépend de parseConfig ? » ou « Où est géré l’expiration de session de connexion ? » Ouvrez ensuite les résultats file.ext:line cités et vérifiez-les contre l’arbre devant vous.
Ce n’est qu’après que les citations ont survécu à ce contact que vous laissez l’agent modifier.

Si le premier dépôt convient bien et que votre arbre est grand, augmentez l’espace de travail pour correspondre à vos lignes indexées et à la cadence de reconstruction. Humains et agents partagent le même compte d’utilisateurs — Maguyva facture par espace de travail, pas par siège — donc ajouter un troisième agent à la boucle ne vous coûte rien.

Le test d’activation est le même que celui que la documentation recommande pour tout premier lancement : indexer un dépôt que vous connaissez déjà, poser une question que vous pouvez vérifier. Un grand dépôt ne change pas le test ; il rend seulement un premier fichier erroné plus coûteux.

À surveiller une fois connecté

Gardez un œil sur trois choses. Fraîcheur : les plans payants se reconstruisent toutes les heures, les plans gratuits tous les jours, et le travail local non poussé ne sera pas dans la carte — c’est le compromis que vous acceptez. Périmètre : indexez un ensemble représentatif de dépôts, pas chaque fork archivé ; le niveau gratuit est délibérément dimensionné pour découvrir si les réponses valent la peine d’être conservées. Et vérification : une carte de grand dépôt qui ne peut pas citer chemins et numéros de ligne n’est qu’un moteur de devinette plus lent, donc faites montrer à votre agent l’endroit avant qu’il livre le correctif.

Exécutez ensuite le même test que vous feriez sur un petit dépôt. Indexez un dépôt que vous connaissez déjà. Posez une question que vous pouvez vérifier. Si la carte est réelle, votre agent cesse de partir d’un arbre froid.

// no laptop got hot building this map.

Pourquoi votre agent de code IA hallucine des chemins de fichiers

Fri, 14 Aug 2026 00:00:00 GMT

Le signe révélateur n’est pas un corps de fonction erroné. C’est une modification assurée d’un fichier qui n’existe pas, ou d’un fichier qui existe mais n’est pas celui qui implémente le comportement.

Vous avez demandé une correction d’expiration de session. L’agent a ouvert src/auth/session.ts. Ce chemin est plausible. Il est aussi faux. Le vrai gestionnaire vit dans apps/api/src/middleware/expiry.ts, renommé il y a deux refactorisations. L’agent ne vous a pas menti. Il a complété une chaîne en forme de chemin à partir de priors d’entraînement plus tout ce qui se trouvait déjà dans la fenêtre de contexte.

C’est le mode d’échec courant sur un dépôt réel. Le modèle sait écrire du code. L’erreur est de choisir le mauvais endroit où l’écrire.

Pourquoi les agents inventent des chemins

Un agent de code est un modèle de prédiction de token suivant, doté d’outils. Quand vous dites « corrige l’expiration de session » , il doit nommer un fichier avant de pouvoir lire ou corriger quoi que ce soit. S’il n’a pas déjà une carte fondée, il construit un chemin à partir de :

Conventions de nommage qu’il a vues dans d’autres dépôts. src/auth/session.ts est une forme fréquente.
Fichiers déjà présents dans la conversation, qui sont peut-être ceux que vous avez collés la semaine dernière, pas ceux qui comptent maintenant.
Listes de répertoires qu’il a exécutées par hasard, incomplètes sur un grand arbre.
Fichiers d’instructions. CLAUDE.md et AGENTS.md disent à l’agent comment se comporter. Ce ne sont pas un index vivant des symboles, des appelants ou des chemins actuels.

Aucune de ces sources n’est une carte de ce dépôt, aujourd’hui. Le modèle comble le vide comme il comble tout vide : avec une continuation hautement probable. Cette continuation ressemble souvent à un vrai chemin. Parfois le fichier existe et se trouve à côté du bon. Parfois il existait sur une branche fusionnée le mois dernier. Parfois il n’a jamais existé.

Grep ne vous sauve pas ici si l’agent ne recherche jamais la bonne chaîne. L’agent a deviné un chemin, puis a lu ce que ce chemin retournait, puis l’a modifié. La première étape erronée était le chemin, pas le correctif.

Lire des fichiers n’est pas non plus la même chose que trouver les bons. Claude Code, Cursor, Codex et des outils similaires peuvent ouvrir tout ce vers quoi vous les pointez. La question est de savoir s’ils trouvent de façon fiable les bons fichiers, les symboles importants, les dépendances, les tests, et le rayon d’impact avant de modifier. L’accès aux fichiers sans carte commence toujours par une supposition.

La modification du mauvais fichier est un problème de récupération

Traitez le chemin inventé comme un échec de récupération, pas comme un défaut de caractère.

Si l’agent devait renvoyer path/file.ext:line avant d’être autorisé à modifier, deux choses se produiraient. D’abord, vous pourriez ouvrir la citation et rejeter le travail en dix secondes. Ensuite, l’agent devrait interroger quelque chose qui connaît réellement l’arbre.

C’est le travail d’une couche de contexte de code. La recherche sémantique seule ne suffit pas. Un fragment qui « sonne comme l’expiration de session » peut quand même atterrir dans un paquet obsolète. Vous avez aussi besoin de texte exact quand vous connaissez la chaîne, de recherche de symboles quand vous connaissez le nom, de recherche structurelle quand vous connaissez la forme, et d’un graphe de dépendances quand vous avez besoin des appelants et du rayon d’impact.

Maguyva est cette couche pour les agents de code compatibles MCP. Ce n’est pas un éditeur. Claude Code, Cursor, Codex CLI, VS Code, Windsurf et les autres clients MCP restent où ils sont. L’agent interroge une carte classée avant de toucher une ligne.

L’affirmation est délibérément modeste : moins de modifications hallucinées. Maguyva ne retire pas au modèle sa capacité à deviner. Il change la première étape par défaut, qui passe d’ « inventer un chemin plausible » à « demander des emplacements classés et cités » .

À quoi ressemble une réponse fondée

Une réponse utile à « où l’expiration de session est-elle gérée » n’est pas un paragraphe. C’est une courte liste d’emplacements :

apps/api/src/middleware/expiry.ts:48 - le gestionnaire
apps/web/src/lib/auth-client.ts:112 - l’appelant
apps/api/tests/expiry.test.ts:20 - le test qui échouera si le changement est faux

Vous pouvez ouvrir ces lignes. Si elles sont fausses, vous vous arrêtez. Si elles sont justes, l’agent peut modifier. La vérification est le but, pas un slogan.

Maguyva expose 11 outils MCP orientés client à travers la recherche, les symboles, l’analyse de dépendances, la récupération de fichiers, le contexte de dépôt et des workflows utilitaires déterministes. Quatre modes de récupération (sémantique, structurel, graphe/dépendance et texte) sont fusionnés en résultats classés ; la recherche de symboles est un outil MCP séparé (find_symbol). Les réponses fondées reviennent avec des chemins de fichiers et des numéros de ligne, afin que vous puissiez les évaluer contre l’arbre devant vous.

La documentation décrit le chemin le plus court : commencer gratuitement, indexer un dépôt que vous connaissez déjà, connecter le client, puis poser une question que vous pouvez vérifier.

Une boucle qui change la première modification

Vous n’avez pas besoin d’une nouvelle religion de workflow. Vous avez besoin d’une étape supplémentaire avant la première écriture.

Posez une question que vous pouvez déjà évaluer. « Quel code gère la connexion et l’expiration de session ? » vaut mieux que « corrige l’authentification » .
Exigez des citations. Chemin de fichier et numéro de ligne, pas un résumé du « module d’authentification » .
Ouvrez les fichiers cités. Suivez le symbole. Confirmez la dépendance que vous êtes sur le point de toucher.
Ce n’est qu’ensuite que vous laissez l’agent corriger.

Si l’étape 2 ne renvoie rien d’utile, l’agent n’a pas le droit d’improviser un chemin. Il recherche à nouveau, ou vous l’orientez. Cette seule barrière est ce qui produit moins de modifications hallucinées. Le modèle est le même modèle. La carte est ce qui a changé.

Les fichiers d’instructions comptent toujours. Gardez-les. Utilisez-les pour les conventions, les règles de revue et ce qu’il ne faut pas toucher. Ne leur demandez pas d’être l’index. Un CLAUDE.md qui liste trois répertoires importants sera obsolète la semaine suivant une scission de paquet. Une carte interrogeable se met à jour quand le dépôt se met à jour.

Un échec apparenté est le fichier presque-bon : l’agent ouvre auth.ts alors que le comportement vit dans auth-client.ts, ou modifie un fichier généré au lieu de la source, ou modifie la copie dans packages/legacy parce que le nom correspondait. Les citations ne rendent pas ces erreurs impossibles. Elles les rendent visibles avant que le diff n’atterrisse.

Ce qu’une carte ne résoudra pas pour vous

Soyez lucide sur ce que vous obtenez. Une carte fondée ne rendra pas chaque modification correcte — votre agent peut toujours écrire un mauvais correctif dans exactement le bon fichier. Si votre base de code s’appuie sur le dispatch dynamique, la réflexion ou le monkey-patching, certaines recherches de symboles reviendront plus maigres que vous ne le souhaiteriez, parce que c’est ce que l’indirection à l’exécution fait à tout index statique. Et si vous espérez un pourcentage — « chemins hallucinés réduits de X % » — vous ne le trouverez pas ici, parce que personne ne peut honnêtement mesurer ce chiffre pour votre dépôt, sauf vous.

Ce que vous pouvez attendre est plus étroit et plus utile : l’agent cesse d’ouvrir ses modifications avec un chemin deviné. Cette première étape est ancrée dans une vraie carte, et c’est de là que viennent moins de modifications hallucinées. Tout ce qui suit la citation — lire le diff, juger le correctif — reste votre travail, comme cela l’a toujours été.

Le test ne vous coûte presque rien : indexez un dépôt que vous connaissez déjà et posez une question que vous pouvez vérifier. Commencez par un chemin qui vous a déjà brûlé. Si les citations sont fausses, vous le verrez immédiatement. Si elles sont justes, la prochaine modification de votre agent a un meilleur endroit où atterrir.

// it doesn't know the file. it knows how to find it.

Pourquoi nous avons fait évoluer la recherche de code vers voyage-4-large

Tue, 09 Jun 2026 00:00:00 GMT

Les chiffres de benchmark de cet article reflètent les classements RTEB au moment de la publication (juin 2026). Les classements évoluent ; considérez-les comme un instantané, pas comme un fait permanent.

Une recherche sémantique ne vaut que ce que valent les embeddings qui la sous-tendent.

Quand un agent demande à Maguyva « où gérons-nous les nouvelles tentatives », il ne cherche pas avec grep le mot « retry ». Il demande le sens — la boucle de backoff, le disjoncteur (circuit breaker), la chose qui enveloppe un appel instable. Cette question trouve sa réponse grâce à un modèle vectoriel qui transforme le code en un point dans l’espace et trouve ses voisins. Choisissez un meilleur modèle, et chaque requête sémantique du produit devient discrètement plus fine.

Nous avons donc changé le nôtre. Depuis juin 2026, les embeddings de code de Maguyva tournent sur voyage-4-large, en remplacement de voyage-code-3.

Le benchmark

Nous n’avons pas pris cette décision à l’instinct. Le Retrieval Embedding Benchmark (RTEB) public classe les modèles d’embedding sur de vraies tâches de récupération, et sur son classement Code, voyage-4-large se trouve 1er au classement global (90,86) — devant gemini-embedding-2-preview (90,26) et, notamment, devant le modèle que nous utilisions déjà, voyage-code-3 (89,73, 3e place).

C’est un petit écart en valeur absolue. Mais c’est un écart dans la bonne direction, sur un benchmark public, sur exactement la tâche qui nous intéresse : récupérer du code par le sens.

Le compromis que nous acceptons : la quantification binaire

Voici la partie que la plupart des articles « nous avons mis à niveau notre modèle » passent sous silence.

Maguyva ne stocke pas de vecteurs en pleine précision. Nous stockons des embeddings quantifiés en binaire : chaque vecteur à 2048 dimensions se réduit à une signature de 2048 bits — 256 octets par vecteur. Ces signatures sont recherchées par distance de Hamming, indexées et partitionnées par tenant.

C’est un compromis délibéré. La quantification binaire sacrifie un peu de précision de récupération en échange d’un stockage nettement plus petit et d’un calcul de distance rapide et peu coûteux, sans base de données vectorielle séparée à exploiter. Pour un produit qui indexe des dépôts entiers par espace de travail, cette économie compte plus que grappiller le dernier centième d’un point de benchmark.

voyage-4-large s’inscrit dans cette conception sans forcer une migration de la couche de stockage : il produit une sortie à 2048 dimensions, soit le même nombre de dimensions que voyage-code-3, donc nos colonnes bit(2048) et notre chemin de recherche par distance de Hamming n’ont pas changé. Le modèle s’est amélioré ; le schéma est resté en place.

Le code n’était qu’un début

Maguyva est un outil d’intelligence du code. Mais nous sommes aussi notre propre client zéro, et nous le pointons vers autre chose : le markdown qui vit dans nos dépôts aux côtés du code. Fiches de décision architecturale, runbooks, contrats, documents financiers et de politique — tout cela versionné dans Git, tout cela derrière le même serveur MCP, un index sémantique sur les documents, pas seulement sur la source.

C’est exactement pourquoi l’étendue de voyage-4-large compte. Sur la même famille de classements RTEB, il est 1er en finance, 1er en santé, et 1er en récupération de texte globale — devant Gemini Embedding de Google, Embed v4 de Cohere, et text-embedding-3-large d’OpenAI. (Voyage est co-créateur de RTEB, nous le lisons donc comme un signal public fort plutôt que comme un arbitre parfaitement neutre — mais il est comparé tête-à-tête à tous les grands modèles commerciaux, sur des jeux de données privés tenus en réserve.) Le même index qui trouve la bonne fonction pour un agent trouve la bonne clause dans un contrat, ou la bonne ligne dans une politique — et sur ces domaines, voyage-4-large n’est pas un compromis, c’est le leader.

Pourquoi nous payons pour des embeddings premium

Il existe une façon moins chère de faire de la recherche, et une bonne partie en est gratuite. La recherche lexicale — BM25 et ses cousins — fait correspondre des mots-clés, tourne localement, et ne coûte rien. Des modèles d’embedding open source comme BGE, Nomic et embeddinggemma offrent une récupération sémantique réellement correcte, et on peut les auto-héberger pour le prix d’un GPU. Maguyva utilise aussi le côté gratuit : chaque requête fusionne recherche textuelle, AST, graphe et sémantique. Ce sur quoi nous ne lésinons pas, c’est la couche sémantique.

Nous payons au token pour des embeddings premium — voyage-4-large — plutôt que d’auto-héberger un modèle gratuit, pour deux raisons. Premièrement, la recherche par mots-clés seule ne peut pas répondre à « où gérons-nous les nouvelles tentatives » quand le code dit backoff et circuit breaker sans jamais dire le mot « retry » — le sens est tout l’intérêt de l’embedding, et sur les domaines que nous servons, les modèles ouverts restent en retrait par rapport aux modèles premium : quelques points de retard sur le texte général, et davantage sur des niches comme le code, les contrats et la finance. Deuxièmement, d’après notre expérience, la qualité de la récupération façonne la réponse finale plus que ne le fait le modèle en bout de chaîne — un agent puissant à qui l’on donne le mauvais contexte répond quand même mal, et il ne voit jamais le document qu’on ne lui a jamais fourni.

Les embeddings premium représentent donc une facture au token qui grandit avec chaque dépôt et chaque document que nous indexons — et nous la payons délibérément. Pour le résultat obtenu par nos utilisateurs, la bonne fonction ou la bonne clause, nous pensons que ce compromis en vaut la peine.

La partie honnête

La documentation de Voyage elle-même désigne toujours voyage-code-3 comme le modèle optimisé pour le code. Alors pourquoi changer ?

Parce que nous lisons le benchmark public, pas seulement le tableau de modèles du fournisseur, et que le benchmark place voyage-4-large en tête pour la récupération de code. C’était un pari tourné vers l’avenir : prendre le modèle plus récent, généralement plus puissant, et le valider face à un classement public sur les tâches qui comptent. Nous sommes à l’aise avec ce pari, car les résultats couvrent de nombreux domaines — voyage-4-large ne gagne pas seulement sur le code, il mène aussi en finance, en santé et en récupération globale.

Les fondations discrètes

Chaque outil que nous exposons — recherche sémantique, collecte de contexte de tâche, questions-réponses ancrées dans le code — se ramène en dernière analyse à la récupération. Quand le moteur de récupération s’améliore, l’agent en bout de chaîne obtient de meilleures preuves, fait moins de faux pas, et ancre ses réponses dans le bon code — ou la bonne clause, ou la bonne politique. Un modèle d’embedding plus fin n’est pas une fonctionnalité tape-à-l’œil. Ce sont les fondations de tout le reste, et nous venons de les renforcer. Vous ne le remarquerez pas. C’est bien le but.

Auto-amélioration récursive de la prise en charge des langages : affiner l'intelligence du code sur environ 280 langages

Tue, 26 May 2026 00:00:00 GMT

Les chiffres de cet article reflètent le système au moment de la publication (mai 2026). Consultez notre page équipe pour les chiffres actuels.

Maguyva extrait symboles, références et graphe de dépendances à partir du code source dans environ 280 langages. Chaque langage repose sur un handler tree-sitter sur mesure — requêtes, heuristiques, cas limites — et chaque handler peut se tromper subtilement, à sa manière propre. Un appel de méthode émis comme une lecture. Une fonction attribuée à la mauvaise portée englobante. Une relation qui, tout simplement, n’existe pas.

On ne peut pas auditer cela à la main. Aucune équipe ne peut lire la sortie d’extraction sur 280 grammaires et repérer les mauvaises arêtes. La question intéressante n’est donc pas « notre extraction est-elle correcte » — c’est « comment découvrir qu’elle est fausse, à cette échelle, sans un humain dans chaque boucle ». Notre réponse est l’auto-amélioration récursive de la prise en charge des langages : une boucle de qualité pilotée par des agents de langage, un LLM agissant comme juge, et une règle que nous réapprenons sans cesse : le vert n’est pas synonyme de correct.

Le vert n’est pas correct

Chaque langage dispose d’une suite de fixtures, et un contrôle préalable à la mise en production l’évalue sur cinq dimensions — exactitude, intégrité structurelle, exhaustivité, qualité et performance. Un langage passe au VERT seulement quand, sur ses fixtures, la précision ≥ 0,95, le rappel ≥ 0,99 et le F1 ≥ 0,97, avec au moins 20 arêtes attendues pour la confiance statistique. En dessous, c’est JAUNE ou ROUGE, et cela ne part pas en production.

Ce contrôle est nécessaire, mais pas suffisant. Les fixtures valident par rapport à des fixtures que nous avons écrites. Elles encodent les cas auxquels nous avons déjà pensé. Un handler peut être irréprochable sur ses fixtures et malgré tout massacrer un schéma qui n’apparaît que dans du code réel — un idiome de macro, une méthode soumise à des contraintes sur ses types génériques, une fonctionnalité de langage pour laquelle personne n’a écrit de fixture. VERT signifie que les fixtures passent. Cela ne signifie pas qu’un dépôt réel s’extrait proprement. La boucle doit donc laisser les fixtures de côté et regarder dans la nature.

La boucle interne : contrôle ponctuel, jugement, correction, preuve

La boucle centrale fait tourner un langage à la fois :

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  1. corpus run ── clone real-world repos, extract relationships   │
        │                                                          │
        ▼                                                          │
  2. spot-check 100 edges (seed 42, then seed 123 to cross-check)  │
        │                                                          │
        ▼                                                          │
  3. LLM judge classifies every sampled edge:                      │
        CORRECT · FALSE_POSITIVE · TYPE_ERROR ·                    │
        SCOPE_ERROR · METADATA_ERROR                               │
        │                                                          │
        ▼                                                          │
  4. fix ONE thing — handler .py, .scm query, or config           │
        │                                                          │
        ▼                                                          │
  5. re-validate — F1 + re-classify + manifest diff (no regressions)│
        │                                                          │
   better? ──no──► revert, try a different fix ────────────────────┤
        │ yes                                                       │
        ▼                                                           │
  6. promote the fix into fixtures (a permanent regression guard) ──┘

Quelques principes permettent à cette boucle d’avancer plutôt que de s’agiter en vain.

Le juge, c’est l’agent, pas un appel d’API. Quand nous disons « LLM en tant que juge », nous voulons dire que l’agent de langage lit lui-même chaque arête échantillonnée face à la source réelle, et la classe selon une grille fixe à cinq catégories : cette arête est-elle correcte, un faux positif, la bonne relation avec le mauvais type, rattachée à la mauvaise portée, ou porteuse de métadonnées erronées ? Cette grille, c’est tout l’enjeu — un « taux d’erreur de 23 % » ne veut rien dire tant qu’on ne sait pas s’il s’agit de vrais défauts ou d’un mauvais comptage du juge.

Corriger une chose, puis le prouver. Chaque itération modifie exactement un actif éditable, puis relance les tests avec le même dispositif de validation et ne conserve le changement que si le F1 s’améliore et que la reclassification paraît meilleure. Sinon, elle est annulée. Pas de lot de modifications spéculatives, pas de « ça devrait aller mieux ». Un changement gagne sa place ou il disparaît. Et quand une correction tient, elle est promue dans la suite de fixtures — pour que le bug qu’elle a corrigé ne puisse jamais revenir en silence. C’est cette étape de promotion qui rend la boucle récursive plutôt que simplement répétitive : chaque passage renforce l’oracle qui servira de référence à la validation du passage suivant.

La leçon que nous réapprenons sans cesse : les métriques surestiment

Voici le piège, et nous y sommes tombés tête baissée. Les métriques secondaires de corpus — à quelle fréquence une cible extraite n’a aucun symbole résolvable, combien de symboles paraissent « orphelins », et ainsi de suite — surestiment massivement les problèmes. Ce sont surtout des artefacts de paradigme, pas des bugs.

L’exemple le plus net : llvm a un jour affiché un taux de « source sans symbole » de 73 % et a été catalogué comme catastrophique. Nous avons creusé. La précision réelle était de 98,5 %. Les « symboles manquants » étaient presque tous des références externes légitimes — des appels vers la bibliothèque standard, vers des frameworks, vers du code qui vit hors du dépôt. La métrique mesurait une propriété du langage, pas un défaut du handler. Des langages comme Zig, COBOL et Odin affichent des taux « orphelins » de 65 à 70 % et sont pourtant entièrement corrects ; COBOL n’avait aucune vraie erreur.

Si nous avions laissé ces chiffres piloter le travail, nous aurions passé des semaines à « corriger » des handlers déjà justes, en ignorant les langages porteurs de vrais bugs discrets. La conclusion est brutale : les métriques agrégées sont, au mieux, un signal de tri grossier. Le vrai signal de qualité est le contrôle ponctuel avec classification des arêtes — regarder les arêtes réelles dans des dépôts réels et les juger une par une. Les données plutôt que l’intuition, mais seulement une fois qu’on sait quelles données disent la vérité.

La boucle externe : une flotte, pas un marathon

Un langage à la fois prendrait une éternité sur 280 d’entre eux, donc la boucle interne est enveloppée dans une boucle externe qui en fait tourner beaucoup en parallèle.

   pick a wave of near-GREEN / high-error languages
        │
        ▼
   fan out 10–15 agents, each ISOLATED in its own git worktree,
   each grinding ONE language, committing to its own branch
        │
        ▼
   orchestrator integrates serially: file-scoped apply, then
   `manifest diff` — any cross-language regression blocks the batch
        │
        ▼
   gated push (reviewed and confirmed) ──► rotate to the next wave

Chaque agent travaille dans un worktree jetable, pour qu’ils ne puissent pas se marcher dessus. L’orchestrateur intègre leurs corrections une par une, chacune derrière un contrôle de régression sur l’ensemble du manifeste : un changement qui aide son propre langage mais casse discrètement trois autres ne passe pas. L’intégration est verrouillée et confirmée avant que quoi que ce soit ne soit poussé — le contrôle de régression décide de ce qui est sûr, un humain décide toujours de ce qui part en production. Puis le pool bascule vers le lot de langages suivant, et tout recommence.

Ce qui reste imparfait

Le juge peut se tromper, et l’erreur a une direction : un agent qui tourne avec trop peu de contexte surestime les problèmes. Sur un lot, huit langages ont été signalés avec un taux d’erreur de 5 à 20 % ; à l’examen, un seul était un vrai bug propre au langage — le reste venait d’erreurs du juge par méconnaissance de la sémantique propre au langage (une seule ligne source émettant légitimement plusieurs arêtes, des liaisons de paramètres modélisées comme des affectations, des langages à référence par identifiant). C’est pourquoi nous échantillonnons avec deux graines aléatoires et procédons à des vérifications croisées, et pourquoi un désaccord entre le juge et les fixtures est traité comme le signal le plus intéressant, pas comme un verdict définitif — parfois, c’est la fixture qui a tort.

Nous sommes aussi honnêtes sur l’objectif. Le but est zéro erreur réelle, point final — mais « zéro » est une direction vers laquelle nous nous acharnons, langage par langage, pas une case que l’on coche. Il y a toujours un autre dépôt avec un autre idiome.

La justesse se mérite, elle ne se décrète pas

Tout ce que Maguyva fait pour un agent — trouver un symbole, tracer une dépendance, répondre à une question avec du code cité — repose sur la justesse de l’extraction sous-jacente. Sur 280 langages, cette justesse ne peut pas être affirmée ; elle doit être méritée en continu face au code réel. La boucle est notre façon de la mériter : un cycle autonome de contrôle ponctuel et de correction qui se méfie de ses propres métriques, prouve chaque changement, et transforme chaque correction en garde-fou contre la prochaine régression. Ce n’est pas glamour. C’est le travail qui nous permet de dire « nous prenons en charge votre langage » et de le penser vraiment. Le vert est facile. La justesse se mérite.

Recherche par fusion multimodale : choisir le bon moteur de récupération pour chaque requête

Wed, 15 Apr 2026 00:00:00 GMT

Note sur la conception historique : cet article d’avril 2026 décrit la conception du routage à cette époque, pas le comportement par défaut actuel. La correction de septembre ci-dessous porte uniquement sur une affirmation de mesure. Pour le routage actuel, les préréglages et les commandes explicites des modalités, voir Comment ça marche.

Une requête de recherche n’est pas une chose unique.

« où est défini parseConfig » veut un symbole exact — un emplacement précis, vite. « comment fonctionne l’authentification » veut du sens — l’ensemble du code apparenté qui explique un concept. « qu’est-ce qui casse si je modifie cette fonction » veut le graphe de dépendances. « trouver la chaîne ECONNREFUSED » veut une correspondance littérale, rien de plus subtil.

Grep excelle pour les correspondances littérales et se révèle utile pour certaines chasses aux références, mais ce n’est pas un graphe de dépendances et il ne comprend pas le sens. Les embeddings couvrent le versant sémantique, mais ce sont le mauvais outil pour les chaînes exactes et l’analyse d’impact. La plupart des outils de recherche de code choisissent un seul moteur et font vivre chaque requête avec ce choix. Maguyva ne choisit pas. Il détermine quel type de question vous avez posée, puis mélange quatre moteurs de récupération dans la proportion que cette question mérite.

Quatre modalités

Sous le capot, il existe quatre façons indépendantes de trouver du code :

sémantique — recherche vectorielle sur des embeddings binaires Voyage ; trouve le code par le sens.
textuelle — correspondance de trigrammes ; trouve les littéraux, les chaînes d’erreur, les identifiants exacts.
structurelle — requêtes AST ; trouve les définitions, les signatures et les constructions du langage.
par graphe — le graphe de dépendances ; trouve les appelants, les appelés et le rayon d’impact.

Chacune excelle sur une classe de question différente. L’astuce consiste à décider dans quelle mesure faire confiance à chacune pour la requête que l’on a sous les yeux.

Classification d’intention

Avant tout lancement de récupération, un classificateur léger trie la requête dans l’une de six intentions, avec un score de confiance. Il est délibérément peu coûteux — des heuristiques ordonnées, la première correspondance l’emporte — car il s’exécute sur le chemin critique et n’ajoute qu’une milliseconde ou deux :

commence par def , class , func , import … → find_definition (confiance 0,95)
« who calls » (qui appelle), « usages of » (usages de), « references to » (références à) → find_references (0,90)
« impact », « blast radius » (rayon d’impact), « what depends on » (qu’est-ce qui dépend de) → impact_analysis (0,90)
une chaîne entre guillemets "string" ou un jeton d’erreur comme traceback → exact_match (0,85–0,90)
un identifiant CamelCase ou snake_case → find_definition (0,60–0,80)
« how » (comment), « why » (pourquoi), « explain » (expliquer), « architecture » → understand_code (0,75)
rien ne correspond → understand_code, faible confiance (0,40)

Chaque intention porte un profil de pondération réparti sur les quatre modalités. Voici les chiffres réels :

Intention	sémantique	textuelle	structurelle (AST)	graphe
find_definition	0,2	0,1	0,6	0,1
find_references	0,1	0,2	0,2	0,5
understand_code	0,5	0,2	0,2	0,1
find_similar	0,4	0,3	0,2	0,1
impact_analysis	0,1	0,1	0,1	0,7
exact_match	0,0	0,9	0,1	0,0

Ainsi, « où est défini parseConfig » s’appuie fortement sur l’AST (0,6). « comment fonctionne l’authentification » s’appuie sur les vecteurs sémantiques (0,5). « qu’est-ce qui dépend de ceci » est presque entièrement du graphe (0,7). « trouver ECONNREFUSED » est presque entièrement du trigramme (0,9), le modèle d’embedding étant entièrement désactivé — parce que la similarité sémantique est précisément le mauvais outil pour une chaîne exacte.

Le chemin rapide, et le chemin fusionné

Quand le classificateur est confiant — score ≥ 0,85 — et que la requête est ordinaire, Maguyva saute entièrement la fusion et route directement vers l’unique modalité dominante. « où est défini X » n’a pas besoin de quatre moteurs de récupération ; il lui faut l’index AST, tout de suite. Ce chemin direct est renvoyé sous la mention fusion_strategy: "direct".

Tout ce qui est ambigu passe par la fusion. Les quatre modalités (ou trois, sur le préréglage par défaut) s’exécutent en parallèle, chacune renvoyant sa propre liste classée, et nous les combinons.

Reciprocal Rank Fusion pondérée

Fusionner des moteurs de récupération hétérogènes est plus difficile qu’il n’y paraît : une similarité cosinus de 0,82, un score de trigramme de 137 et une centralité de graphe de 0,004 ne sont pas sur la même échelle, donc on ne peut pas simplement les additionner. La Reciprocal Rank Fusion contourne le problème en jetant les scores bruts et en ne conservant que le rang attribué par chaque moteur. La contribution d’un résultat pour une modalité est :

contribution = weight × 1 / (k + rank + 1)

où rank est sa position dans la liste de cette modalité et k est une constante de lissage. Les contributions sont sommées entre modalités pour tout résultat trouvé par plus d’un moteur — l’accord entre moteurs de récupération remonte naturellement vers le haut. Nous utilisons k = 40 sur le préréglage par défaut et 60 sur thorough (quick tourne uniquement en sémantique, donc la fusion n’y intervient jamais). Les travaux originaux sur la RRF ont retenu k = 60 pour la récupération généraliste ; notre valeur par défaut est légèrement plus tranchante, ce qui donne un peu plus de poids à l’accord entre modalités sur les résultats les mieux classés — et nous ne recommandons pas de la régler manuellement.

En plus de cela, les résultats portent un bonus d’importance de graphe. Un nœud central — une fonction sur laquelle s’appuie toute la base de code — devrait devancer un nœud feuille peu connu même à pertinence textuelle égale, donc nous multiplions chaque contribution par :

boost = min(1 + 0.3 × ln(1 + centrality), 1.5)

La centralité provient des métriques PageRank / degré précalculées du pipeline, et le bonus est plafonné à 1,5× pour qu’une fonction populaire ne puisse pas complètement enterrer une fonction obscure plus pertinente. Enfin, nous rétrogradons les résultats issus des chemins vendor, build et archive, et nous dédupliquons pour ne garder que le meilleur segment par fichier.

Ce qui reste imparfait

Le classificateur d’intention est un ensemble d’expressions régulières, pas un modèle entraîné. Il traite les formes courantes de requêtes par des heuristiques, et une requête ambiguë se rabat sur understand_code et un mélange à dominante sémantique. Une version antérieure de cet article présentait comme obtenue une baisse du taux de requêtes sans résultat d’environ 15 % à moins de 5 %. La proposition de décembre 2025 indiquait en réalité une valeur initiale estimée et un objectif ; aucun jeu de requêtes ni relevé de mesure à l’appui n’est fourni. Nous retirons cette affirmation d’amélioration obtenue ; voir les preuves sources et la correction. Nous n’avons pas remplacé le classificateur par un modèle entraîné parce que la version économique est rapide et suffisante pour son rôle de routage prévu, et parce qu’un classificateur erroné mais sûr de lui est pire qu’un repli honnête. Les poids sont des hypothèses initiales choisies à la main, pas des valeurs apprises à partir de données de clics que nous ne collectons pas.

Poser la question, pas choisir l’outil

Un agent ne devrait pas avoir à savoir s’il faut recourir à grep, aux embeddings ou au graphe d’appels — il devrait poser sa question en termes simples et obtenir la bonne réponse. La fusion multimodale est ce qui permet à find_symbol, à la recherche sémantique et à l’analyse de dépendances d’être accessibles via une seule interface de requête : le système lit la forme de la question et assemble discrètement le bon moteur de récupération pour elle. Le modèle qui note les embeddings compte, mais savoir quand ne pas les utiliser compte tout autant. Choisir le bon outil pour chaque requête est une forme de qualité à part entière, et c’est une responsabilité que nous préférons assumer plutôt que de la reporter sur l’appelant.

// you bring the question. it brings the tools.

Observabilité des agents : hooks, Alloy et Grafana

Tue, 24 Mar 2026 00:00:00 GMT

Les systèmes d’agents échouent de façons étranges.

Parfois, c’est le modèle qui pose problème. Parfois, c’est l’outil. Parfois votre serveur MCP fonctionne très bien, mais l’agent a choisi le mauvais spécialiste, ou a passé la moitié de la session à faire du travail shell que vous n’attendiez pas, ou a silencieusement brûlé du budget dans une boucle qui paraissait productive de l’extérieur.

Si vous ne pouvez pas voir la différence, vous n’opérez pas vraiment un système d’agents. Vous devinez.

Nous avons donc construit une pile d’observabilité pour notre propre flux de travail : Claude Code, Codex, les événements de hooks Claude, les événements de notification Codex, OpenTelemetry natif, Grafana Alloy, et Grafana Cloud de l’autre côté.

La partie intéressante n’est pas « nous avons créé un tableau de bord ». La partie intéressante est que nous avons dû scinder la télémétrie en deux flux distincts, parce qu’aucune source unique ne nous donnait la vue d’ensemble.

Le problème : la télémétrie des agents est fragmentée

Les agents de codage modernes émettent déjà une certaine télémétrie. C’est utile, mais insuffisant.

OTEL natif répond bien à des questions comme :

Combien de requêtes avons-nous effectuées ?
Combien a coûté une session ?
Où se trouvent les spans et les traces ?
La latence a-t-elle connu un pic ?

Il répond beaucoup moins bien à des questions comme :

Sur quel serveur MCP l’agent s’est-il appuyé ?
Cet échec s’est-il produit dans Bash, un outil de fichiers intégré, ou un appel MCP ?
Quelle compétence s’est réellement activée ?
Quel type de sous-agent a été dépêché ?
La session accomplissait-elle un travail utile, ou se débattait-elle simplement ?

Cette seconde catégorie de questions relève davantage des hooks que des traces.

Mais l’inverse est vrai aussi : certaines des questions de performance les plus importantes relèvent davantage des traces que des hooks.

Si vous voulez savoir où la latence s’est réellement accumulée, quels spans étaient lents, ou si la session a passé du temps dans des appels de modèle plutôt que dans l’exécution d’outils, vous avez besoin de données de trace autant que d’événements sémantiques.

L’architecture à laquelle nous avons abouti

Nous faisons tourner deux chemins de télémétrie en parallèle.

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

Cette scission est délibérée.

Elle est aussi asymétrique. Claude Code nous offre une interface de hooks de cycle de vie beaucoup plus riche. Codex nous offre de l’OTEL natif plus une interface de notification, donc nous normalisons des événements de fin de tour plus légers vers le même schéma de log, plutôt que de prétendre que les deux runtimes exposent les mêmes contrôles.

L’OTEL natif nous donne le flux de référence : logs et traces issus du runtime lui-même, plus des métriques là où le runtime les émet réellement.

Les événements de hooks et de notification nous donnent la couche sémantique : des éléments comme PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated, et les métadonnées classifiées qui nous intéressent réellement lors du débogage du comportement des agents. Claude Code apporte ici le flux d’événements le plus riche. Codex apporte un flux normalisé plus léger, mais tout de même utile.

Pourquoi les hooks existent tout court

Notre pipeline de hooks enrichit les événements avant qu’ils n’atteignent Loki.

Au lieu de simplement dire « un outil s’est exécuté », nous classons l’événement dans des champs comme :

tool_type : builtin, mcp, skill, agent, bash
mcp_server : quel backend MCP a traité l’appel
bash_cli : la famille de commande shell
subagent_type : quel type de spécialiste a été dépêché
agent_tool : si la source était Claude Code ou Codex

Cela signifie que nous pouvons poser des questions qui comptent sur le plan opérationnel :

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

Ce ne sont pas des champs de façade. Ils font toute la différence entre « l’agent semblait lent » et « l’agent a passé les dix dernières minutes dans des opérations git riches en commandes shell, avec un taux d’échec d’outils élevé ».

Un détail d’implémentation qui paraît plus étrange qu’il ne l’est vraiment : le flux Loki partagé utilise toujours service_name="claude-code-hooks" comme label, même quand l’événement provient de Codex. La véritable scission entre les runtimes se fait sur agent_tool.

Pourquoi Alloy se trouve au milieu

Dans ce dispositif, Grafana Alloy n’est pas un simple relais. C’est le point d’application des règles.

Nous dirigeons le flux OTEL natif de Claude Code et Codex vers un proxy Alloy local sur localhost:4318, puis laissons Alloy nettoyer la charge utile avant de la transmettre à Grafana Cloud.

Cela compte, car la télémétrie brute des agents regorge de champs à forte cardinalité, utiles pour l’analyse mais désastreux comme labels indexés :

session_id
prompt_id
les comptages de tokens
les durées
les blobs de paramètres d’outils

Si vous indexez tout, vous obtenez une explosion de labels et une mauvaise journée.

Alloy fait donc trois choses pour nous :

Il maintient indexé un tout petit ensemble de labels à faible cardinalité.
Il déplace les champs bruyants mais utiles vers des métadonnées structurées.
Il élimine purement et simplement le bruit pur.

L’idée importante est simple : observer davantage, indexer moins.

Pourquoi le flux de hooks contourne Alloy

Le flux de hooks est déjà façonné pour Loki.

Au moment où send_event.py pousse un événement, nous avons déjà décidé quels champs méritent un traitement en label et lesquels appartiennent au corps JSON structuré. Ce flux part directement vers la passerelle OTLP de Grafana Cloud, sans repasser par Alloy.

Le système présente donc une répartition claire des tâches :

Alloy dompte le flux OTEL natif brut.
L’enrichissement par hooks rend les événements sémantiques interrogeables.

Cela garde l’architecture plus simple que si l’on tentait de tout faire passer par un seul chemin.

Ce que montre réellement le tableau de bord

La capture d’écran ci-dessous provient de l’un des tableaux de bord d’observabilité qui sous-tendent notre flux de travail d’agents. Ce n’est pas un benchmark, et les chiffres ne sont qu’un instantané à un moment donné. Ce qui compte, c’est la forme des données : flux d’activité, appels d’outils, échecs, prompts, et répartitions par agent, outils intégrés, usage MCP, commandes shell et compétences.

Ce qui est utile, c’est que ce tableau de bord vit sur la même pile Grafana que le reste de la télémétrie des agents. Nous pouvons filtrer par agent source et famille d’outils, et regarder à travers les runtimes sans inventer une histoire d’observabilité différente pour chaque système.

L'un des tableaux de bord en direct qui sous-tendent notre flux de travail d'agents. Cette capture d'écran n'est qu'une tranche d'une pile Grafana partagée qui reçoit aussi la télémétrie de nos autres runtimes et systèmes d'agents. Cliquez sur l'image pour la version en pleine résolution.

Pourquoi les traces comptent plus qu’il n’y paraît au premier abord

Les logs nous disent quelle catégorie de travail a eu lieu. Les traces nous disent comment ce travail s’est déroulé dans le temps.

Cette distinction compte dans les systèmes d’agents, parce que « lent » est un terme trop grossier pour être utile.

Une trace peut nous dire si la douleur venait :

de la latence du modèle
du temps d’exécution des outils
de tentatives répétées
d’une interaction MCP particulièrement coûteuse
d’une longue traîne de petites opérations qui paraissaient inoffensives isolément

En pratique, nous utilisons ensemble le flux de hooks et les traces Tempo.

Les logs de hooks répondent : quel genre de chose s’est produit ?
Les traces répondent : où le temps est-il passé ?

Cette combinaison est ce qui transforme l’observabilité d’un tableau de bord en une explication.

Où se situe Codex

Codex fait partie de la même pile, mais il n’est pas identique à Claude Code.

Pour Codex, nous relions deux éléments :

L’OTEL natif de Codex vers Alloy
Un webhook de notification vers codex_notify.py, qui fait correspondre les fins de tour au même schéma Loki que celui utilisé pour les événements de hooks

Cela nous donne un filtre unifié comme agent_tool="codex-cli" à l’intérieur du même flux de logs.

La réserve honnête : la charge utile de notification de Codex est aujourd’hui plus légère que la charge utile de hooks de Claude Code, car ce n’est pas le même type d’interface d’intégration. Dans notre configuration actuelle, les fins de tour de Codex peuvent être normalisées dans le schéma partagé, mais une extraction riche outil par outil reste meilleure dans le flux OTEL natif que dans le pont de notification.

Ce n’est pas une raison d’éviter le sujet. C’est justement le propos de cet article. Les vrais systèmes d’observabilité s’assemblent à partir de signaux imparfaits.

Grafana via MCP change la donne

Le changement le plus important est que Grafana n’est plus seulement un lieu que les humains visitent dans un navigateur.

Dans ce dépôt, nous exposons aussi Grafana via MCP. Cela signifie qu’un agent peut interroger Loki, Prometheus et Tempo directement, au lieu d’attendre qu’un humain inspecte d’abord manuellement les tableaux de bord.

Cela transforme l’observabilité en une entrée active du flux de travail.

Un agent peut demander :

Quelles familles d’outils ont le plus échoué au cours de la dernière heure ?
Quel serveur MCP a dominé une session ?
Les changements récents ont-ils réduit les échecs d’outils, ou simplement déplacé le travail vers des chemins plus riches en shell avec les mêmes erreurs ?
Quelles traces montrent la latence la plus élevée ou des tentatives répétées ?

Une fois que vous avez cela, vous êtes très proche d’une boucle d’auto-amélioration.

Du tableau de bord à la boucle de rétroaction

C’est la partie que nous trouvons la plus intéressante.

Une fois que la pile d’observabilité devient interrogeable depuis la couche agent, la télémétrie cesse d’être une surface de reporting passive et devient un signal de contrôle.

La boucle ressemble à ceci :

L’activité des agents émet des traces, des métriques et des logs de hooks enrichis.
Grafana stocke les preuves dans Loki, Tempo et Prometheus, là où les métriques existent.
Les agents interrogent ces preuves via Grafana MCP.
Le système identifie un mauvais mélange d’outils, des compétences fragiles, un routage faible, ou des flux de travail riches en shell qui continuent de produire des erreurs évitables.
Les agents ou les opérateurs ajustent les prompts, les configurations d’agents, les descriptions de compétences, les règles de routage ou les accès aux outils.
La session suivante produit une nouvelle forme de télémétrie, et le cycle se répète.

C’est ainsi que l’on passe d’un « tableau de bord intéressant » à un « système d’amélioration mesurable ».

L’objectif n’est pas de maximiser une seule catégorie d’outils. C’est de trouver le bon mélange de CLI, d’outils intégrés, d’appels MCP et de compétences pour le travail réellement effectué.

Les questions auxquelles cela nous permet de répondre

Une fois que les deux runtimes atterrissent dans la même pile Grafana, nous pouvons répondre bien plus vite à des questions opérationnelles :

Les échecs sont-ils concentrés dans une seule famille d’outils ?
Les flux de travail riches en shell créent-ils des erreurs évitables là où un outil de plus haut niveau devrait exister ?
Quels serveurs MCP portent la charge de travail ?
Payons-nous pour une activité d’agent qui ne produit pas de progrès significatif ?
Une session est-elle malsaine à cause du modèle, des outils, ou de la couche d’orchestration ?

C’est particulièrement utile dans les flux de travail multi-agents, où « l’agent était occupé » ne vous apprend presque rien.

Si un spécialiste continue d’être dépêché et produit des taux d’échec élevés, c’est un problème de routage ou de façonnage des prompts.

Si un seul serveur MCP domine tous les appels, cela peut être une bonne architecture, ou un signe que tout le reste est du poids mort.

Si les échecs d’outils grimpent en flèche pendant que le coût reste élevé, vous avez un problème opérationnel, pas un problème de qualité.

Si le travail shell continue d’échouer de façon prévisible et évitable là où un outil de plus haut niveau devrait exister, c’est un signal produit.

Si une compétence s’active constamment sans améliorer les résultats, c’est un signal de prompt ou de routage.

La véritable leçon

La leçon la plus profonde ici est que l’observabilité des agents a besoin à la fois de télémétrie runtime et de télémétrie de flux de travail.

La télémétrie runtime vous dit ce que le système a fait.

La télémétrie de flux de travail vous dit ce que l’agent pensait être en train de faire.

Nous avons besoin des deux.

Si vous ne gardez que les traces et les compteurs, vous manquez la couche sémantique. Si vous ne gardez que les événements de hooks, vous manquez la latence, les spans et la vue d’ensemble du runtime.

Et si vous gardez les deux sans jamais les reboucler vers la couche agent, vous avez de la surveillance, pas de l’adaptation.

C’est cette combinaison qui rend le système suffisamment explicable pour être opéré, et suffisamment réglable pour être amélioré.

Ce qui reste imparfait

Il subsiste des aspérités.

Tous les événements de hooks n’incluent pas les données de durée et de tokens que nous souhaiterions.
Certaines des meilleures vues de chronométrage viennent encore des traces Tempo, pas des logs de hooks.
Codex est aujourd’hui moins riche sémantiquement que Claude Code dans le flux d’événements enrichi.
La capture d’écran du tableau de bord est une surface d’exploitation en direct, pas un artefact marketing poli.

Ce dernier point est volontaire. Nous préférons montrer le véritable tableau de bord de pilotage plutôt que de prétendre que les systèmes d’agents s’expliquent magiquement d’eux-mêmes.

Pourquoi cela compte pour Maguyva

Maguyva a pour vocation de donner aux agents une meilleure intelligence du code. Mais une fois que les agents accomplissent réellement un travail utile, une nouvelle exigence apparaît immédiatement : il faut voir comment ils se comportent.

La qualité de la recherche, la qualité du routage, la sélection des outils et l’efficacité du contexte deviennent tous des problèmes observables.

C’est pourquoi nous pensons que cela vaut la peine d’en parler. La pile d’agents de demain n’est pas seulement faite de prompts et d’outils. Elle est faite de prompts, d’outils, et de la couche d’instrumentation qui vous dit si l’ensemble fonctionne réellement.

Si vous construisez des flux de travail d’agents sérieux, l’observabilité n’est pas une infrastructure optionnelle. Elle fait partie du produit.

Exploiter l'historique pour refermer la boucle : comment les changements deviennent mémoire institutionnelle

Tue, 03 Feb 2026 00:00:00 GMT

Les chiffres de cet article reflètent le système au moment de la publication (février 2026). Consultez notre page équipe pour les chiffres actuels.

Chaque équipe d’ingénierie fait face au même défi : les changements se produisent en continu, mais le pourquoi derrière ces changements disparaît. Six mois plus tard, quelqu’un demande « pourquoi avons-nous adopté DuckDB pour les étapes du pipeline ? », et la réponse ne vit que dans la tête de la personne qui a pris cette décision — si elle est encore là.

Nous avons construit un flux de travail de minage qui referme cette boucle. Les changements transitent par les commits Git, sont traités par notre pipeline de minage, deviennent des entrées de changelog structurées et des fiches de décision architecturale, puis reviennent nourrir nos agents IA via des requêtes en ligne de commande. Le résultat : une mémoire institutionnelle accessible aussi bien aux humains qu’à l’IA.

Le problème : les décisions s’évaporent

Considérez un scénario typique. Un développeur commite :

feat(canonical): add DuckDB runtime for pipeline stages

Ce commit représente un choix architectural significatif. L’équipe a évalué des options, pesé des compromis, et opté pour DuckDB pour des raisons précises. Mais tout ce contexte vit dans :

Un fil Slack (probablement supprimé)
La mémoire de quelqu’un (qui s’estompe assurément)
Un commentaire dans le code (peut-être, si vous avez de la chance)

Trois mois plus tard, un nouveau membre de l’équipe demande : « Dois-je utiliser DuckDB ou SQLite pour cette nouvelle étape ? » Sans mémoire institutionnelle, il réinvente la roue ou fait des choix incohérents.

La boucle : des commits au contexte

Notre flux de travail de minage transforme l’historique Git en savoir interrogeable :

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

L’idée clé : les entrées de changelog et les décisions architecturales découlent toutes deux du même historique Git, traité par un pipeline unifié. Cela garantit que rien ne passe entre les mailles du filet.

Comment fonctionne le minage

Étape 1 : synchroniser l’index

uv run orkestra mine sync

Cette commande scanne l’historique Git et construit un index de tous les commits. Elle extrait de chaque commit des signaux structurés :

Type de commit selon Conventional Commits (feat, fix, chore, docs)
Portée (quel package ou quelle zone)
Marqueurs de changement cassant
Fichiers touchés et métriques de complexité

Étape 2 : vérifier le statut de couverture

uv run orkestra mine status

Voici à quoi ressemble notre statut actuel :

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

15 637 commits traités. 476 sont devenus des décisions architecturales. 6 799 sont devenus des entrées de changelog. Chaque commit est classé.

Étape 3 : obtenir des candidats à relire

uv run orkestra mine candidates --limit 50 --full

Cela fait remonter les commits pas encore traités, avec le contexte complet pour la classification :

{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

Les signaux aident à guider la classification : is_releasable_type: true suggère que ceci devrait apparaître dans le changelog. Le grand nombre d’insertions et les fichiers d’infrastructure suggèrent que cela pourrait aussi être une décision architecturale.

Étape 4 : classer les commits

Deux chemins divergent ici : les entrées de changelog et les décisions architecturales.

Pour les entrées de changelog :

uv run orkestra mine classify abc123 --changelog added

Cela enregistre que le commit abc123 doit apparaître dans le changelog sous la catégorie « Ajouté ».

Pour les décisions architecturales :

D’abord, obtenez un véritable identifiant de décision :

uv run orkestra registry decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

Puis classez avec cet identifiant de décision :

uv run orkestra mine classify abc123 --decision DEC-PL-143

Cela relie le commit à une fiche de décision qui sera créée ou mise à jour.

Pour le traitement par lots (ce que nous faisons réellement) :

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

Le format JSONL prend en charge les deux domaines en un seul passage :

{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

Étape 5 : générer les sorties

uv run orkestra registry changelog render --package <pkg>

Cela génère, à partir du registre, des fichiers CHANGELOG.md par package. Les changelogs sont des artefacts dérivés — supprimez-les, et ils se régénèrent parfaitement à partir du registre source.

La structure d’une fiche de décision

Les décisions extraites deviennent des fichiers YAML dotés de métadonnées riches :

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

Chaque décision renvoie à ses commits sources. Chaque décision précise quels fichiers elle affecte. Les relations entre décisions sont explicites.

Intégration CLI : interroger la mémoire institutionnelle

C’est ici que la boucle se referme. Les agents peuvent interroger les décisions via la CLI :

# Search by topic
uv run orkestra registry decisions search --query "retry"

Renvoie les décisions liées à la logique de nouvelle tentative, à la gestion des erreurs, aux schémas de récupération.

# Get full details on a specific decision
uv run orkestra registry decisions info DEC-PL-142

Renvoie la fiche de décision complète, avec contexte, justification et impact.

# List recent decisions for context
uv run orkestra registry decisions list --limit 15

Montre quels choix architecturaux ont été faits récemment.

Comment les agents utilisent cela

Les instructions de base de notre orchestrateur incluent :

**Essential CLI commands:**
- `orkestra registry decisions search "X"` — Find architectural decisions

Quand un agent reçoit la demande d’implémenter quelque chose lié à DuckDB, il peut d’abord vérifier :

uv run orkestra registry decisions search --query "DuckDB"

Et découvrir DEC-PL-142, apprenant ainsi :

Pourquoi nous avons choisi DuckDB (context)
Comment l’utiliser correctement (agent_guidance)
Quels fichiers consulter (files)
Quelles décisions connexes existent (related)

L’agent ne réinvente pas la roue. Il s’appuie sur des schémas déjà établis.

Le test des trois questions

Tout commit ne mérite pas une fiche de décision. Nous utilisons le test des trois questions pour filtrer :

Était-ce difficile à décider ? Cela a-t-il exigé une analyse significative, une évaluation de compromis, ou un débat ?
Est-ce coûteux à changer ? Revenir sur cette décision exigerait-il un travail de refonte important ?
A-t-elle un impact à l’échelle du système ? Affecte-t-elle plusieurs packages, ou établit-elle des schémas que d’autres suivront ?

Si un commit répond « oui » à au moins une de ces questions, il est candidat à l’extraction en décision. Notre taux habituel : 1 à 4 décisions pour 100 commits (environ 1 à 4 %).

Pour les entrées de changelog, la barre est plus basse : tout changement visible par l’utilisateur (fonctionnalités, corrections, améliorations) est enregistré. Les tâches internes, les mises à jour de documentation et les refactorisations sont généralement écartées. Notre taux habituel : 30 à 50 entrées de changelog pour 100 commits.

Stockage des données : registres en ajout seul

Le système de minage utilise des registres JSONL en ajout seul, pour un fonctionnement multi-agents sans conflit :

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

Le format JSONL, avec merge=union dans .gitattributes, signifie que plusieurs agents peuvent classer des commits simultanément sans conflit de fusion. Chaque ligne est indépendante.

Contrôles de validation

Avant toute session de minage, nous exécutons une validation :

uv run orkestra mine validate --quick

Cela vérifie :

La validité du format SHA
La conformité du format d’identifiant de décision
L’absence d’entrées en double pour un même SHA
L’existence réelle des décisions référencées

Après la classification, nous validons à nouveau avant de commiter les changements.

Pourquoi cela compte

La boucle de rétroaction que nous avons construite résout plusieurs problèmes :

Pour les nouveaux membres de l’équipe : au lieu de demander « pourquoi avons-nous fait X ? », ils peuvent chercher dans le registre des décisions. Le contexte est préservé.

Pour les agents IA : ils n’opèrent pas dans le vide. Ils peuvent interroger le savoir institutionnel avant de formuler des recommandations. Quand on leur demande d’ajouter une nouvelle étape de pipeline, ils peuvent découvrir le schéma DuckDB et le suivre.

Pour la cohérence architecturale : les décisions sont explicites et interrogeables. Quand quelqu’un propose une approche qui contredit une décision existante, le système peut faire remonter le conflit.

Pour la génération du changelog : les notes de version ne sont pas une course de dernière minute. Elles sont un sous-produit de la classification continue pendant le développement.

Pour l’intégration : les nouveaux agents héritent du contexte complet de la base de code. Ils ne voient pas seulement le code — ils voient les décisions qui l’ont façonné.

État actuel

À ce jour :

15 637 commits traités par le pipeline
476 décisions architecturales extraites et documentées
6 799 entrées de changelog enregistrées
100 % de couverture sur les deux domaines

Chaque commit depuis nos débuts a été classé. La mémoire institutionnelle est complète et interrogeable.

Pour commencer

Si vous voulez implémenter quelque chose de similaire :

Commencez par des commits au format Conventional Commits. Le pipeline de minage fonctionne mieux quand les commits ont des préfixes structurés (feat:, fix:, chore:).
Définissez vos domaines. Nous utilisons des domaines comme pipeline, agent-design, observability, data-modeling. Ils organisent les décisions par zone.
Construisez l’habitude de classification. Le minage fonctionne quand les équipes classent régulièrement les commits. Le traitement par lots assisté par LLM aide à passer à l’échelle.
Rendez les décisions interrogeables. La valeur s’accumule quand les agents peuvent chercher les décisions via la CLI. Structurez votre sortie pour une consommation par machine.
Refermez la boucle. Les décisions doivent influencer le travail futur. Incluez des références aux décisions dans les instructions des agents et les listes de vérification de revue de code.

L’objectif n’est pas une documentation parfaite. C’est de rendre le pourquoi derrière les changements accessible, à la fois aux humains et à l’IA, aujourd’hui comme dans six mois. Quand les changements deviennent mémoire institutionnelle, les équipes construisent sur des schémas établis plutôt que de les réinventer.

Le flux de travail de minage fait partie de notre moteur d’orchestration, plus précisément du module de moteur de contexte de notre package d’orchestration.

Extraction de compétences : de 3 500 candidates à 466 capacités

Tue, 27 Jan 2026 00:00:00 GMT

Les chiffres de cet article reflètent le système au moment de la publication (janvier 2026). Consultez notre page équipe pour les chiffres actuels.

Le problème des 3 500 compétences

Quand nous avons commencé à construire un système d’orchestration d’agents, nous avons fait face à un défi intéressant : des milliers de compétences potentielles sont éparpillées dans tout l’écosystème IA. Dépôts GitHub, documentation d’éditeurs, projets communautaires, schémas internes — les compétences existent partout. Mais lesquelles comptent ? Lesquelles fonctionnent ? Et comment maintenir une bibliothèque de compétences cohérente que les agents peuvent réellement utiliser ?

Notre réponse : une boucle systématique d’extraction et d’ingestion.

Les chiffres aujourd’hui

À peine plus de trois mois après le lancement des Agent Skills par Anthropic le 16 octobre 2025, voici où nous en étions à la publication de cet article, le 27 janvier 2026 :

Métrique	Nombre
Candidates identifiées	plus de 3 500
Compétences adoptées	466
Compétences d’éditeurs	373
Compétences internes	93
Éditeurs actifs	plus de 25
Tokens moyens par compétence	2 834
Outils référencés	89
Tags uniques	635

Nous avons passé en revue plus de 3 500 compétences candidates. Nous en avons adopté 466. Cela représente un taux d’adoption de 13 % — et cette sélectivité est voulue.

Le système de paliers de connaissance

Toutes les compétences ne se valent pas. Nous les organisons en cinq couches de connaissance (K0-K4), chacune représentant une portée d’applicabilité différente :

K0 : Fondations (universelles)

Des compétences que chaque agent devrait posséder. Elles représentent des capacités de « bon penseur » qui fonctionnent partout.

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

Les compétences K0 sont portables vers n’importe quel projet, domaine ou pile technologique. Elles encodent des schémas cognitifs universels.

K1 : Identités (discipline)

Des compétences de « bon ingénieur » ou de « bon chercheur » qui s’appliquent à travers les projets au sein d’une discipline.

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2 : Domaines (expertise sur un sujet)

Des compétences de « bon expert base de données » ou de « bon ingénieur sécurité », portables au sein d’un domaine.

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3 : Piles techniques (technologie)

Des compétences de « bon utilisateur Supabase » ou de « bon développeur Cloudflare » pour des piles technologiques spécifiques.

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4 : Projet (organisation)

Des compétences propres à notre organisation et à nos flux de travail.

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

La boucle d’extraction

Phase 1 : découverte

Les compétences viennent de partout :

Dépôts d’éditeurs : AWS, Anthropic, Cloudflare, Supabase et des contributeurs communautaires publient des collections de compétences. Nous suivons plus de 25 racines d’éditeurs.

Projets communautaires : GitHub regorge de templates Claude Code, de schémas d’agents et de définitions de flux de travail.

Schémas internes : à mesure que notre équipe résout des problèmes, des schémas émergent. Ils sont formalisés en compétences.

Extraction depuis la documentation : la documentation technique contient souvent des compétences implicites — procédures, listes de vérification, arbres de décision.

La découverte est continue. Nous utilisons un backlog de compétences pour suivre les candidates avant évaluation formelle.

Phase 2 : évaluation

Chaque candidate passe par la même grille :

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

Les cinq critères produit doivent tous être satisfaits. C’est pourquoi 87 % des candidates sont rejetées.

Ensuite, chaque candidate passe par une revue de confiance distincte. Nous ne traitons pas un dépôt officiel d’éditeur, un mainteneur communautaire bien connu et un dépôt GitHub aléatoire comme des sources de vérité équivalentes.

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

Les éditeurs de confiance bénéficient d’une revue de provenance plus légère, mais pas d’un laissez-passer. Les sources non fiables ou inconnues subissent un audit manuel plus approfondi, et nous n’exécutons pas les scripts intégrés avant qu’ils n’aient été lus, délimités, et classés comme sûrs.

Analyse d’écart : avant d’adopter, nous cherchons dans notre registre :

uv run orkestra skills search "<capability>"

Si nous l’avons déjà, nous n’en avons pas besoin. Si nous avons quelque chose de proche, nous pourrions fusionner plutôt qu’adopter.

Notation de profondeur et de conformité aux standards : nous notons aussi à quel point une candidate exploite pleinement le modèle agent-compétence. Un simple SKILL.md isolé peut rester utile, mais des compétences plus profondes ont plus de valeur quand elles séparent instructions, références, scripts et actifs comme le recommande agentskills.io.

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

Les étoiles GitHub peuvent légèrement rehausser un score de crédibilité, mais elles ne sauvent jamais une compétence superficielle ou dangereuse. Un dépôt très étoilé avec un seul SKILL.md vague et des scripts opaques obtient une moins bonne note qu’un plus petit dépôt avec une description précise, des references/ soignées, et des utilitaires atomiques qui exploitent réellement toute la capacité du modèle de compétence.

Analyse structurelle : nous vérifions la qualité de la compétence :

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

Si une candidate inclut des scripts, cette revue devient plus stricte. Une bonne compétence n’est pas seulement utile ; elle doit être lisible, délimitée et sûre à confier à un agent. Ce seul filtre de sécurité disqualifie une part significative de candidates par ailleurs intéressantes.

Phase 3 : ingestion

Quand une compétence passe l’évaluation, elle entre dans le registre. Mais les compétences ne sont jamais adoptées sans modification. Elles sont adaptées à notre système.

Modifications lors de l’adoption :

Normalisation des métadonnées : chaque compétence reçoit notre schéma de frontmatter
Attribution du palier K : les compétences sont placées dans la couche de connaissance appropriée
Enrichissement des tags : des tags sont ajoutés pour la découverte
Déclaration des outils : les outils autorisés sont explicitement déclarés
Alignement des sections : le contenu est restructuré pour correspondre à notre modèle

Un YAML de compétence typique après ingestion :

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

Phase 4 : attribution de portée

Les compétences sont attribuées à des portées — des catégories qui déterminent quels agents chargent quelles compétences :

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

Les agents déclarent leurs portées, et les compétences sont attribuées automatiquement :

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

Phase 5 : matérialisation

Les compétences ne vivent pas en YAML en production. Elles sont rendues en fichiers SKILL.md que Claude Code peut charger :

uv run orkestra sync

Cette commande :

Lit toutes les définitions YAML de compétences
Les rend via des templates Jinja
Écrit les fichiers SKILL.md dans .claude/skills/
Organise par palier K (foundations/, identities/, domains/, stacks/, project/)

La structure de sortie finale :

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

Le schéma des portées dormantes

L’un de nos schémas les plus puissants est celui des compétences « adoptées mais non chargées ». Nous appelons cela des portées dormantes.

Prenez les compétences de calcul scientifique du dépôt k-dense-scientific. Nous avons adopté plus de 120 compétences couvrant la bio-informatique, la chimie, l’informatique quantique et l’informatique clinique. Mais la plupart de nos agents n’ont pas besoin d’amarrage moléculaire ni d’analyse d’expression génique.

Au lieu de charger les 120 compétences dans chaque agent (ce qui gonflerait les fenêtres de contexte), nous :

Adoptons les compétences avec une portée spécifique (par exemple, bioinformatics)
Les gardons dormantes — enregistrées mais non chargées
Les activons seulement quand un agent déclare cette portée

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

Ce schéma nous permet d’avoir 466 compétences dans le registre, tandis qu’un agent typique n’en charge que 40 à 60 pertinentes.

Types de compétences

Les compétences suivent trois schémas cognitifs :

Flux de travail

Des étapes procédurales ordonnées : « 1. Faire X, 2. Puis Y, 3. Enfin Z »

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

Discipline

Des garde-fous comportementaux : « Toujours X », « Jamais Y », « Préférer Z »

type: discipline
# Examples: test-first-discipline, evidence-based-completion

Liste de vérification

Des critères de vérification : « Confirmer X », « Vérifier Y », « Contrôler Z »

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

Contrôles qualité

Chaque compétence doit passer une validation avant de partir en production :

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

Les descriptions doivent compter de 50 à 400 caractères, avec des phrases de déclenchement (« À utiliser quand… », « Quand vous avez besoin de… ») pour que Claude Code sache quand les suggérer.

Nous validons en continu :

uv run orkestra validate --show-warnings

L’écosystème d’éditeurs

Nos 373 compétences d’éditeurs viennent de :

Fournisseur	Compétences	Domaine
AWS Agent	19	Services cloud
Anthropic	12	Génération de documents
Cloudflare	8	Edge computing
Supabase	5	Base de données
k-dense	plus de 100	Calcul scientifique
silvainfm	4	Data science
Java Developer Kit	plus de 45	Spring/Java
Vercel	1	Automatisation navigateur

Chaque racine d’éditeur est déclarée dans metadata.yaml :

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

Quand orkestra sync s’exécute, les compétences d’éditeurs sont liées par symlink dans .claude/skills/vendor/ avec leur espace de noms fournisseur.

Ce que nous avons appris

La sélectivité paie. Il est tentant d’adopter tout ce qui paraît utile. Mais chaque compétence coûte des tokens. Avec 2 834 tokens en moyenne par compétence, le gonflement fait mal vite. Notre taux d’adoption de 13 % garde les agents légers.

La structure permet la découverte. Le système de paliers K n’est pas qu’une question d’organisation — c’est une question de portabilité. Les compétences K0 sont réutilisables partout. Les compétences K4 sont intentionnellement propres au projet. Cette clarté aide les humains comme les agents à trouver ce dont ils ont besoin.

Les portées dormantes passent à l’échelle. Vous pouvez adopter des centaines de compétences sans toutes les charger. Les portées vous permettent de construire un registre exhaustif tout en gardant maniables les fenêtres de contexte de chaque agent.

La modification lors de l’adoption est essentielle. Les compétences brutes d’éditeurs correspondent rarement à votre système. Le processus d’ingestion — ajouter des métadonnées, attribuer des paliers, enrichir les tags — fait fonctionner les compétences externes en interne.

L’extraction est continue. Le chiffre de 3 500 continue de croître. De nouveaux dépôts d’éditeurs apparaissent. Des schémas communautaires émergent. Des flux de travail internes se solidifient. La boucle ne s’arrête jamais.

Et ensuite

Nous travaillons sur plusieurs améliorations :

Détection automatisée d’écarts : alerter quand des échecs courants d’agents pourraient être résolus par une compétence non adoptée
Flux de travail de dépréciation des compétences : un processus formel pour retirer les compétences supplantées ou inutilisées
Dépendances entre compétences : déclaration explicite des prérequis d’une compétence
Analytique d’usage : suivre quelles compétences les agents invoquent réellement, par opposition à celles qu’ils se contentent de charger

La boucle d’extraction de compétences est de l’infrastructure. Ce n’est pas glamour. Mais c’est ce qui fait que 41 agents travaillent de façon cohérente avec 466 capacités, tout en restant dans les limites de contexte.

Voilà l’histoire de comment 3 500 devient 466. Pas en ignorant 3 000 — en les évaluant systématiquement et en n’adoptant que ce qui fonctionne.

Vous voulez voir le système de compétences en action ? Consultez uv run orkestra skills list pour explorer notre registre actuel.

Divulgation progressive : des fenêtres CLI sur les systèmes d'agents

Tue, 20 Jan 2026 00:00:00 GMT

Les chiffres de cet article reflètent le système au moment de la publication (janvier 2026). Consultez notre page équipe pour les chiffres actuels.

Les systèmes d’agents sont opaques par conception. Ils prennent des décisions, invoquent des outils et coordonnent le travail entre des dizaines de spécialistes. Mais quand quelque chose tourne mal — ou quand vous voulez simplement comprendre ce qui se passe — où regarder ?

La réponse, c’est la divulgation progressive : une interface en couches qui révèle exactement autant de complexité que nécessaire, exactement au moment où c’est nécessaire.

Le problème de l’opacité

Un système moderne d’orchestration d’agents peut compter :

Plus de 40 agents spécialistes, chacun doté de capacités distinctes
Plus de 700 compétences couvrant l’automatisation interne et les intégrations tierces
Plus de 470 décisions architecturales façonnant le comportement
Des dizaines de serveurs d’outils MCP fournissant des capacités externes

Cette complexité est intentionnelle. Les agents ont besoin d’accéder à un contexte riche — savoir de domaine, intelligence du code, schémas de base de données — pour prendre de bonnes décisions. Mais cette même richesse crée un problème de visibilité.

Comment savoir quel agent gère les migrations de base de données ? Quelles décisions ont façonné le comportement de classement du système de recherche ? À quels outils le conseiller en architecture a-t-il accès ?

Sans accès structuré, il ne vous reste plus qu’à lire le code source ou espérer que la documentation est à jour.

La divulgation progressive comme architecture

La divulgation progressive n’est pas qu’un schéma d’interface utilisateur. C’est un principe architectural : organiser l’information en couches, chacune plus profonde que la précédente, pour que les utilisateurs puissent s’arrêter au niveau qui répond à leur question.

Pour les systèmes d’agents, cela se traduit par des commandes CLI à des profondeurs croissantes :

Niveau	Commande	Question à laquelle on répond
1	`orkestra system status`	Tout va-t-il bien ?
2	`orkestra agents list`	Quels agents existent ?
3	`orkestra agents info <name>`	Que fait cet agent ?
4	`orkestra decisions search`	Pourquoi fonctionne-t-il ainsi ?
5	Outils MCP de Maguyva	Montrez-moi le code.

Chaque niveau répond à une question de suivi naturelle. Vous avez rarement besoin de sauter directement au niveau 5.

Niveau 1 : santé du système

La première question est toujours : tout fonctionne-t-il ?

$ orkestra system status

{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

Une seule commande. Quatre chiffres. Suffisant pour savoir que le système est configuré et que les registres sont peuplés.

Si le nombre d’agents chute de façon inattendue, ou si des compétences échouent à se charger, vous le voyez ici en premier. Pas besoin de plonger dans les logs.

Niveau 2 : inventaire des agents

Une fois que vous savez que le système est en bonne santé, la question suivante est : qu’y a-t-il de disponible ?

$ orkestra agents list

Cela renvoie des données structurées — noms d’agents, descriptions, préférences de modèle, couverture de domaine. La sortie est en JSON par défaut, ce qui la rend facile à faire transiter par jq pour du filtrage :

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

Vous voulez des agents qui gèrent le travail base de données ? La commande de recherche réduit le champ :

$ orkestra agents search "database"

Cela scanne les noms, descriptions et capacités. Vous trouvez le bon spécialiste sans lire 40 définitions d’agents.

Niveau 3 : plongée dans un agent

Vous avez trouvé un agent qui semble pertinent ? La commande info révèle tout :

$ orkestra agents info architecture-advisor

La sortie inclut :

Métadonnées : nom, catégorie, préférence de modèle, description
Domaines : quelles zones de savoir cet agent couvre
Identité : traits de caractère (architecte, stratège, architecte-connaissances)
Guides d’outils : quelle documentation d’outil est injectée dans le contexte
Outils : la liste complète des outils MCP disponibles pour cet agent

Voici un échantillon de ce que vous voyez :

{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

Cela vous indique exactement ce que l’agent peut faire. Aucun code source requis.

Niveau 4 : archéologie des décisions

Les agents se comportent selon des décisions documentées. Quand vous devez comprendre pourquoi quelque chose fonctionne d’une manière particulière, le registre des décisions est la source de vérité.

$ orkestra decisions search "agent"

Cela renvoie les décisions architecturales correspondantes :

{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

Chaque décision dispose d’une provenance complète — quand elle a été prise, pourquoi, quels compromis ont été considérés, quels commits l’ont mise en œuvre :

$ orkestra decisions info DEC-SR-049

{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

C’est de la documentation architecturale qui reste à jour, parce qu’elle est extraite des commits, pas maintenue manuellement.

Niveau 5 : intelligence du code directe

Quand vous devez voir l’implémentation réelle — pas des métadonnées à son sujet — les outils MCP de Maguyva fournissent un accès direct.

Depuis une session d’agent :

mcp__maguyva__intelligent_search
  query: "agent context loading"

Cela route automatiquement entre recherche sémantique, textuelle et AST pour trouver le code pertinent. Pour des symboles spécifiques :

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Pour l’analyse de dépendances :

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

Ce ne sont pas de simples remplacements de grep. Ils tiennent compte du graphe, sont indexés sémantiquement, et intégrés à la même intelligence du code qui alimente les agents eux-mêmes.

Recherche unifiée entre registres

Parfois, vous ne savez pas quel registre détient la réponse. La recherche unifiée couvre tout :

$ orkestra search "database" --summary

{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

254 correspondances sur cinq registres. Le résumé vous indique où creuser. Retirez --summary pour des résultats détaillés, ou ajoutez --limit 5 pour garder une sortie maniable.

Pourquoi cela compte

La divulgation progressive ne concerne pas que la commodité. Elle change la façon dont vous interagissez avec des systèmes complexes.

Le débogage devient maîtrisable. Quand un agent prend une décision inattendue, vous ne fouillez pas les logs à coups de grep. Vous vérifiez à quels outils il a accès (agents info), quelles décisions façonnent son comportement (decisions search), et tracez l’implémentation si nécessaire (intelligent_search).

L’intégration s’accélère. Les nouveaux membres de l’équipe n’ont pas besoin de lire toute la base de code. Ils commencent avec system status, explorent avec agents list, et n’approfondissent que quand ils tombent sur quelque chose qu’ils ne comprennent pas.

La documentation reste à jour. Parce que la CLI lit dans les mêmes registres qui configurent les agents, la sortie est toujours exacte. Il n’y a pas de dérive entre ce que dit la documentation et ce que fait le système.

La CLI comme interface

Nous aurions pu construire un tableau de bord web. Nous aurions pu écrire une documentation exhaustive. Au lieu de cela, nous avons construit une CLI qui lit directement dans la source de vérité.

La CLI a des avantages :

Composable : faire transiter la sortie par jq, s’intégrer à des scripts
Scriptable : automatiser des vérifications, générer des rapports
Rapide : pas de chargement de page, pas de flux d’authentification
Exacte : lit la configuration réelle, pas une représentation mise en cache

Pour les systèmes où la justesse compte plus que l’esthétique, la CLI l’emporte.

Construire votre propre divulgation progressive

Si vous construisez des systèmes d’agents, réfléchissez à la façon dont les utilisateurs les inspecteront :

Commencez par des contrôles de santé. Une commande qui vous dit si tout fonctionne.
Fournissez des vues d’inventaire. Listez ce qui existe avant d’expliquer ce que cela fait.
Activez des requêtes ciblées. La recherche l’emporte sur la navigation à grande échelle.
Exposez la provenance. Laissez les utilisateurs tracer les décisions jusqu’à leurs origines.
Connectez-vous à l’intelligence du code. Au bout du compte, les utilisateurs doivent voir l’implémentation.

Chaque couche répond à une question de suivi. Construisez-les par ordre de fréquence — la plupart des utilisateurs s’arrêtent au niveau 2 ou 3. Seuls les utilisateurs avancés atteignent le niveau 5.

L’objectif n’est pas de tout exposer. C’est d’exposer exactement ce qui est nécessaire, exactement quand c’est nécessaire. C’est la divulgation progressive appliquée à l’architecture d’agents.

Vérités de terrain : ancrer les agents IA dans la réalité

Tue, 13 Jan 2026 00:00:00 GMT

Les chiffres de cet article reflètent le système au moment de la publication (janvier 2026). Consultez notre page équipe pour les chiffres actuels.

Les agents IA sont remarquablement capables. Ils savent raisonner, synthétiser et générer. Mais ils ont une faiblesse fondamentale : ils inventent des choses. Pas par malveillance, mais avec assurance. Un agent peut inventer des paramètres d’API qui n’existent pas, référencer des configurations qui n’ont jamais été définies, ou appliquer des schémas issus de ses données d’entraînement qui contredisent votre architecture réelle.

La parade habituelle est de « donner plus de contexte à l’agent ». Mais le contexte peut être contradictoire. La documentation dérive par rapport à l’implémentation. Les commentaires mentent. Même le code peut induire en erreur quand on le lit sans comprendre l’intention.

Il nous fallait quelque chose de plus explicite. Quelque chose qui ne puisse être ni ignoré ni mal interprété. Quelque chose qui ancre les agents dans une réalité vérifiable.

Nous les appelons les Vérités de terrain.

Qu’est-ce qu’une vérité de terrain ?

Une vérité de terrain est un énoncé de fait explicite et versionné que les agents doivent respecter. Ce n’est pas de la documentation. Ce n’est pas un commentaire. C’est une entité à part entière dans le système, dotée de :

Un identifiant unique (comme GT-MAG-015 ou GT-MAG-036)
Un statut de cycle de vie (actuelle, provisoire ou obsolète)
Une portée (à l’échelle de la plateforme, spécifique à un package, ou liée à un domaine)
Des preuves (chemins de fichiers, URL ou références qui étayent l’énoncé)
Des consignes pour l’agent (instructions explicites à faire ou à éviter)

Voici un exemple tiré de notre plateforme d’intelligence du code Maguyva :

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

Ce n’est pas de la prose. C’est un contrat. Quand un agent rencontre cette vérité de terrain, il sait :

Le comportement par défaut est déterministe (résultats vides, pas de suppositions floues)
Il existe des paramètres spécifiques (find_similar, exact_match) au comportement défini
Des preuves existent dans des fichiers précis, vérifiables
L’énoncé a été vérifié à une date précise

L’anatomie d’un registre de vérités de terrain

Les vérités de terrain vivent dans des registres YAML sous ai_assets/reference/ground_truths.yaml. Chaque package ou domaine peut avoir son propre registre. La structure est la suivante :

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

Le registre inclut des métadonnées sur la collection elle-même, une configuration de rendu pour la génération de documentation, et les énoncés eux-mêmes. Chaque énoncé suit un schéma strict validé par des modèles Pydantic :

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

Comment les agents accèdent aux vérités de terrain

Les vérités de terrain sont exposées via plusieurs canaux :

1. Documentation rendue

La commande orkestra sync transforme les registres YAML en markdown lisible :

uv run orkestra sync

Cela génère des fichiers GROUND_TRUTHS.md qui sont inclus dans le contexte de l’agent. Le rendu regroupe les énoncés par statut et par catégorie :

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. Recherche en ligne de commande

Les agents disposant d’un accès shell peuvent rechercher des vérités de terrain de manière programmatique :

uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current

La fonction de recherche note les correspondances sur plusieurs champs avec une pertinence pondérée :

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. Composition du contexte

Quand les agents sont générés à partir de définitions YAML, leur contexte peut référencer des registres de vérités de terrain :

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

Cela garantit que les vérités de terrain pertinentes sont chargées avant que l’agent ne commence à travailler.

Catégories de vérités de terrain

En parcourant nos registres, les vérités de terrain se regroupent en plusieurs schémas :

Principes produit

Des contraintes sur ce que le produit est et n’est pas :

« Maguyva est en lecture seule vis-à-vis des dépôts des utilisateurs ; le seul actif non reconstructible est le cache d’embeddings payant. » (GT-MAG-001)

Frontières architecturales

Où vivent les responsabilités, et pourquoi :

« Les frontières entre pipeline et Maguyva sont intentionnelles : pipeline est réutilisable, Maguyva porte la logique propre au code, et le CQRS sépare les écritures des étapes des lectures du serveur. » (GT-MAG-006)

Règles anti-hallucination

Des mandats explicites qui gardent les contrats d’outils déterministes plutôt qu’inférés :

« La correspondance floue de symboles est optionnelle via find_similar=true. Le comportement par défaut renvoie des résultats vides pour les symboles inexistants ; exact_match=true impose une correspondance stricte et désactive tous les replis flous. » (GT-MAG-015)

Contrôles qualité

Des standards à maintenir :

« Les modifications de l’infrastructure partagée (post_filters.py, extracteurs de relations, handlers partagés) DOIVENT être validées face à TOUS les langages pris en charge, via une génération complète du manifeste, avant tout commit. Une validation sur un seul langage est insuffisante pour du code partagé. » (GT-MAG-036)

Schémas de code

Des exigences d’implémentation :

« Utilisez asyncio.to_thread() pour le travail lié au CPU dans des contextes asynchrones ; le schéma déprécié loop.run_in_executor() ne doit pas être utilisé dans du nouveau code. » (GT-MAG-018)

Le cycle de vie d’une vérité de terrain

Les vérités de terrain ne sont pas statiques. Elles évoluent selon un cycle de vie défini :

Provisoire

Une vérité proposée, en cours d’évaluation. L’énoncé est enregistré mais peut changer :

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Actuelle

Une vérité vérifiée que les agents doivent respecter. Les preuves ont été validées :

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Obsolète

Une vérité qui ne s’applique plus. Conservée à titre de référence historique, avec un pointeur vers ce qui l’a remplacée :

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

Pourquoi pas simplement de la documentation ?

La documentation sert un autre objectif. Elle explique. Elle enseigne. Elle peut être vague, utiliser des qualificatifs comme « généralement » ou « typiquement ».

Les vérités de terrain ne peuvent pas être vagues. Ce sont des assertions. Elles s’appliquent, ou elles ne s’appliquent pas.

Considérez la différence :

Documentation : « L’API renvoie généralement des résultats vides quand un symbole n’est pas trouvé, bien que la correspondance floue puisse être activée dans certaines configurations. »

Vérité de terrain : « Le comportement par défaut renvoie des résultats vides pour les symboles inexistants ; exact_match=true impose une correspondance stricte et désactive tous les replis flous. »

La première est utile pour les humains qui apprennent le système. La seconde est exploitable pour les agents qui prennent des décisions.

Consignes pour l’agent : à faire et à éviter

Certaines vérités de terrain incluent des consignes explicites pour l’agent :

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

Cela lève toute ambiguïté. Un agent qui lit cela sait non seulement ce qui est vrai, mais aussi quelles actions cette vérité implique.

Vérification et maintenance

Les vérités de terrain demandent de la maintenance. Nous suivons :

last_verified : la date à laquelle quelqu’un a confirmé que l’énoncé tient toujours
evidence : les fichiers qui étayent l’énoncé (leur existence peut être vérifiée)
source : d’où vient la vérité (inspection en CLI, revue d’architecture, apprentissage post-incident)

Une vérité de terrain dont les dates de vérification sont anciennes ou dont les liens de preuve sont rompus est un signal à investiguer. Soit la vérité est toujours valide et a besoin d’être revérifiée, soit la réalité a changé et la vérité doit être mise à jour.

Exemples réels tirés de la production

Frontière de sécurité

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

Cette vérité de terrain empêche une catégorie de fausses « améliorations de sécurité » qui casseraient le produit.

Précision au moment de l’extraction

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

Cela vient d’une expérience douloureuse. Des agents corrigeaient des packs de langage défaillants en ajoutant des filtres réservés au validateur, qui faisaient paraître le harnais de test plus vert, alors que l’extracteur Maguyva en production continuait d’émettre les mauvaises arêtes. La règle force les corrections à revenir dans le vrai chemin : configuration YAML, requêtes, ou handlers.

Filtrage multi-niveaux

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

Cela empêche les agents d’ajouter des filtres au mauvais endroit, une erreur courante qui a provoqué des régressions de précision.

Intégration avec le système d’orchestration

Les vérités de terrain sont une couche parmi d’autres d’un système de contexte plus large :

Décisions architecturales (ADR) — enregistrent pourquoi nous avons choisi l’approche A plutôt que B
Vérités de terrain — énoncent ce qui est établi avec certitude à ce jour
Schémas de domaine — décrivent comment bien faire les choses
Anti-schémas — décrivent ce qu’il faut éviter, et pourquoi

Un agent qui travaille dans le système a accès aux quatre. Les vérités de terrain fournissent l’ancrage factuel, tandis que les décisions expliquent l’historique, les schémas guident l’implémentation, et les anti-schémas préviennent des pièges.

Mesurer l’impact

Depuis l’introduction des vérités de terrain, nous avons observé :

Moins de cycles « corriger la correction hallucinée »
Une prise de décision plus assurée des agents quand les faits sont clairs
De meilleures revues de PR, parce que les attentes sont explicites
Un temps d’intégration réduit pour les nouveaux agents (et les nouveaux humains)

L’investissement dans la maintenance des vérités de terrain se traduit par moins de débogage et des frontières système plus claires.

Pour commencer

Pour ajouter une vérité de terrain à votre système :

Créez un ground_truths.yaml dans le répertoire ai_assets/reference/ de votre package
Définissez les métadonnées et la configuration de rendu
Ajoutez les énoncés en suivant le schéma
Exécutez uv run orkestra sync pour générer la documentation
Incluez le registre dans la composition du contexte de l’agent

Commencez par les faits qui provoquent le plus de confusion, ou les contraintes les plus souvent violées. Ce sont vos vérités de terrain les plus précieuses.

Conclusion

Les agents IA vont halluciner. C’est leur nature. Mais nous pouvons créer des environnements où l’hallucination est contrainte, où certains faits ne sont pas négociables, où les agents peuvent confronter leurs suppositions à une réalité vérifiée.

Les vérités de terrain ne sont pas une solution complète. Elles demandent de la maintenance. Elles peuvent devenir obsolètes. Elles ajoutent une charge au processus de développement.

Mais elles apportent quelque chose de précieux : un vocabulaire partagé de faits auquel humains et agents peuvent tous deux faire confiance. Dans un monde où les agents participent de plus en plus au développement logiciel, ce socle commun devient essentiel.

L’alternative, ce sont des cycles sans fin d’agents commettant des erreurs avec assurance et d’humains les corrigeant. Les vérités de terrain brisent ce cycle en rendant les corrections explicites et durables.

Vos agents méritent de savoir ce qui est vrai. Dites-le-leur.

Orkestra : orchestrer des agents IA à grande échelle

Tue, 06 Jan 2026 00:00:00 GMT

Les chiffres de cet article reflètent le système au moment de la publication (janvier 2026). Consultez notre page équipe pour les chiffres actuels.

Quand nous avons commencé à construire avec Claude Code, nous nous sommes heurtés à un problème que toute équipe utilisant des assistants de codage IA finit par rencontrer : un seul agent ne peut pas tout bien faire.

Vous pouvez demander à un agent d’être un spécialiste base de données. Ou un auditeur de sécurité. Ou un ingénieur frontend. Mais dès l’instant où vous lui demandez d’être les trois à la fois, la qualité en souffre. Le contexte se dilue. Les instructions entrent en conflit. L’agent devient un généraliste médiocre en tout.

Nous avons donc construit Orkestra.

Qu’est-ce qu’Orkestra ?

Orkestra est un système d’orchestration d’agents pour Claude Code et les outils de codage IA similaires. Il coordonne plusieurs agents spécialisés, chacun doté d’une expertise distincte, sous un orchestrateur unique qui répartit le travail vers le bon spécialiste.

Imaginez-le comme une agence de placement pour agents IA. L’orchestrateur reçoit une tâche, identifie quel spécialiste doit la traiter, et délègue avec le bon contexte. Une fois le travail fait, les résultats remontent vers l’orchestrateur pour synthèse.

Les chiffres parlent d’eux-mêmes :

Composant	Nombre
Agents spécialistes	46
Compétences réutilisables	466
Archétypes d’identité	27
États d’esprit	11
Styles de communication	10
Domaines de connaissance	21

Le système de personnage : le D&D des agents

L’idée centrale derrière Orkestra est que le comportement d’un agent émerge de trois primitives composables :

L’identité définit ce que l’agent est. Un architecte conçoit des structures système. Un débogueur remonte des échecs jusqu’à leurs causes racines. Un gardien fait respecter la conformité et les frontières de sécurité. Nous avons 27 archétypes d’identité qui peuvent être combinés.

L’état d’esprit définit comment l’agent pense. Un état d’esprit analytique ancre les affirmations dans des preuves et quantifie l’incertitude. Un état d’esprit sceptique interroge les hypothèses et recherche des preuves contradictoires. Un état d’esprit exploratoire embrasse l’ambiguïté et essaie plusieurs approches.

Le style définit comment l’agent communique. Un style technique inclut des valeurs exactes et référence des fichiers précis. Un style concis élimine le superflu et commence par la réponse. Un style diplomatique équilibre honnêteté et tact.

Un agent combine ces primitives :

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

Cette composition crée un agent qui conçoit des systèmes (architecte), relie les connaissances entre domaines (architecte-connaissances), fixe une direction stratégique (stratège), pense en preuves et en données (analytique), et communique sans superflu (concis).

La puissance vient de l’explosion combinatoire. 27 identités multipliées par 11 états d’esprit multipliées par 10 styles donnent près de 3 000 personnalités d’agent possibles. Mais vous ne définissez que les combinaisons qui comptent pour votre travail.

Compétences : des modules de capacité réutilisables

Les compétences sont le savoir et les flux de travail que les agents peuvent invoquer. Elles suivent un système par paliers fondé sur la portée :

Palier	Nom	Portée	Exemple
K0	Fondations	Méthodologie universelle	Discipline test-first, achèvement fondé sur les preuves
K1	Identités	Flux de travail par rôle	Standards d’interface CLI, guide de performance
K2	Domaines	Savoir spécifique à un domaine	Schémas de migration de base de données, validation d’authentification
K3	Piles techniques	Spécifique à une technologie	Déploiement Cloudflare, opérations Supabase
K4	Projet	Cette base de code uniquement	Flux de travail et conventions spécifiques au projet

Les compétences sont chargées à la demande. Un agent voit les noms et descriptions des compétences au démarrage, mais le contenu complet d’une compétence ne se charge que lorsqu’elle est déclenchée. Cela garde le contexte léger tout en rendant des centaines de compétences découvrables.

Chaque compétence inclut :

Des conditions de déclenchement claires (« À utiliser lors de la migration de schémas de base de données »)
Des consignes étape par étape
Les outils autorisés pour le flux de travail
Des critères de succès et des chemins de récupération en cas d’échec

Les 466 compétences de notre registre couvrent tout, de l’isolation par worktree Git aux flux de travail de recherche web, en passant par la validation de la santé des déploiements.

Pourquoi l’orchestration compte

Les architectures à agent unique se heurtent vite à des murs :

Dilution du contexte. Une fenêtre de contexte de 200 000 tokens paraît vaste, jusqu’à ce que vous chargiez des schémas de base de données, de la documentation d’API, des fixtures de test et du savoir de domaine. Les spécialistes peuvent travailler avec un contexte ciblé.

Conflits d’instructions. Dire à un agent d’« être minutieux mais rapide » et de « tout vérifier sans sur-ingénierie » crée une tension. Les spécialistes résolvent cela en ayant une portée claire.

Profondeur d’expertise. Un agent généraliste sait un peu de tout. Un agent spécialiste, composé avec la bonne identité et les bonnes compétences, connaît son domaine en profondeur.

Orkestra met en œuvre une orchestration plate : un orchestrateur coordonne plusieurs spécialistes. Les spécialistes ne peuvent pas engendrer de sous-spécialistes. Cela empêche l’explosion de complexité tout en permettant le travail parallèle.

L’orchestrateur a accès à une capacité effective de 2,2 millions de tokens : sa propre fenêtre de 200 000 tokens, plus 10 sous-agents simultanés de 200 000 tokens chacun. Un travail qui épuiserait un agent unique tourne confortablement à travers la flotte.

Le pipeline de rendu

Les définitions d’agents vivent en YAML. Claude Code lit du Markdown. Orkestra comble cet écart avec un pipeline de rendu déterministe :

YAML Registries → Jinja Templates → .claude/agents/*.md

Les opérateurs modifient la source YAML, puis exécutent orkestra sync. Le Markdown rendu apparaît dans .claude/agents/. Claude Code récupère les changements.

Cette séparation sert des publics différents :

La source YAML inclut les métadonnées de cycle de vie, les tags, les règles de validation et les notes de dépréciation pour l’outillage
Le Markdown rendu inclut seulement ce dont le modèle a besoin : description, outils, compétences et consignes de comportement

Le pipeline compose identités, états d’esprit, styles et compétences en un seul prompt cohérent. Un agent architecte-analytique-concis reçoit un prompt système très différent d’un agent débogueur-sceptique-technique, même s’ils partagent certaines compétences sous-jacentes.

Savoir de domaine : le schéma en quatre fichiers

Chaque domaine de connaissance suit une structure cohérente :

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

Cette structure sert le chargement du contexte des agents. Un agent qui travaille sur l’authentification charge authentication/patterns.md pour s’orienter et authentication/anti-patterns.md pour éviter les pièges connus. Les fichiers sont dimensionnés pour un chargement de contexte efficace : assez ciblés pour être utiles, assez complets pour faire autorité.

Nous maintenons 21 domaines de premier niveau, incluant l’analytique, l’authentification, la data science, l’infrastructure, l’apprentissage automatique, la performance, la sécurité, et plus encore. Chaque domaine peut avoir des sous-domaines pour une granularité plus fine.

Valeurs : le système d’exploitation

Tous les agents partagent une couche de base de valeurs qui définit comment ils opèrent :

La simplicité d’abord. Utiliser la solution la plus simple qui fonctionne. N’ajouter de la complexité que lorsqu’elle est justifiée.

Corriger les causes racines. Ne jamais rafistoler autour des échecs. Si un pipeline échoue, déboguer le pipeline. Si un test échoue, corriger le code ou le test.

Fondé sur les preuves. Étiqueter les affirmations comme « vérifiées » (avec des benchmarks) ou « estimées » (avec des hypothèses). Un schéma détecté n’équivaut pas à un problème confirmé.

Économie de contexte. Les outils MCP coûtent 0,1 % du contexte. Les lectures de fichiers coûtent 2 % chacune. Appliquer l’expertise de domaine avant d’explorer le code.

Ces valeurs se propagent à chaque spécialiste via le pipeline de rendu. Un agent ne peut pas les contourner par composition.

CLI : le plan de contrôle

Orkestra est livré avec une CLI pour gérer l’écosystème d’agents :

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

La CLI est la source de vérité pour savoir quels agents existent, quelles compétences ils possèdent, et si le système est en bonne santé. Elle exécute une validation avant la synchronisation pour détecter les problèmes tôt.

Considérations open source

Nous avons construit Orkestra pour résoudre notre propre problème : coordonner des agents IA à grande échelle pour une base de code complexe. Les schémas que nous avons découverts ne sont pas spécifiques à notre domaine.

Le système de composition de personnage (identité + état d’esprit + style) s’applique à toute équipe qui définit des personnalités d’agent.

Le système de paliers de compétences (K0-K4) fournit un modèle mental pour organiser des capacités réutilisables par portée.

Le schéma de pipeline de rendu (source YAML + templates + artefacts générés) sépare les préoccupations entre l’outillage et la consommation par le modèle.

Le modèle d’orchestration plate (un coordinateur, de nombreux spécialistes) évite la complexité tout en permettant le parallélisme.

Qu’Orkestra devienne open source ou non dépend de la valeur de ces schémas pour d’autres équipes qui construisent avec Claude Code. Si vous vous heurtez aux murs que nous avons décrits, cette architecture pourrait vous aider.

Ce que nous avons appris

Construire Orkestra nous a appris que l’orchestration ne consiste pas à rendre les agents plus intelligents. Elle consiste à les rendre plus concentrés.

Un agent unique avec des instructions parfaites finit quand même par manquer de contexte. Un agent unique avec toutes les compétences hésite quand même sur les compétences à utiliser. Un agent unique qui essaie d’être tout produit des résultats médiocres partout.

Quarante spécialistes, chacun excellent dans son domaine, coordonnés par un orchestrateur qui sait quand déléguer : voilà comment nous livrons.

Les chiffres comptent moins que l’architecture. Vous pourriez avoir besoin de cinq agents, ou de cinquante. Le principe demeure : la composition plutôt que la capacité brute, la spécialisation plutôt que la généralisation, la coordination plutôt que l’héroïsme individuel.

Orkestra alimente l’écosystème d’agents derrière Maguyva, notre plateforme d’intelligence du code. Vous voulez en savoir plus ? Contactez l’équipe.