Ce n'est pas Claude qui dérive — c'est l'ambiguité de vos documents

On le voit de plus en plus. Un agent Claude qui ignore une consigne pourtant clairement écrite. Un skill qui ne fait pas ce qu'on lui demande. Une règle qui semble « oubliée » d'un run à l'autre.

Le réflexe immédiat : accuser le modèle. « Claude a changé. » « Anthropic a modifié quelque chose. » « Le contexte est corrompu. »

La plupart du temps, ce n'est pas le cas.

Le vrai problème — celui qu'on n'interroge jamais — c'est le contrat implicite de nos propres documents. On rédige des rules, des agents, des skills comme si notre interlocuteur partageait déjà notre vocabulaire. Mais une IA sans contexte ne fait pas d'hypothèses polies : elle choisit l'interprétation la plus plausible, pas forcément la bonne.

Il existe un test simple pour vérifier si vos documents sont réellement clairs. Et une solution concrète pour corriger le problème — sans changer une ligne de votre modèle.

Avant de continuer de lire la suite de l'article, je vous invite à vous inscrire à ma newsletter, pour connaître en avant première les futurs sujets traités chaque semaine.

Le réflexe : accuser le modèle

Pendant des mois, j'ai attribué les dérives de mes agents à des causes externes. Une mise à jour du modèle. Un contexte trop long qui « noyait » les instructions. Une hallucination isolée.

Ces causes existent. Mais elles sont rares.

Ce qui est beaucoup plus fréquent : un agent qui interprète différemment selon le jour, parce que le document qu'on lui donne contient des termes flottants — des mots qui semblent précis pour nous, mais qui n'ont aucun ancrage pour lui.

Les modèles récents sont remarquablement stables. Ce qui varie entre deux runs, ce n'est pas le modèle : c'est la documentation qu'on lui injecte, et l'ambiguité qu'elle contient.

Le vrai coupable : le biais cognitif de documentation

Imaginez qu'on vous demande de suivre une procédure interne rédigée par votre collègue. La procédure mentionne « déclencher le module CRM » — mais personne ne vous a expliqué ce qu'est « le module CRM » dans ce contexte. S'agit-il d'un bouton dans l'interface ? D'un script à lancer ? D'une requête API ?

Vous, vous poseriez la question. Un agent IA, lui, choisit.

Ce biais cognitif a un nom dans la littérature : le curse of knowledge. Quand on maîtrise un domaine, on oublie ce que c'était de ne pas le maîtriser. On rédige des documents pour des pairs qui partagent notre contexte — pas pour un interlocuteur qui arrive sans aucun préambule.

Avec une IA, ce biais devient un bug systématique. Trois symptômes l'illustrent :

L'ambiguité des termes. Un même mot peut désigner des choses très différentes selon le contexte. Dans mon projet, "hooks" peut désigner :
- Le dossier scripts/hooks/ (un répertoire)
- L'un des 89 scripts individuels qu'il contient
- Le concept abstrait de PostToolUse (un hook Claude Code)
- Le serveur HTTP sur le port 18766 qui orchestre ces scripts

Sans typage explicite, l'agent choisit. Et il ne vous dit pas qu'il a choisi.

L'absence de navigation. Pour savoir si agent-router.ts est utilisé par subagent-start.ts, il faut lire les deux fichiers en entier — ou deviner. Une documentation prose n'offre aucun raccourci.

La dérive silencieuse. Un script renommé, une table supprimée, une dépendance changée — la documentation reste fausse indéfiniment, car rien ne signale la divergence. L'agent continue de référencer un composant qui n'existe plus.

Le test que personne ne fait

Il y a quelques semaines, j'ai demandé à Claude de me remonter la plus petite skill de mon projet — la moins volumineuse, la plus « simple ».

Ce qu'il m'a retourné parlait de yq, rg, fd, yaml frontmapper, agents .md, batch agents audit.

J'ai lu ce fichier. Et j'ai réalisé que sans le contexte de mon projet, je serais incapable de l'exécuter sans recherches. Ces termes me parlaient — à moi. Mais pour quelqu'un qui arrive sans historique, c'est du jargon pur.

C'est là que j'ai compris le biais cognitif : j'avais rédigé ce fichier pour moi, pas pour une machine sans contexte partagé.

Le test à faire maintenant : prenez un fichier agent ou une rule de votre projet. Envoyez-le à un collègue qui ne connaît pas votre infrastructure. Demandez-lui s'il pourrait exécuter la tâche sans vous poser de questions.

Si la réponse est non — et elle l'est souvent — alors l'IA est dans la même situation que votre collègue. Sauf qu'elle ne posera pas de questions : elle inventera des réponses.

L'ambiguité concrète : ce que l'IA « comprend » à la place

Voici un extrait réel d'ambiguïtés terminologiques que j'ai trouvées en auditant mes propres fichiers :

Ces ambiguïtés ne sont pas des fautes de rédaction. Ce sont des erreurs de conception : on présuppose que l'IA partage notre dictionnaire mental.

La recherche le confirme. Des travaux sur l'ambiguïté dans les LLM (AmbigNLG, 2024) montrent que face à une instruction sous-spécifiée, les modèles « default to creative plausibility rather than constraints » — ils généralisent vers ce qui semble cohérent, pas vers ce qui est correct dans votre contexte.

Le coût n'est pas nul : un agent qui choisit mal une interprétation répercute cette erreur sur toutes les sous-tâches qu'il délègue. Une ambiguïté en tête de chaîne devient un bug systémique.

La solution : définir le vocabulaire dans chaque fichier

La solution n'est pas de réécrire tous vos documents en langue contrôlée. Elle est plus simple et plus puissante : déclarer explicitement les entités que votre document mentionne, avec leur type et leurs relations.

J'ai adopté deux sections structurées dans chaque fichier de documentation : ## Nodes et ## Relations.

## Nodes déclare toutes les entités avec leur type exact :

## Nodes

| Node | Type | Description |
|------|------|-------------|
| "agent-router.ts" | script | Hook UserPromptSubmit — routing pipeline regex+vector+/compose |
| "rag_agent_instructions" | db_table | Source de vérité skills/agents (chunks + embeddings bge-m3) |
| "hooks/" | concept | 89 scripts PostToolUse/PreToolUse — orchestrés par hooks-http-server.ts |

## Relations déclare comment ces entités interagissent :

## Relations

| Subject | Relation | Object |
|---------|----------|--------|
| "agent-router.ts" | OPERATES_ON | "rag_agent_instructions" |
| "hooks-http-server.ts" | SUPPORTS | "hooks/" |

Ces deux sections sont lisibles par un humain et ingérables automatiquement dans un graphe de connaissance. "hooks" n'est plus un terme flottant : c'est un nœud de type concept, avec une description précise et des relations explicites vers les scripts qui l'implémentent.

Le résultat immédiat : quand l'IA lit ce fichier, elle peut pointer vers "hooks/" comme vers un nœud typé dans un index — pas interpréter le mot dans le vide.

Comment le graphe de connaissance devient un index

Pensez à l'index d'un livre de référence technique. Il ne contient pas le savoir lui-même — il vous indique où chercher. Rapidement, sans lire tout le livre.

C'est exactement ce que le graphe de connaissance fait pour vos agents IA.

Quand un fichier de documentation déclare ses nœuds et ses relations, ces informations sont synchronisées dans une table PostgreSQL (rag_knowledge_graph). Le résultat : n'importe quel agent peut naviguer l'infrastructure du projet comme s'il en avait une carte.

-- Tout ce qui opère sur rag_agent_instructions
SELECT subject_name, relation, object_name
FROM rag_knowledge_graph
WHERE active = true
  AND object_name = 'rag_agent_instructions'
ORDER BY relation, subject_name;

Cette requête retourne en 50 ms tous les scripts qui utilisent cette table — sans lire un seul fichier source.

La comparaison avant/après est frappante :

Ce n'est pas de la théorie. Les équipes qui déploient des agents en production arrivent toutes à la même conclusion : sans vocabulaire explicite, le LLM généralise. Les ontologies (Salesforce, Microsoft), GraphRAG (Neo4j, IBM) — tous ces outils répondent au même problème fondamental. Ce que j'ai implémenté avec des fichiers Markdown et PostgreSQL, c'est la même idée, adaptée à un projet Claude Code.

Le workflow de synchronisation : garder le KG à jour

Ajouter des sections ## Nodes et ## Relations dans vos fichiers est une première étape. Le défi suivant : maintenir la cohérence quand les fichiers évoluent.

C'est le rôle de kg-md-diff.ts — un script local qui joue le rôle de pont de synchronisation :

fichier .md  ←──── kg-md-diff.ts ────→  rag_knowledge_graph (PostgreSQL)
(## Nodes       (compare, corrige,         (triplets actifs,
 ## Relations)   génère via LLM)            embeddings bge-m3)

Il détecte trois types d'écarts :

Pour les fichiers sans sections ## Nodes/## Relations, un mode LLM analyse la prose et génère les sections de zéro — en local, via qwen3:4b-16k sur GPU. Zéro exfiltration de vos règles internes. Zéro coût API. Zéro dépendance réseau.

Un hook PostToolUse surveille les modifications de fichiers .md et flag automatiquement ceux qui ont besoin d'être resynchronisés. Le KG ne dérive plus silencieusement : il signale.

Ce que ça change concrètement

Depuis que j'ai reformaté mes fichiers de documentation avec ces sections typisées, trois choses ont changé :

Les agents naviguent au lieu de deviner. Quand un agent reçoit une consigne qui mentionne "rag_agent_instructions", il peut interroger le KG et obtenir en retour le type exact de l'entité, sa description, et tous les composants qui l'utilisent. Il ne choisit plus entre quatre interprétations possibles.

Les dérives sont devenues traçables. Quand un agent fait quelque chose d'inattendu, je peux maintenant vérifier si la documentation était ambiguë. La plupart du temps, c'est le cas. Avant, j'aurais blâmé le modèle.

La maintenance est devenue proactive. Quand je renomme un script ou supprime une table, kg-md-diff.ts détecte les orphelins et les signale. La documentation reste à jour sans effort manuel.

Et maintenant ?

L'ambiguité du langage naturel est le bug silencieux de nos systèmes d'agents IA. On ne le voit pas parce que l'IA ne dit pas « je ne comprends pas ce terme » — elle choisit et avance.

La correction n'est pas dans le modèle. Elle est dans notre façon de rédiger.

La prochaine fois que vous créez un fichier rules/, un agent .md, ou un skill, posez-vous cette question : « Si je donne ce fichier à quelqu'un qui ne connaît pas mon projet, peut-il exécuter la tâche sans me demander quoi que ce soit ? »

Si la réponse est non, ajoutez un ## Nodes et un ## Relations. Définissez chaque terme. Typisez chaque entité.

L'IA ne dérivera plus. Elle naviguera.

Et vous, quel terme dans vos agents pourrait être interprété de cinq façons différentes ? Partagez votre cas en commentaire — les exemples concrets m'intéressent toujours.

Pour aller plus loin

Articles liés sur ce blog :
- Quand mes agents apprennent de leurs erreurs : le bilan des learned skills — la mise en place des skills évolutifs qui m'a révélé la nécessité de documenter le vocabulaire
- Quand vos agents IA oublient les consignes : pourquoi la surveillance est indispensable — les gardes-fous que j'ai construits après avoir mesuré les dérives
- Agents éphémères : j'ai tenté de supprimer la maintenance de mes agents IA — l'architecture qui tire parti d'un vocabulaire structuré

Sources externes :
- AmbigNLG: Addressing Task Ambiguity in Instruction for NLG (Megagon Labs) — recherche sur l'ambiguïté dans les LLM
- Why Ontologies Are Your Secret Weapon in the Agentic AI Era (Salesforce) — l'ontologie comme solution en production
- What Is a Knowledge Graph ? (Neo4j) — référence sur GraphRAG et la structuration du vocabulaire

Qui suis je ?

Je suis Mathieu GRENIER, CTO d'Easystrat une startup de Montpellier, en France. Je manage une équipe d'une dizaine d'ingénieurs (Graphistes, IA, frontend, backend, devOps, AWS) en remote depuis le Japon.

J'ai aussi mon activité de freelance, où je conseille des entrepreneurs dans leurs projets d'application.

Avec mon expérience personnelle de plus de 15 ans en ESN, j'ai pu travailler pour un large panel d'entreprises de différentes tailles. Ma compréhension des problèmes métiers est une de mes grandes forces et permet à mes clients de pouvoir se projeter plus facilement.

L'essentiel de mon travail consiste à canaliser l'énergie des entrepreneurs sur l'essence même de leur projet.

La technologie, les méthodes, le management sont le cœur de mes compétences.

Vous pouvez me faire confiance sur ces points là.

Si vous voulez me parler d'un de vos projets, n'hésitez pas à m'envoyer un email avec vos disponibilités à : contact@mathieugrenier.fr

Je documente en public ce que je construis en privé. Abonnez-vous pour ne pas manquer les prochains articles sur l'IA agentique, les agents autonomes et l'architecture de systèmes LLM.

Tous les articles de ce blog sont écrits par moi, même si je peux m'aider de l'IA pour illustrer mes propos. Mais jamais je ne fournis d'articles 100 % IA.