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 qu’elle corresponde à la sortie réelle, et rapporté : « Test corrigé. Tous les tests passent. » Il avait raison. Le test passait. Et la correction était 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 vérifie. 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. J’emploie « métacognitif » comme une analogie fonctionnelle, pas comme une affirmation de sciences cognitives : les LLM n’ont pas de processus internes de surveillance comme les humains. Ce qu’ils ont, c’est un comportement de suivi d’instructions qui peut être orienté vers l’auto-évaluation. Le framework fonctionne parce qu’il change les instructions que l’agent suit pendant la vérification, pas parce que l’agent développe une véritable conscience de soi. La plupart des gens n’écrivent que le premier type d’instruction.
La programmation métacognitive de l’IA consiste à donner aux agents IA des instructions d’auto-évaluation : il ne s’agit pas seulement de leur dire quoi faire, mais de leur apprendre à détecter quand ils partent dans la mauvaise direction. Les instructions au niveau de l’action définissent un comportement (« écrire des tests », « valider les entrées »). Les instructions métacognitives définissent une auto-surveillance (« si vous dites “devrait” au lieu de “a fait”, vous n’avez pas vérifié »). Cette seconde couche, mise en œuvre par des barrières de preuve, des modes de défaillance nommés et la détection du langage évasif, sépare les agents qui produisent une sortie plausible de ceux qui produisent une sortie correcte.
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-vous et remettez en question l’architecture », « la confiance n’est pas une preuve ». La plupart des configurations d’agent ne contiennent que 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. Je fais tourner depuis neuf mois en production un système métacognitif comprenant sept modes de défaillance nommés, une barrière de preuve à six critères et une détection du langage évasif, le tout appliqué par 95 hooks.
Les deux niveaux d’instructions d’agent
Toute instruction d’agent opère à l’un de deux niveaux.
Les instructions au niveau de l’action définissent un 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 indiquent à l’agent à quoi ressemble un comportement correct. Elles partagent toutefois une limite structurelle : elles supposent que l’agent les exécutera fidèlement. Elles ne tiennent pas compte de la façon dont l’agent évalue sa propre conformité.
Les instructions métacognitives définissent une 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 compte parce que les instructions au niveau de l’action disent à l’agent à quoi ressemble la destination. Les instructions métacognitives lui disent comment détecter qu’il part dans la mauvaise direction. Les unes empêchent les mauvaises actions. Les autres empêchent le mauvais raisonnement : les schémas de pensée qui sont à l’origine des mauvaises actions.
Le projet obra/superpowers sur GitHub explore ce territoire avec des skills qui apprennent aux agents à surveiller leur propre raisonnement pour y repérer des signaux de défaillance.1 L’idée clé : la plupart des skills opèrent au niveau de l’action (faites X, ne faites pas Y). Le niveau métacognitif fonctionne autrement (remarquez quand vous êtes sur le point de faire Y).
Le tableau des fausses preuves
L’outil métacognitif le plus efficace que j’aie construit est un tableau qui définit ce qui ne compte PAS comme une preuve.2
Quand je dis à un agent « vérifiez votre travail », l’agent produit une vérification. Mais cette vérification n’est souvent qu’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 certain que c’est correct. » Chacune de ces affirmations ressemble à une preuve. Aucune n’est une preuve.
Le tableau des fausses preuves bloque à l’avance des raccourcis précis en les nommant :
| Affirmation | Preuve requise | NON suffisant (fausse preuve) |
|---|---|---|
| « Les tests passent » | Sortie des tests collée, avec 0 échec | « Les tests devraient passer » ou « Je les ai lancés tout à l’heure » |
| « Suit les patterns » | Nommer le pattern ET le fichier où il existe | « J’ai suivi les bonnes pratiques » |
| « Solution la plus simple » | Nommer les alternatives rejetées et pourquoi | « C’est propre » |
| « Cas limites gérés » | Lister chaque cas limite et son traitement | « J’ai pris en compte les cas limites » |
| « Aucune régression » | Nommer les fichiers/fonctionnalités vérifiés | « Rien d’autre ne devrait être affecté » |
| « Résout le problème » | Énoncer le besoin de l’utilisateur et la façon dont la solution y répond | « Ça implémente la fonctionnalité » |
C’est dans la troisième colonne que réside la valeur. Sans elle, l’agent remplit la deuxième colonne de reformulations plausibles de sa propre confiance. Avec elle, le tableau nomme et bloque chaque raccourci précis avant que l’agent ne le prenne.3
Le tableau va au-delà du prompt engineering classique. Il crée un cadre d’auto-surveillance plutôt qu’une directive comportementale. Le tableau ne dit pas à l’agent quoi faire différemment. Il lui dit quoi guetter dans sa propre sortie. L’agent confronte ses propres réponses à la colonne NON suffisant et, lorsqu’il détecte une correspondance, sait qu’il doit remplacer le raccourci par une preuve réelle.
Le schéma passe à l’échelle. On peut y ajouter n’importe quelle affirmation propre à un domaine. Pour les revues de sécurité : « Aucune vulnérabilité » exige « les classes de vulnérabilités précises vérifiées et les constats », pas « J’ai relu le code ». Pour l’accessibilité : « Conforme WCAG » exige « la sortie d’un 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. Dès que vous pouvez nommer un 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 présentait de façon récurrente, donné un nom à chacun et ajouté des signaux de détection :4
| Mode de défaillance | À quoi il ressemble | Signal de détection |
|---|---|---|
| Shortcut Spiral | Sauter des étapes de vérification pour rendre compte plus vite | Rapport de complétion sans preuve pour chaque étape |
| Confidence Mirage | « Je suis confiant » à la place d’une vérification réelle | Langage évasif dans le rapport |
| Good-Enough Plateau | Du code qui fonctionne mais n’est ni propre, ni testé, ni documenté | Hésitation face aux questions de qualité |
| Tunnel Vision | Peaufiner une fonction en cassant le code adjacent | « Rien d’autre n’est affecté » sans vérification |
| Phantom Verification | Affirmer que les tests passent sans les avoir lancés maintenant | Preuve issue d’une session précédente |
| Deferred Debt | Laisser des TODO/FIXME/HACK dans le code commité | Tout commentaire de ce type dans le diff |
| Hollow Report | « Terminé » sans citer de détails précis | Rapport de complétion où manque la preuve d’un critère |
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 à présenter l’un des modes de défaillance nommés, ARRÊTEZ et reprenez à partir de l’étape Évaluer. »
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 (ce code est-il correct ?). La surveillance façonne la génération en tant que partie du raisonnement de l’agent, ce qui explique qu’elle attrape des erreurs que la revue au niveau de la sortie laisse passer.
Les propres implémentations de référence de skills d’Anthropic vont dans le sens de cette approche. L’analyse des skills officiels de Claude Code a révélé des schémas structurels dans la conception efficace d’instructions d’agent. Selon l’observation de l’auteur, les interdictions (« NEVER X ») se sont révélées plus efficaces que les suggestions (« consider Y »), car elles nomment l’esquive précise plutôt que l’action générale.5 Les modes de défaillance nommés sont des interdictions précises : « NEVER exhibit Phantom Verification » fonctionne mieux que « always run tests », parce que l’interdiction bloque l’esquive au lieu de reformuler l’action.
Détection du langage évasif
Le moniteur métacognitif le plus simple que j’aie mis en place détecte des mots précis 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 emploie l’un de ces mots dans un rapport de complétion, le mot lui-même est la preuve d’une vérification insuffisante.6 « Tests should pass » signifie que l’agent ne les a pas lancés. « It seems to work » signifie que l’agent a jeté un coup d’œil. « I’m confident » signifie que l’agent substitue un état interne à une preuve externe.
La mise en œuvre 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 :
- « Tests should pass » devient : lance les tests, colle la sortie montrant 0 échec
- « It looks correct » devient : cite l’assertion ou la vérification précise qui confirme l’exactitude
- « I’m confident » devient : liste les preuves qui fondent cette confiance
Le schéma vient du travail d’obra sur la vérification avant complétion.1 Le parallèle avec les sciences cognitives est bien établi : dans la métacognition humaine, l’exactitude de l’auto-évaluation (« je comprends ») est faiblement corrélée à la compréhension réelle.3 Les gens qui disent « j’ai compris » n’ont souvent pas compris. Ceux qui peuvent l’expliquer, en général, si. Il en va de même pour les agents IA : un agent capable de citer une preuve précise 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 un mauvais raisonnement. Elle consiste aussi à savoir 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.7 Ne pas tenter une quatrième correction. Ne pas chercher un autre angle sur la même approche. S’arrêter. Prendre du recul. Se demander si le problème se trouve dans la solution ou dans la définition du problème.
La règle sert de disjoncteur pour les boucles de débogage. Sans elle, les agents entrent dans ce que j’appelle la Fix Spiral : chaque tentative ratée produit une nouvelle théorie, qui produit une nouvelle correction, qui échoue, qui produit une nouvelle théorie. L’agent peut enchaîner des dizaines de corrections sans jamais se demander s’il travaille sur le bon problème. L’incident des 23 agents emballés en était une version en largeur : les agents sont parvenus à un consensus sur la mauvaise question, parce qu’aucune vérification métacognitive ne demandait « cette question est-elle correctement délimité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 à l’intérieur du modèle mental actuel. La correction 4 (qui consiste en réalité à « arrêter de corriger ») oblige 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 précisions à l’utilisateur, autant de démarches plus productives qu’une quatrième supposition.
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 d’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 » (les tests n’ont pas été lancés), « follows best practices » (sans préciser quelles pratiques) et aucune preuve que les cas limites aient été envisagés. Un Confidence Mirage emballé 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 ne tient pas à ce que le second agent aurait écrit un meilleur code. Les deux agents ont peut-être écrit un code identique. La différence, c’est que le second agent a vérifié son travail au regard de critères de preuve précis et a rapporté les preuves plutôt que sa confiance.
Construire votre propre couche métacognitive
Le framework est transposable. Vous n’avez pas besoin de mon système en particulier. Il vous faut trois composants :
1. Un tableau des fausses preuves. Définissez ce qui ne compte PAS comme preuve pour les affirmations que votre agent formule le plus souvent. Commencez par les six critères ci-dessus et ajoutez des lignes propres à votre domaine. C’est dans la troisième colonne (NON suffisant) que réside 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 à chacune. Ajoutez des signaux de détection. Incluez l’instruction : « Si vous vous surprenez à présenter l’un des modes de défaillance nommés, arrêtez-vous et réévaluez. »
3. La détection du langage évasif. Listez les mots précis qui, dans votre domaine, signalent une vérification insuffisante. Ajoutez l’instruction : « Remplacez tout mot évasif par la preuve qui rendrait la réserve inutile. »
Ces trois composants forment ensemble une couche métacognitive qui se superpose à n’importe quel ensemble d’instructions au niveau de l’action. Les instructions au niveau de l’action définissent à quoi ressemble un comportement correct. La couche métacognitive définit comment l’agent détecte qu’il s’en écarte.
La mise en œuvre peut se limiter à 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éterministes, impossibles à contourner), des fichiers de règles (chargés dans le contexte) ou des instructions en ligne (qui 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, et non au niveau du prompt. Même au niveau du prompt, cependant, les instructions métacognitives améliorent de façon mesurable la qualité de la sortie de l’agent, car elles changent ses critères d’évaluation et pas seulement ses actions.
Exercice : auditez vos trois dernières interactions avec un agent. Copiez les rapports de complétion. Surlignez chaque occurrence de « should », « probably » ou « I’m confident ». Pour chaque mot surligné, écrivez la preuve précise qui aurait dû remplacer la réserve. Si la preuve existe mais que l’agent ne l’a pas citée, l’agent a besoin d’une détection du langage évasif. Si la preuve n’existe pas, l’agent a purement et simplement sauté la vérification : il a besoin du tableau des fausses preuves.
L’ordre compte : commencez par le tableau des fausses preuves (le plus fort impact, le plus simple à mettre en place), ajoutez les modes de défaillance nommés une fois que vous avez observé des schémas récurrents, puis la détection du langage évasif comme contrôle mécanique. Chaque couche attrape des erreurs que la précédente laisse passer. Ensemble, elles forment une boucle de rétroaction : l’agent surveille sa propre sortie, détecte les schémas de défaillance connus et se corrige avant d’annoncer qu’il a terminé.
Configuration minimale reproductible
Vous pouvez tester le schéma métacognitif de base en cinq minutes. Créez un fichier nommé .claude/CLAUDE.md (ou complétez celui que vous avez déjà) avec ce contenu :
## Evidence Gate
Before reporting any task as complete, provide evidence for ALL criteria:
| Claim | Required Evidence | NOT Sufficient |
|-------|------------------|----------------|
| "Tests pass" | Paste test output showing 0 failures | "Tests should pass" |
| "Follows patterns" | Name the pattern AND file where it exists | "Best practices" |
| "Edge cases handled" | List each case and handling | "Considered edge cases" |
## Red Flag Words
If your completion report contains: should, probably, seems to,
I believe, looks correct, I'm confident — STOP.
Replace the word with the evidence that eliminates the hedge.
## Circuit Breaker
After 3 failed fixes for the same issue, STOP.
Question whether you are solving the right problem.
Demandez à l’agent d’accomplir une tâche non triviale (par exemple « ajoutez une validation des entrées à cet endpoint »). Comparez le rapport de complétion avec et sans la barrière de preuve. La différence est visible dès la première tâche : sans la barrière, l’agent rapporte sa confiance. Avec la barrière, il rapporte des preuves.
La configuration ci-dessus est un sous-ensemble du système complet. Elle omet les modes de défaillance nommés et l’application par hooks, mais elle démontre le mécanisme central : définir ce qui ne compte PAS comme preuve change immédiatement le comportement de vérification de l’agent.
Résultats en production après neuf mois
Le système métacognitif tourne sur 12 projets actifs depuis mai 2025. Mesurer précisément son impact est difficile, car il n’y a pas de groupe témoin (je ne peux pas rejouer les mêmes neuf mois de développement sans le système). Les signaux de tendance sont néanmoins nets :
Avant les instructions métacognitives (les trois premiers mois, de mai à juillet 2025) : l’agent produisait régulièrement des Confidence Mirages, des rapports qui disaient « tests pass » sans les avoir lancés, ou « follows patterns » sans nommer lesquels. Je les repérais lors de la revue manuelle, ce qui signifiait que chaque complétion de l’agent exigeait une vérification humaine complète. L’agent était un outil de brouillon, pas un outil autonome.
Après le tableau des fausses preuves (août 2025) : les affirmations fondées sur de fausses preuves sont tombées presque à zéro dans les rapports de complétion de l’agent. Un exemple représentatif : le commit 3a8f2c1 (septembre 2025, blakecrosley.com) montre un rapport de complétion de l’agent qui cite une sortie de tests précise, les chemins de fichiers relus et les cas limites gérés, pour le même type de tâche qui produisait auparavant « tests should pass » et « follows best practices ». Le tableau nomme et bloque chaque raccourci précis. L’agent ne peut pas dire « tests should pass » quand l’instruction liste explicitement cette phrase comme NON suffisante. Le contrôle mécanique fonctionne parce qu’il compare des motifs de chaînes, pas une intention sémantique.
Après les modes de défaillance nommés (octobre 2025) : les boucles de débogage ont raccourci. Avant le disjoncteur des trois corrections, l’agent tentait 8 à 12 corrections pour un seul problème avant que j’intervienne. Depuis le disjoncteur, l’agent escalade ou demande des précisions après trois tentatives. L’escalade mène généralement à un diagnostic correct plus vite qu’une quatrième supposition ne l’aurait fait.
Après la détection du langage évasif par hooks (décembre 2025) : le système de hooks intercepte mécaniquement le langage évasif, si bien que l’agent ne peut pas sauter le contrôle, même lors de tâches complexes en plusieurs étapes où les instructions au niveau du prompt passent parfois au second plan. La combinaison des trois couches (tableau + modes de défaillance + hooks) produit une sortie d’agent que je relis pour son exactitude plutôt que pour sa complétude : l’agent rapporte de façon fiable ce qu’il a réellement fait plutôt que ce qu’il comptait faire.
Le système n’élimine pas les erreurs. Il élimine une classe précise d’erreurs : celle où l’auto-évaluation de l’agent diverge de sa performance réelle.
Le schéma est corroboré de manière indépendante par plusieurs sources. Les travaux d’Anthropic sur la Constitutional AI entraînent les modèles sur des critères d’auto-évaluation plutôt que sur le seul retour externe.9 Le projet superpowers d’obra a découvert indépendamment que les skills de « vérification avant complétion » modifient davantage le comportement des agents que les instructions au niveau de l’action.1 Les process reward models (PRM) d’OpenAI ont montré qu’évaluer chaque étape de raisonnement indépendamment produit des sorties plus fiables qu’évaluer seulement la réponse finale, principe que le tableau des fausses preuves applique aux étapes de vérification de l’agent.10 Le framework Reflexion de Shinn et al. (2023) a démontré que des LLM recevant des prompts structurés d’autoréflexion amélioraient leur précision de 20 à 30 % sur des benchmarks de code par rapport à une simple nouvelle tentative, établissant que le format de l’auto-évaluation compte autant que sa présence.11 Le tableau des fausses preuves de ce système en est une version spécifiée à la main : définissez explicitement les critères d’évaluation, et la qualité de la sortie de l’agent s’améliore parce que son auto-surveillance s’améliore.
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 attrape des raccourcis précis. Il n’attrape pas les raccourcis inédits qu’il ne nomme pas. Les modes de défaillance nommés détectent des schémas connus. Ils ne détectent pas ceux qui n’ont pas encore de nom. La détection du langage évasif repère la substitution superficielle de la confiance à la preuve. Elle ne repère pas un agent qui s’est réellement convaincu (dans le sens, quel qu’il soit, où « convaincu » s’applique) qu’une sortie fausse est correcte.
Plus fondamentalement, les instructions métacognitives approchent le goût sans le produire. Le système Jiro peut empêcher except: pass et imposer des preuves de tests. Il ne peut pas déterminer si l’architecture est la bonne, si le nommage traduit l’intention, ni si la solution répond au problème réel plutôt qu’au problème énoncé. Ces jugements exigent un raisonnement contextuel que les modèles actuels approchent sans l’exercer de façon fiable.
Quelqu’un a répondu à l’un de mes tweets sur le système Jiro, en substance : vous essayez au fond d’apprendre à la boucle la retenue, le goût et quelque chose qui ressemble à une pause morale, précisément ce contre quoi le pattern Ralph de base optimise explicitement au nom du débit.8
Cette personne avait raison. La programmation métacognitive est un échafaudage structurel pour des qualités que la machine ne possède pas. Cet échafaudage est porteur. Sans lui, la machine produit des Confidence Mirages à grande échelle. Avec lui, elle produit une sortie vérifiée à grande échelle. L’écart entre ces deux résultats, c’est la différence entre un agent à qui vous pouvez confier une nuit de travail et un agent que vous devez surveiller comme le lait sur le feu.
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. La couche métacognitive rend cette limite visible au lieu de la cacher derrière une prose assurée.
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 qu’il s’en écarte. C’est le second type qui distingue une sortie plausible d’une sortie vérifiée.
-
Nommez les modes de défaillance de votre agent. Dès 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 déploient à grande échelle des workflows assistés par 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) bloque à l’avance les raccourcis précis que prennent les agents quand on leur demande de « vérifier ».
-
Le langage évasif est un signal fiable. Chaque fois qu’un agent dit « should », « probably » ou « I’m confident » dans un rapport de complétion, il n’a pas effectué la vérification qu’il revendique. Détectez-le et remplacez-le mécaniquement.
L’audit métacognitif
Vous voulez évaluer vos propres instructions d’agent ? L’outil interactif ci-dessous analyse n’importe quel CLAUDE.md, AGENTS.md ou prompt système et lui attribue un score selon les dimensions métacognitives décrites dans cet article.
Collez vos instructions d’agent, et l’audit identifiera : quelle part de vos instructions relève du niveau de l’action et quelle part du niveau métacognitif, quels modes de défaillance nommés sont couverts, si une détection du langage évasif existe, et où se trouvent les lacunes.
Questions fréquentes
Quelle est la différence entre les instructions au niveau de l’action et les instructions métacognitives pour un agent IA ?
Les instructions au niveau de l’action définissent le comportement correct : « utiliser des type hints », « écrire des tests », « valider les entrées ». Les instructions métacognitives définissent comment l’agent surveille sa propre conformité à ces comportements : « si vous employez le mot “devrait” dans un rapport de vérification, vous n’avez pas réellement vérifié », « si trois corrections échouent, remettez en question l’architecture ». Les instructions au niveau de l’action empêchent les sorties fausses. Les instructions métacognitives empêchent les schémas de raisonnement erronés qui produisent ces sorties fausses. La plupart des configurations d’agent ne contiennent que le premier type, ce qui explique que les agents livrent un travail plausible mais non vérifié.
Comment construire une couche métacognitive pour un agent de programmation IA ?
Commencez par le tableau des fausses preuves. Listez les cinq affirmations que votre agent formule le plus souvent (« les tests passent », « suit les patterns », « gère les cas limites ») et définissez pour chacune ce qui ne compte PAS comme preuve. La troisième colonne (NON suffisant) bloque des raccourcis précis avant que l’agent ne les prenne. Ajoutez les modes de défaillance nommés après avoir observé trois fois le même schéma d’erreur. Ajoutez la détection du langage évasif en dernier, comme contrôle mécanique. Chaque couche attrape des erreurs que la précédente laisse passer. L’ensemble du système peut démarrer comme une section markdown de votre CLAUDE.md et grandir à partir de là.
La programmation métacognitive fonctionne-t-elle avec d’autres modèles que Claude ?
Les principes sont indépendants du modèle. Tout modèle de langage qui suit des instructions peut tirer parti des tableaux des fausses preuves, des modes de défaillance nommés et de la détection du langage évasif. Le mécanisme d’application varie : Claude Code prend en charge des hooks qui interceptent la sortie de l’agent au niveau de l’utilisation des outils (déterministes, impossibles à contourner). D’autres frameworks peuvent s’appuyer sur des prompts système ou des scripts de post-traitement. La force de l’application détermine la fiabilité : les instructions métacognitives au niveau du prompt améliorent la qualité de la sortie, mais l’application au niveau des hooks la garantit.
Quels signes indiquent qu’un agent IA a besoin d’instructions métacognitives ?
Quatre signaux : (1) L’agent annonce « terminé », mais le travail contient des erreurs évidentes (un Hollow Report, où l’agent a sauté la vérification). (2) Le même type d’erreur revient d’une session à l’autre : un mode de défaillance sans nom qui se répète parce que rien ne le guette. (3) Les rapports de complétion de l’agent emploient un langage évasif (« should work », « looks correct ») au lieu de citer des preuves : un Confidence Mirage. (4) L’agent s’enlise dans de longues boucles de débogage sans remettre en question son approche : il manque un disjoncteur. Si l’un de ces schémas apparaît plus de deux fois, l’agent a besoin d’un échafaudage métacognitif.
Cet article fait partie de la série Claude Code Deep Dives. Le système de hooks met en œuvre la couche d’application décrite ici. Le context engineering comme architecture explique comment la couche métacognitive s’insère dans le système de contexte plus large à sept couches.
-
obra/superpowers sur GitHub. Le projet superpowers comprend des skills de débogage systématique et de vérification qui apprennent aux agents Claude Code à surveiller leurs propres schémas de raisonnement plutôt que leurs seules sorties. Le cadrage métacognitif du présent article s’appuie sur cette approche. github.com/obra/superpowers ↩↩↩
-
La structure du tableau des fausses preuves s’inspire du schéma de vérification avant complétion du projet obra/superpowers. J’ai adapté le concept en Evidence Gate, un système de vérification à six critères appliqué par des hooks. Voir l’article sur la philosophie de qualité Jiro pour l’implémentation complète. ↩
-
La troisième colonne (NON suffisant) traite ce que la littérature académique appelle les « illusions métacognitives » : les cas où l’auto-évaluation qu’un agent fait de sa propre performance diverge de sa performance réelle. En sciences cognitives, le phénomène est bien documenté : les étudiants qui s’estiment « avoir compris » une matière réussissent souvent mal les tests portant sur cette matière. Dunning, D., Johnson, K., Ehrlinger, J., & Kruger, J. (2003). Why people fail to recognize their own incompetence. Current Directions in Psychological Science, 12(3), 83-87. doi.org/10.1111/1467-8721.01235 ↩↩
-
Les sept modes de défaillance nommés sont issus de neuf mois d’utilisation en production. Chacun a été documenté après que le schéma a été observé au moins trois fois sur différents projets et types de tâches. Le système complet est décrit dans Pourquoi mon agent IA a une philosophie de qualité. ↩
-
Analyse par l’auteur des skills officiels de Claude Code disponibles via le système de skills de la CLI Claude Code. Les interdictions (« NEVER X ») se sont révélées plus efficaces que les suggestions (« consider Y ») parce qu’elles nomment l’esquive précise. L’observation selon laquelle les skills orientés état d’esprit l’emportent sur les guides procéduraux en matière d’adoption repose sur des retours de la communauté sur le Discord de Claude Code et dans des discussions GitHub, et non sur une étude contrôlée. Voir la documentation Claude Code d’Anthropic : docs.anthropic.com/en/docs/claude-code. ↩
-
L’idée que le langage évasif signale une vérification insuffisante trouve un appui empirique au-delà des systèmes d’agents. Nisbett, R.E. and Wilson, T.D. (1977). « Telling More Than We Can Know: Verbal Reports on Mental Processes. » Psychological Review, 84(3), 231-259. doi.org/10.1037/0033-295X.84.3.231. Nisbett et Wilson ont constaté que les comptes rendus verbaux des processus de raisonnement sont souvent confabulés : les gens décrivent des explications plausibles plutôt qu’un récit exact de leur raisonnement réel. La même dynamique apparaît dans la sortie des agents : « je suis certain que c’est correct » est une auto-évaluation plausible, pas une preuve de vérification. ↩
-
La règle d’escalade des trois corrections fonctionne comme un pattern de disjoncteur appliqué au débogage. Le pattern est analogue au circuit breaker des systèmes distribués (Nygard, M. Release It!, 2007, Pragmatic Bookshelf) : échouer vite, escalader, essayer une autre approche. Après trois tentatives ratées à l’intérieur du même modèle mental, poursuivre sur la même voie donne des rendements décroissants. ↩
-
Paraphrase d’une réponse à @blakec sur X, février 2026. Le tweet original portait sur la tension entre l’optimisation de vélocité de la boucle Ralph et la friction de qualité du système Jiro. L’observation de la personne qui a répondu, selon laquelle la boucle de base « explicitly optimizes against restraint in the name of throughput », décrit avec justesse la tension de conception à laquelle répond la couche métacognitive. ↩
-
Anthropic, « Constitutional AI: Harmlessness from AI Feedback, » 2022. arxiv.org/abs/2212.08073. L’approche Constitutional AI entraîne le modèle à évaluer ses propres sorties au regard d’un ensemble de principes. Le système métacognitif décrit ici en est une version à l’exécution : au lieu d’une auto-évaluation au moment de l’entraînement, le tableau des fausses preuves et les modes de défaillance nommés fournissent des critères d’évaluation au moment de l’inférence, par le biais du jeu d’instructions. ↩
-
Lightman, H., Kosaraju, V., Burda, Y., et al., « Let’s Verify Step by Step, » arXiv, 2023. arxiv.org/abs/2305.20050. Les travaux d’OpenAI sur les process reward models ont montré qu’évaluer les étapes intermédiaires du raisonnement (supervision du processus) surpasse l’évaluation de la seule réponse finale (supervision du résultat) en résolution de problèmes mathématiques. Le tableau des fausses preuves applique le même principe au niveau des instructions : il exige une preuve pour chaque affirmation de vérification au lieu d’accepter un rapport final « terminé ». ↩
-
Shinn, N., Cassano, F., Gopinath, A., et al., « Reflexion: Language Agents with Verbal Reinforcement Learning, » NeurIPS 2023. arxiv.org/abs/2303.11366. Reflexion a obtenu des gains de précision de 20 à 30 % sur les benchmarks HumanEval et ALFWorld en donnant aux agents LLM des prompts structurés d’autoréflexion après leurs échecs. Le framework valide l’idée centrale du présent système : le format et la précision des instructions d’auto-évaluation comptent autant que leur présence. ↩