Une source de vérité par rôle : le piège silencieux des systèmes agentiques

Dans l'article précédent, j'ai décortiqué sept principes de conception extraits du leak de Claude Code. Le deuxième principe, "le prompt est l'architecture", est celui que je vois le plus mal appliqué en pratique. Pas parce que les gens l'ignorent, mais parce qu'ils le comprennent partiellement, et cette compréhension partielle crée un piège que je vais décrire ici.

Ce piège a un nom : la double source de vérité. Il apparaît dès qu'on commence à structurer sérieusement un système d'agents, et il produit des symptômes déroutants : l'agent se comporte correctement quatre-vingt-dix pour cent du temps, puis déraille subitement sans raison visible. Les utilisateurs parlent alors d'hallucinations, d'instabilité, de "l'IA qui fait n'importe quoi". Dans mon expérience, ce n'est presque jamais ça. C'est une contradiction interne que le système a chargée sans le savoir.

Le symptôme

Voici une situation que j'ai vu se répéter plusieurs fois. Une personne me pose la question suivante :

J'ai créé un sous-dossier dédié pour mon agent Code Reviewer, avec un fichier descriptif, des exemples et des règles. Mais je viens de voir que ce même agent est déjà défini dans mon manifeste d'équipe à la racine du projet. Claude va utiliser lequel ?

La réponse qui semble évidente, c'est "le plus spécifique" ou "le plus récent". Les deux sont fausses. La bonne réponse est : les deux.

Quand vous interagissez avec un agent comme Claude Code, il explore votre dossier projet, identifie les fichiers pertinents (CLAUDE.md, fichiers markdown liés au sujet de la conversation, points d'entrée courants), et charge leur contenu dans son contexte. Si votre manifeste d'équipe liste vingt rôles dont le Code Reviewer, il le charge. Si votre sous-dossier code-reviewer/ contient un fichier descriptif, il le charge aussi. Les deux se retrouvent dans le contexte, au même moment.

Pourquoi ça déraille

Tant que les deux définitions disent la même chose, avec éventuellement un niveau de détail différent, tout va bien. Le manifeste introduit le rôle, le sous-dossier le précise. C'est même plutôt sain : une vue synthétique et une vue détaillée, cohérentes entre elles.

Le problème commence dès que les deux divergent. Et elles divergent toujours, tôt ou tard, parce que vous allez mettre à jour l'une sans penser à l'autre. Un ton qui évolue dans le sous-dossier, une règle qui change dans le manifeste, une mission reformulée à un seul endroit. La divergence est souvent subtile, parfois invisible à l'œil nu.

À partir de ce moment, le modèle a deux versions légèrement différentes du même rôle dans son contexte. Et là, son comportement dépend de plusieurs facteurs imprévisibles : l'ordre dans lequel les fichiers ont été chargés, leur longueur relative, leur position dans le contexte (les tokens récents ont plus de poids que les anciens), et le biais naturel du modèle à s'accrocher aux formulations les plus explicites. Le résultat est que vous ne pouvez plus prédire quelle version il va suivre. Parfois c'est l'une, parfois c'est l'autre, et dans les cas les plus désagréables, il tente de faire un mélange des deux qui ne correspond à aucune.

Les utilisateurs parlent alors d'instabilité du modèle. En réalité, le modèle est parfaitement stable. C'est le scaffold qui lui a donné deux vérités concurrentes à réconcilier, et qui ne lui a pas laissé de moyen de choisir. Ce n'est pas un problème d'IA, c'est un problème de conception de système.

La règle à retenir

Un rôle, une seule source de vérité. Pas deux. Pas "le manifeste pour l'intro et le sous-dossier pour les détails" si vous n'avez pas un mécanisme strict pour empêcher la divergence.

Cette règle a l'air évidente dite comme ça. En pratique, elle est violée dans la quasi-totalité des projets que j'ai vus, parce que les gens arrivent à l'agentique avec des réflexes de documentation classique où la duplication d'information est considérée comme normale (voire utile, pour le confort de lecture).

Dans un système agentique, la duplication n'est pas normale, elle est toxique. Le modèle ne "lit pas en diagonale" comme un humain qui sauterait la redite. Il charge tout, il pondère tout, et il vous rendra la pondération qu'il aura faite, laquelle dépend de mille détails que vous ne contrôlez pas.

Arbitrer entre manifeste et dossier dédié

Concrètement, vous avez deux options pour chaque rôle :

Option 1 : une fiche dans le manifeste, pas de dossier dédié.

Si le rôle tient en une page (mission, ton, règles principales, exemples concis), la fiche dans le manifeste suffit. Pas besoin de dossier. Vous gagnez en simplicité et en cohérence.

agents/
  MANIFEST.md         # 20 rôles, une fiche par rôle, ~1 page chacune

Option 2 : un dossier dédié, pas de fiche dans le manifeste.

Si le rôle mérite vraiment un développement (plusieurs documents, des exemples longs, des règles nuancées, des playbooks), vous lui donnez son dossier. Mais dans ce cas, dans le manifeste, vous ne mettez qu'une seule ligne qui renvoie vers le dossier, sans redéfinir le rôle.

agents/
  MANIFEST.md         # 20 lignes, une ligne par rôle
  code-reviewer/
    ROLE.md           # mission, ton, critères de review
    examples/
      style-violations.md
      common-smells.md
    playbooks/
      security-review.md
      performance-review.md

Et dans MANIFEST.md, l'entrée du Code Reviewer ressemble à :

- **Code Reviewer** : voir [code-reviewer/ROLE.md](code-reviewer/ROLE.md)

Rien de plus. Pas de mission répétée, pas de résumé "au cas où". Une ligne, un pointeur, point.

Comment savoir lequel choisir

La question qui vient ensuite, c'est : "comment je sais si mon agent mérite un dossier ou si une fiche suffit ?"

La règle que j'applique personnellement est simple : si vous pouvez tout écrire en une seule page sans vous censurer, le dossier est du sur-engineering. Vous allez créer cinq fichiers pour ranger ce qui tenait sur un seul écran, et chacun de ces fichiers sera une source potentielle de divergence future.

À l'inverse, si vous constatez que votre fiche fait déjà trois pages, qu'elle mélange des règles générales et des playbooks spécifiques, qu'elle accumule des exemples au point de devenir difficile à relire, c'est le signal qu'il faut éclater en dossier. Mais à ce moment-là, la fiche disparaît complètement du manifeste. Elle ne se contente pas d'être "résumée" à la racine. Elle est remplacée par un pointeur.

Ce principe est exactement le même que dans Claude Code avec la distinction entre MEMORY.md (l'index, une ligne par entrée, toujours chargé en contexte) et les topic files (le détail, chargé à la demande). L'index pointe, il ne duplique pas. C'est une convergence architecturale qui n'est pas un hasard : c'est la seule façon de garder un système agentique prévisible quand il grandit.

Le lien avec le principe 2

Dans l'article parent, j'ai écrit que "le prompt est l'architecture". Ce que je viens de décrire en est une conséquence directe. Si le prompt est l'architecture, alors les règles de bonne architecture s'y appliquent, et en particulier le principe DRY (don't repeat yourself). En architecture logicielle, quand vous dupliquez une information dans deux endroits du code, tout le monde sait que c'est une dette qui se paiera. Dans le prompt d'un agent, c'est exactement pareil, sauf que le coût se paie en comportement imprévisible plutôt qu'en bugs compilateur.

La différence avec le code classique, c'est que vous n'avez pas de linter qui vous signale la duplication. Il n'y a pas d'outil qui vous dit "attention, le rôle Code Reviewer est défini dans deux fichiers". Vous devez maintenir cette discipline vous-même, par convention, au moment où vous concevez l'arborescence et à chaque fois que vous la modifiez.

Ce que Claude Code fait déjà

Le leak de Claude Code confirme cette approche. Le système mémoire à trois couches (index, topic files, transcripts) repose entièrement sur la règle "l'index pointe, il ne duplique pas". MEMORY.md est limité à 200 lignes, et chaque entrée doit faire environ 150 caractères maximum. Ce n'est pas une contrainte esthétique, c'est une contrainte architecturale : si l'index commence à contenir du vrai contenu plutôt que des pointeurs, il entre en concurrence avec les topic files, et le problème de double source de vérité réapparaît immédiatement.

Le sous-agent de consolidation autoDream a d'ailleurs dans son prompt une directive explicite de "supprimer les contradictions" au moment de fusionner les observations. Anthropic a manifestement rencontré ce problème et l'a traité au niveau du design système, pas au niveau du modèle. C'est cohérent avec le principe 1 de l'article parent : le scaffold compte plus que le modèle. Une contradiction dans les sources, aucun modèle ne la résout proprement. Il faut la prévenir en amont.

Ce que j'applique pour mes propres projets

Dans mes propres dossiers d'agents, j'ai fini par adopter trois règles concrètes qui évitent le piège :

1. Un seul fichier fait autorité pour un rôle donné, et je le sais au moment où je crée le rôle. Je ne me laisse pas l'option de "voir plus tard si je fais un dossier".

2. Le manifeste est un index, pas une documentation. S'il contient quoi que ce soit d'autre que des pointeurs et des lignes de synthèse sans règles exécutables, je sais que j'ai déjà un problème latent.

3. Quand je migre un rôle d'une fiche vers un dossier, je supprime immédiatement la fiche du manifeste au moment de la création du dossier. Dans la même opération. Pas plus tard. Pas "quand je serai sûr que le dossier est complet". La fiche et le dossier ne coexistent jamais, même pendant cinq minutes.

Ces trois règles sont ennuyeuses à appliquer au début. Elles deviennent naturelles au bout de quelques projets, et elles éliminent toute une classe de comportements erratiques qui étaient auparavant mis sur le dos de "l'instabilité des modèles".

Pour aller plus loin

Le prochain article de cette série traite d'une autre conséquence directe du principe 2 : comment structurer le contexte pour qu'il reste efficace et économique. La discipline architecturale dont je parle ici trouve son prolongement naturel dans la gestion fine des fichiers chargés à chaque session.

Et si vous voulez voir ces principes appliqués à un moteur d'inférence plutôt qu'à un système d'agents, herbert-rs adopte la même philosophie : une source de vérité par composant, pas de duplication cachée, et une architecture où chaque pièce sait exactement de quoi elle est responsable. Les domaines changent, les principes restent.

Des questions sur cet article ou votre propre projet ? Réserver une consultation