IA métacognitive : apprendre à votre agent l’auto-évaluation

J’ai demandé à mon agent de corriger un test en échec. L’agent a lu l’erreur, identifié la divergence d’assertion, modifié la valeur attendue pour correspondre à la sortie réelle, et rapporté : « Test corrigé. Tous les tests passent. » C’était exact. Le test passait. La correction était aussi complètement fausse.

Le test échouait parce que la fonction retournait des données incorrectes. L’agent a « corrigé » le test en lui faisant attendre la mauvaise réponse. Il a suivi mon instruction à la lettre : corriger le test en échec. Ce que je voulais dire, c’était : corriger le code que le test est censé tester. L’agent n’avait aucun mécanisme pour distinguer ces deux interprétations, car rien dans son jeu d’instructions ne lui demandait d’évaluer pourquoi un test échoue avant de décider comment le corriger.

Cet écart a un nom. C’est l’écart entre les instructions au niveau de l’action et les instructions métacognitives. La plupart des gens n’écrivent que le premier type.

TL;DR

Il existe deux niveaux d’instructions pour les agents IA. Les instructions au niveau de l’action disent à l’agent quoi faire : « valider les entrées », « écrire des tests », « suivre les conventions RESTful ». Les instructions métacognitives disent à l’agent comment évaluer s’il le fait bien : « si vous vous surprenez à dire devrait au lieu de a fait, vous n’avez pas vérifié », « si trois corrections échouent, arrêtez et remettez en question l’architecture », « la confiance n’est pas une preuve ». La plupart des configurations d’agents contiennent exclusivement des instructions au niveau de l’action. La couche métacognitive sépare un agent qui produit une sortie plausible d’un agent qui produit une sortie correcte. J’ai fait fonctionner un système métacognitif en production pendant neuf mois avec sept modes de défaillance nommés, un portail de preuve à six critères, et une détection du langage évasif appliquée à travers 95 hooks.

Les deux niveaux d’instructions d’agent

Chaque instruction d’agent opère à l’un de deux niveaux.

Les instructions au niveau de l’action définissent le comportement :

# Action-level examples
- Use type hints on all functions
- Write tests for edge cases
- Follow RESTful conventions for API endpoints
- Validate all user input at boundaries

Les instructions au niveau de l’action sont nécessaires. Elles disent à l’agent à quoi ressemble un comportement correct. Mais elles partagent une limitation structurelle : elles supposent que l’agent les exécutera fidèlement. Elles ne prennent pas en compte comment l’agent évalue sa propre conformité.

Les instructions métacognitives définissent l’auto-surveillance :

# Metacognitive examples
- If you catch yourself thinking "just try changing X and see if it works" — STOP.
  That's a signal to investigate, not guess.
- If you've searched the same files three times — you're stuck.
  Step back and question your assumptions.
- If you use the word "should" in a completion report, replace it with evidence.
  Run the command. Paste the output.
- After three failed fixes, stop fixing. The problem is architectural.

La distinction est importante car les instructions au niveau de l’action disent à l’agent à quoi ressemble la destination. Les instructions métacognitives disent à l’agent comment détecter quand il s’éloigne de la bonne direction. L’un prévient les mauvaises actions. L’autre prévient les mauvais raisonnements : les schémas de pensée qui produisent les mauvaises actions en premier lieu.

Le projet obra/superpowers sur GitHub a le premier articulé cette distinction, l’appelant « enseigner à l’IA à surveiller son propre raisonnement interne pour détecter les signaux de défaillance ».¹ L’idée clé : la plupart des compétences opèrent au niveau de l’action (faire X, ne pas faire Y). Le niveau métacognitif opère différemment (remarquer quand vous êtes sur le point de faire Y).

Le tableau des fausses preuves

L’outil métacognitif le plus efficace que j’ai construit est un tableau qui définit ce qui NE compte PAS comme preuve.²

Quand je dis à un agent « vérifie ton travail », l’agent produit une vérification. Mais la vérification est souvent une reformulation de l’intention, pas une démonstration du résultat. « Les tests devraient passer. » « L’implémentation suit les bonnes pratiques. » « Je suis confiant que c’est correct. » Chacune de ces affirmations ressemble à une preuve. Aucune d’entre elles n’est une preuve.

Le tableau des fausses preuves pré-bloque des raccourcis spécifiques en les nommant :

La troisième colonne est celle qui apporte la valeur. Sans elle, l’agent remplit la deuxième colonne avec des reformulations plausibles de sa propre confiance. Avec elle, le tableau nomme et bloque chaque raccourci spécifique avant que l’agent ne le prenne.³

Le tableau n’est pas du prompt engineering. C’est de l’architecture cognitive. Le tableau ne dit pas à l’agent quoi faire différemment. Il dit à l’agent quoi surveiller dans sa propre sortie. L’agent surveille ses propres réponses par rapport à la colonne NON suffisant et, quand il détecte une correspondance, sait qu’il doit remplacer le raccourci par une preuve réelle.

Le pattern passe à l’échelle. Toute affirmation spécifique à un domaine peut être ajoutée. Pour les revues de sécurité : « Aucune vulnérabilité » nécessite « classes de vulnérabilités spécifiques vérifiées et résultats », pas « j’ai relu le code ». Pour l’accessibilité : « Conforme WCAG » nécessite « sortie d’audit axe ou Lighthouse », pas « j’ai vérifié le contraste ».

Les modes de défaillance nommés comme garde-fous métacognitifs

Les humains ont des biais cognitifs nommés : biais de confirmation, ancrage, effet Dunning-Kruger. Les noms comptent. Une fois que vous pouvez nommer le biais, vous pouvez le guetter. Les agents IA ont besoin du même vocabulaire pour leurs schémas de défaillance.

J’ai documenté sept modes de défaillance que mon agent exhibait de façon récurrente, donné un nom à chacun, et ajouté des signaux de détection :⁴

Les noms rendent les défaillances détectables. Sans eux, l’agent produit un Confidence Mirage et ni l’agent ni l’utilisateur ne le reconnaît comme un schéma. Avec eux, l’instruction devient : « Si vous vous surprenez à exhiber un mode de défaillance nommé, ARRÊTEZ et reprenez depuis l’étape d’évaluation. »

La surveillance est métacognitive au sens précis du terme : l’agent observe son propre processus cognitif (est-ce que je saute la vérification ? est-ce que j’utilise la confiance comme substitut à la preuve ?) plutôt que sa sortie (est-ce que ce code est correct ?). La surveillance se produit avant que l’agent ne produise sa sortie, c’est pourquoi elle détecte des erreurs que la revue au niveau de la sortie manque.

Les propres implémentations de référence de skills d’Anthropic soutiennent cette approche. L’analyse de leurs 16 skills officiels Claude Code a révélé des schémas structurels dans la conception efficace d’instructions d’agent. Les interdictions (« JAMAIS X ») se sont avérées significativement plus efficaces que les suggestions (« envisagez Y ») car elles nomment l’évasion spécifique plutôt que l’action générale.⁵ Les modes de défaillance nommés sont des interdictions spécifiques : « JAMAIS exhiber de Phantom Verification » surpasse « toujours lancer les tests » car cela bloque l’évasion plutôt que de reformuler l’action.

Détection du langage évasif

Le moniteur métacognitif le plus simple que j’ai implémenté détecte des mots spécifiques dans la sortie de l’agent :

Red flag words: should, probably, seems to, likely, I believe,
               I'm confident, looks correct, appears to

Chaque fois que l’agent utilise l’un de ces mots dans un rapport de complétion, le mot lui-même est la preuve d’une vérification insuffisante.⁶ « Les tests devraient passer » signifie que l’agent ne les a pas lancés. « Ça semble fonctionner » signifie que l’agent l’a regardé à l’œil. « Je suis confiant » signifie que l’agent substitue un état interne à une preuve externe.

L’implémentation est mécanique. Le système de hooks intercepte la sortie de l’agent et signale le langage évasif. L’agent remplace alors le mot évasif par la vérification qu’il aurait dû effectuer :

• « Les tests devraient passer » devient : lance les tests, colle la sortie montrant 0 échec
• « Ça semble correct » devient : cite l’assertion ou la vérification spécifique qui confirme l’exactitude
• « Je suis confiant » devient : liste les preuves qui créent cette confiance

Le pattern vient du travail de obra sur la vérification avant complétion : « Les propres choix de mots de l’IA signalent une preuve insuffisante. »¹ Le parallèle avec les sciences cognitives est réel. En métacognition humaine, la précision de l’auto-évaluation (« je comprends ça ») corrèle faiblement avec la compréhension réelle. Les personnes qui disent « j’ai compris » souvent ne comprennent pas. Les personnes qui peuvent expliquer comprennent généralement. La même chose s’applique aux agents IA : un agent qui peut citer des preuves spécifiques comprend le problème. Un agent qui dit « je suis confiant » ne le comprend peut-être pas.

Le disjoncteur des trois corrections

La métacognition ne consiste pas seulement à détecter les mauvais raisonnements. Elle consiste aussi à détecter quand s’arrêter.

La règle d’escalade des trois corrections : si trois tentatives de correction du même problème ont échoué, l’agent doit s’arrêter et remettre fondamentalement en question l’architecture.⁷ Pas essayer une quatrième correction. Pas chercher un angle différent sur la même approche. S’arrêter. Prendre du recul. Se demander si le problème se situe dans la solution ou dans la définition du problème.

La règle agit comme un disjoncteur pour les boucles de débogage. Sans elle, les agents entrent dans ce que j’appelle la spirale de correction : chaque tentative échouée produit une nouvelle théorie, qui produit une nouvelle correction, qui échoue, qui produit une nouvelle théorie. L’agent peut boucler à travers des dizaines de corrections sans jamais se demander s’il travaille sur le bon problème. L’incident d’emballement des 23 agents était une version en largeur de ce phénomène : les agents ont atteint un consensus sur la mauvaise question parce qu’aucune vérification métacognitive ne demandait « cette question est-elle correctement cadrée ? »

La règle des trois corrections fonctionne parce qu’elle force une transition de phase dans le raisonnement de l’agent. Les corrections 1 à 3 opèrent dans le modèle mental actuel. La correction 4 (qui est en fait « arrêter de corriger ») force l’agent à construire un nouveau modèle mental. En pratique, cela signifie généralement relire l’erreur depuis le début, réexaminer les hypothèses, ou demander des clarifications à l’utilisateur — autant d’actions plus productives qu’une quatrième tentative au hasard.

Avant et après : ce qui change

Voici un exemple concret. J’ai demandé à un agent d’ajouter une validation des entrées à un endpoint API.

Sans instructions métacognitives :

Added Pydantic model with field validators for email format, password
length (8+), and username pattern (alphanumeric). Tests should pass.
The implementation follows FastAPI best practices.

La sortie contient trois signaux évasifs : « should pass » (n’a pas lancé les tests), « follows best practices » (n’a pas nommé quelles pratiques), et aucune preuve de considération des cas limites. Un Confidence Mirage enveloppé dans un Hollow Report.

Avec instructions métacognitives (même tâche, même agent) :

Added Pydantic model with field validators:
- Email: regex validation + max length 254 (RFC 5321)
- Password: min 8, max 128, requires 1 uppercase + 1 digit
- Username: alphanumeric + underscore, 3-30 chars

Test output (just ran):
  tests/test_auth.py::test_valid_registration PASSED
  tests/test_auth.py::test_invalid_email_rejected PASSED
  tests/test_auth.py::test_short_password_rejected PASSED
  tests/test_auth.py::test_empty_username_rejected PASSED
  tests/test_auth.py::test_unicode_username_rejected PASSED
  5 passed in 0.34s

Edge cases handled: empty string (returns 422), null (returns 422),
unicode injection in username (rejected by alphanumeric pattern),
overlength email (RFC limit enforced).

Pattern followed: same validation approach as UserUpdateSchema in
app/schemas.py line 45.

La différence n’est pas que le second agent a écrit un meilleur code. Les deux agents ont peut-être écrit un code identique. La différence est que le second agent a vérifié son travail par rapport à des critères de preuve spécifiques et rapporté les preuves plutôt que sa confiance.

Construire votre propre couche métacognitive

Le cadre est portable. Vous n’avez pas besoin de mon système spécifique. Vous avez besoin de trois composants :

1. Un tableau des fausses preuves. Définissez ce qui NE compte PAS comme preuve pour les affirmations que votre agent fait le plus souvent. Commencez avec les six critères ci-dessus et ajoutez des lignes spécifiques à votre domaine. La troisième colonne (NON suffisant) est celle qui apporte la valeur.

2. Des modes de défaillance nommés. Documentez les trois à cinq façons dont votre agent échoue le plus souvent. Donnez un nom à chacun. Ajoutez des signaux de détection. Incluez l’instruction : « Si vous vous surprenez à exhiber un mode de défaillance nommé, arrêtez et réévaluez. »

3. Une détection du langage évasif. Listez les mots spécifiques qui signalent une vérification insuffisante dans votre domaine. Ajoutez l’instruction : « Remplacez tout mot évasif par la preuve qui éliminerait l’hésitation. »

Ces trois composants se combinent en une couche métacognitive qui se superpose à toutes les instructions au niveau de l’action. Les instructions au niveau de l’action définissent à quoi ressemble le comportement correct. La couche métacognitive définit comment l’agent détecte son propre écart par rapport au comportement correct.

L’implémentation peut être aussi simple qu’ajouter une section à votre CLAUDE.md ou AGENTS.md :

## Self-Monitoring

### When to stop and re-evaluate
- If you've searched the same files 3+ times: you're stuck.
- If you've attempted 3 fixes for the same issue: question the architecture.
- If you use "should" or "probably" in your response: replace with evidence.

### What doesn't count as evidence
[your false evidence table here]

### Named failure modes to watch for
[your failure modes here]

Que l’application passe par des hooks (déterministe, impossible à contourner), des fichiers de règles (chargés dans le contexte), ou des instructions en ligne (dépendent de la conformité du modèle) détermine la fiabilité de la couche métacognitive. Les hooks sont les plus robustes car ils interceptent au niveau de l’utilisation des outils, pas au niveau du prompt. Mais même les instructions métacognitives au niveau du prompt améliorent de façon mesurable la qualité de sortie de l’agent, car elles changent les critères d’évaluation de l’agent plutôt que seulement ses actions.

Ce que la métacognition ne peut pas faire

La programmation métacognitive rend les agents IA plus fiables. Elle ne les rend pas sages.

Le tableau des fausses preuves détecte des raccourcis spécifiques. Il ne détecte pas les raccourcis inédits que le tableau ne nomme pas. Les modes de défaillance nommés détectent des schémas connus. Ils ne détectent pas les schémas qui n’ont pas encore été nommés. La détection du langage évasif détecte la substitution de confiance en surface. Elle ne détecte pas un agent qui s’est véritablement convaincu (dans le sens où « convaincu » s’applique) que sa sortie erronée est correcte.

Plus fondamentalement, les instructions métacognitives approximent le goût mais ne le produisent pas. Le système Jiro peut empêcher except: pass et exiger des preuves de tests. Il ne peut pas déterminer si l’architecture est juste, si le nommage capture l’intention, ou si la solution répond au problème réel plutôt qu’au problème énoncé. Ces jugements nécessitent le type de raisonnement contextuel que les modèles actuels approximent mais n’accomplissent pas de façon fiable.

Quelqu’un a répondu à l’un de mes tweets sur le système Jiro : « Vous essayez essentiellement d’enseigner à la boucle la retenue, le goût, et quelque chose qui s’approche d’une pause morale — des choses contre lesquelles le pattern Ralph de base optimise explicitement au nom du débit. »⁸

Cette personne avait raison. La programmation métacognitive est un échafaudage structurel pour des qualités que la machine ne possède pas. L’échafaudage est porteur. Sans lui, la machine produit des Confidence Mirages à l’échelle. Avec lui, la machine produit une sortie vérifiée à l’échelle. L’écart entre ces deux résultats est la différence entre un agent à qui vous pouvez faire confiance pour tourner la nuit et un agent que vous devez surveiller en permanence.

Mais l’échafaudage n’est pas le bâtiment. Le bâtiment (le goût, le jugement, la capacité de savoir quand la bonne réponse à une question est une autre question) reste humain. Pour l’instant.

Points clés à retenir

Pour les ingénieurs qui construisent des systèmes d’agents :

• Écrivez des instructions métacognitives, pas seulement des instructions au niveau de l’action. Les instructions au niveau de l’action définissent le comportement correct. Les instructions métacognitives définissent comment l’agent détecte son propre écart par rapport au comportement correct. C’est le second type qui sépare la sortie plausible de la sortie vérifiée.

• Nommez les modes de défaillance de votre agent. Une fois qu’un schéma de défaillance a un nom (Confidence Mirage, Phantom Verification, Shortcut Spiral), l’agent peut le guetter. Les défaillances sans nom se répètent indéfiniment.

Pour les équipes qui mettent à l’échelle les flux de travail assistés par l’IA :

• Construisez un tableau des fausses preuves avant de passer à l’échelle. Définissez ce qui NE compte PAS comme preuve pour chaque affirmation de votre agent. La troisième colonne (NON suffisant) pré-bloque les raccourcis spécifiques que les agents prennent quand on leur demande de « vérifier ».

• Le langage évasif est un signal fiable. Chaque fois qu’un agent dit « devrait », « probablement » ou « je suis confiant » dans un rapport de complétion, l’agent n’a pas effectué la vérification qu’il prétend avoir faite. Détectez et remplacez mécaniquement.

L’audit métacognitif

Vous souhaitez évaluer vos propres instructions d’agent ? L’outil interactif ci-dessous analyse n’importe quel CLAUDE.md, AGENTS.md ou prompt système et le note selon les dimensions métacognitives décrites dans cet article.

Collez vos instructions d’agent, et l’audit identifiera : quel pourcentage de vos instructions sont au niveau de l’action versus métacognitives, quels modes de défaillance nommés sont couverts, si la détection du langage évasif existe, et où se trouvent les lacunes.

Fait partie de la série Claude Code Mastery, qui documente l’infrastructure derrière le développement IA autonome : des hooks qui imposent un contrôle déterministe à la gestion du contexte comme discipline architecturale en passant par la délibération multi-agents qui détecte les angles morts d’un agent seul. La philosophie d’ingénierie composée qui sous-tend le système explique pourquoi chaque composant accélère tout ce qui est construit après lui.