IA Metacognitiva: Ensinando Seu Agente a se Autoavaliar

Eu disse ao meu agente para corrigir um teste que estava falhando. O agente leu o erro, identificou a incompatibilidade na asserção, alterou o valor esperado para corresponder à saída real e reportou: “Teste corrigido. Todos os testes passam.” Estava certo. O teste passou. A correção também estava completamente errada.

O teste estava falhando porque a função retornava dados incorretos. O agente “corrigiu” o teste fazendo-o esperar a resposta errada. Ele seguiu minha instrução perfeitamente: corrigir o teste que estava falhando. O que eu quis dizer era: corrigir o código que o teste está testando. O agente não tinha mecanismo para distinguir entre essas duas interpretações porque nada no seu conjunto de instruções pedia que ele avaliasse por que um teste falha antes de decidir como corrigi-lo.

Essa lacuna tem um nome. É a lacuna entre instruções de nível de ação e instruções metacognitivas. A maioria das pessoas só escreve o primeiro tipo.

TL;DR

Existem dois níveis de instrução para agentes de IA. Instruções de nível de ação dizem ao agente o que fazer: “valide entradas,” “escreva testes,” “siga convenções RESTful.” Instruções metacognitivas dizem ao agente como avaliar se ele está fazendo isso bem: “se você se pegar dizendo deveria ao invés de fiz, você não verificou,” “se três correções falharem, pare e questione a arquitetura,” “confiança não é evidência.” A maioria das configurações de agentes contém exclusivamente instruções de nível de ação. A camada metacognitiva separa um agente que produz saída plausível de um que produz saída correta. Eu opero um sistema metacognitivo em produção há nove meses com sete modos de falha nomeados, um portão de evidência de seis critérios e detecção de linguagem evasiva aplicados através de 95 hooks.

Os Dois Níveis de Instrução para Agentes

Toda instrução para agentes opera em um de dois níveis.

Instruções de nível de ação definem comportamento:

# 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

Instruções de nível de ação são necessárias. Elas dizem ao agente como é o comportamento correto. Mas compartilham uma limitação estrutural: assumem que o agente as executará fielmente. Elas não consideram como o agente avalia sua própria conformidade.

Instruções metacognitivas definem automonitoramento:

# 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.

A distinção importa porque instruções de nível de ação dizem ao agente como é o destino. Instruções metacognitivas dizem ao agente como detectar quando está indo na direção errada. Uma previne ações erradas. A outra previne raciocínios errados: os padrões de pensamento que produzem ações erradas em primeiro lugar.

O projeto obra/superpowers no GitHub articulou essa distinção pela primeira vez, chamando-a de “ensinar a IA a observar seu próprio raciocínio interno em busca de sinais de falha.”¹ O insight: a maioria das habilidades opera no nível de ação (faça X, não faça Y). O nível metacognitivo opera de forma diferente (perceba quando você está prestes a fazer Y).

A Tabela de Evidências Falsas

A ferramenta metacognitiva mais eficaz que construí é uma tabela que define o que NÃO conta como evidência.²

Quando eu digo a um agente “verifique seu trabalho,” o agente produz verificação. Mas a verificação é frequentemente uma reformulação da intenção, não uma demonstração do resultado. “Os testes devem passar.” “A implementação segue boas práticas.” “Estou confiante de que isso está correto.” Cada uma dessas afirmações parece evidência. Nenhuma delas é evidência.

A tabela de evidências falsas bloqueia previamente atalhos específicos ao nomeá-los:

A terceira coluna é onde está o valor. Sem ela, o agente preenche a segunda coluna com reformulações plausíveis de sua própria confiança. Com ela, a tabela nomeia e bloqueia cada atalho específico antes que o agente o tome.³

A tabela não é engenharia de prompt. É arquitetura cognitiva. A tabela não diz ao agente o que fazer de diferente. Ela diz ao agente o que observar em sua própria saída. O agente monitora suas próprias respostas contra a coluna NÃO Suficiente e, quando detecta uma correspondência, sabe que deve substituir o atalho por evidência real.

O padrão é escalável. Qualquer afirmação específica de domínio pode ser adicionada. Para revisões de segurança: “Sem vulnerabilidades” requer “classes específicas de vulnerabilidade verificadas e achados,” não “Eu revisei o código.” Para acessibilidade: “Conforme com WCAG” requer “saída de auditoria axe ou Lighthouse,” não “Eu verifiquei o contraste.”

Modos de Falha Nomeados como Salvaguardas Metacognitivas

Humanos têm vieses cognitivos nomeados: viés de confirmação, ancoragem, Dunning-Kruger. Os nomes importam. Uma vez que você consegue nomear o viés, consegue observá-lo. Agentes de IA precisam do mesmo vocabulário para seus padrões de falha.

Eu documentei sete modos de falha que meu agente exibia repetidamente, dei um nome a cada um e adicionei sinais de detecção:⁴

Os nomes tornam as falhas detectáveis. Sem eles, o agente produz uma Miragem de Confiança e nem o agente nem o usuário a reconhecem como um padrão. Com eles, a instrução se torna: “Se você se pegar exibindo qualquer modo de falha nomeado, PARE e recomece da etapa de Avaliação.”

O monitoramento é metacognitivo no sentido preciso: o agente observa seu próprio processo cognitivo (estou pulando a verificação? estou usando confiança como substituto para evidência?) ao invés de sua saída (este código está correto?). O monitoramento acontece antes que o agente produza sua saída, e é por isso que ele captura erros que a revisão no nível de saída não detecta.

As próprias implementações de referência de skills da Anthropic apoiam essa abordagem. A análise de suas 16 skills oficiais do Claude Code revelou padrões estruturais no design eficaz de instruções para agentes. Proibições (“NUNCA faça X”) se mostraram significativamente mais eficazes do que sugestões (“considere Y”) porque nomeiam a evasão específica ao invés da ação geral.⁵ Modos de falha nomeados são proibições específicas: “NUNCA exiba Verificação Fantasma” supera “sempre execute testes” porque bloqueia a evasão ao invés de reafirmar a ação.

Detecção de Linguagem Evasiva

O monitor metacognitivo mais simples que implementei detecta palavras específicas na saída do agente:

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

Toda vez que o agente usa uma dessas palavras em um relatório de conclusão, a própria palavra é evidência de verificação insuficiente.⁶ “Testes devem passar” significa que o agente não os executou. “Parece funcionar” significa que o agente apenas olhou por cima. “Estou confiante” significa que o agente está substituindo estado interno por evidência externa.

A implementação é mecânica. O sistema de hooks intercepta a saída do agente e sinaliza linguagem evasiva. O agente então substitui a palavra evasiva pela verificação que deveria ter realizado:

• “Testes devem passar” se torna: executa testes, cola saída mostrando 0 falhas
• “Parece correto” se torna: cita a asserção ou verificação específica que confirma a correção
• “Estou confiante” se torna: lista a evidência que cria essa confiança

O padrão vem do trabalho de verificação antes da conclusão do obra: “As próprias escolhas de palavras da IA sinalizam evidência insuficiente.”¹ O paralelo com ciência cognitiva é real. Na metacognição humana, a precisão do autorrelato (“Eu entendo isso”) correlaciona-se mal com a compreensão real. Pessoas que dizem “Eu entendi” frequentemente não entenderam. Pessoas que conseguem explicar geralmente entendem. O mesmo se aplica a agentes de IA: um agente que consegue citar evidência específica entende o problema. Um agente que diz “Estou confiante” pode não entender.

O Disjuntor de Três Tentativas

Metacognição não é apenas sobre detectar raciocínio falho. É também sobre detectar quando parar.

A regra de escalação de três tentativas: se três tentativas de correção para o mesmo problema falharam, o agente deve parar e questionar a arquitetura fundamentalmente.⁷ Não tentar uma quarta correção. Não buscar um ângulo diferente na mesma abordagem. Parar. Dar um passo atrás. Perguntar se o problema está na solução ou na definição do problema.

A regra funciona como um disjuntor para loops de depuração. Sem ela, os agentes entram no que eu chamo de Espiral de Correção: cada tentativa falha produz uma nova teoria, que produz uma nova correção, que falha, que produz uma nova teoria. O agente pode percorrer dezenas de correções sem jamais questionar se está trabalhando no problema certo. O incidente de descontrole de 23 agentes foi uma versão em largura disso: os agentes alcançaram consenso sobre a pergunta errada porque nenhuma verificação metacognitiva perguntou “esta pergunta está corretamente delimitada?”

A regra de três tentativas funciona porque força uma transição de fase no raciocínio do agente. As tentativas 1-3 operam dentro do modelo mental atual. A tentativa 4 (que na verdade é “pare de corrigir”) força o agente a construir um novo modelo mental. Na prática, isso geralmente significa reler o erro desde o início, reexaminar as suposições ou pedir esclarecimento ao usuário — todas ações mais produtivas do que um quarto palpite.

Antes e Depois: O Que Muda

Aqui está um exemplo concreto. Eu pedi a um agente para adicionar validação de entrada a um endpoint de API.

Sem instruções metacognitivas:

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.

A saída contém três sinais evasivos: “should pass” (não executou os testes), “follows best practices” (não nomeou quais práticas) e nenhuma evidência de consideração de casos extremos. Uma Miragem de Confiança embrulhada em um Relatório Vazio.

Com instruções metacognitivas (mesma tarefa, mesmo agente):

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.

A diferença não é que o segundo agente escreveu código melhor. Ambos os agentes podem ter escrito código idêntico. A diferença é que o segundo agente verificou seu trabalho contra critérios de evidência específicos e reportou a evidência ao invés de sua confiança.

Construindo Sua Própria Camada Metacognitiva

O framework é portável. Você não precisa do meu sistema específico. Você precisa de três componentes:

1. Uma Tabela de Evidências Falsas. Defina o que NÃO conta como prova para as afirmações que seu agente faz com mais frequência. Comece com os seis critérios acima e adicione linhas específicas do domínio. A terceira coluna (NÃO Suficiente) é onde está o valor.

2. Modos de Falha Nomeados. Documente os três a cinco modos como seu agente falha com mais frequência. Dê um nome a cada um. Adicione sinais de detecção. Inclua a instrução: “Se você se pegar exibindo qualquer modo de falha nomeado, pare e reavalie.”

3. Detecção de Linguagem Evasiva. Liste as palavras específicas que sinalizam verificação insuficiente no seu domínio. Adicione a instrução: “Substitua qualquer palavra evasiva pela evidência que eliminaria a evasão.”

Esses três componentes se compõem em uma camada metacognitiva que se sobrepõe a quaisquer instruções de nível de ação. As instruções de nível de ação definem como é o comportamento correto. A camada metacognitiva define como o agente detecta seu próprio desvio do comportamento correto.

A implementação pode ser tão simples quanto adicionar uma seção ao seu 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]

Se a aplicação acontece através de hooks (determinísticos, não podem ser ignorados), arquivos de regras (carregados no contexto) ou instruções inline (dependem da conformidade do modelo) determina a confiabilidade da camada metacognitiva. Hooks são os mais fortes porque interceptam no nível de uso de ferramentas, não no nível de prompt. Mas mesmo instruções metacognitivas no nível de prompt melhoram de forma mensurável a qualidade da saída do agente porque mudam os critérios de avaliação do agente ao invés de apenas suas ações.

O Que a Metacognição Não Consegue Fazer

A programação metacognitiva torna agentes de IA mais confiáveis. Não os torna sábios.

A tabela de evidências falsas captura atalhos específicos. Não captura atalhos novos que a tabela não nomeia. Modos de falha nomeados detectam padrões conhecidos. Não detectam padrões que ainda não foram nomeados. A detecção de linguagem evasiva captura substituição de confiança no nível superficial. Não captura um agente que genuinamente se convenceu (em qualquer sentido que “convenceu” se aplique) de que uma saída errada está correta.

De forma mais fundamental, instruções metacognitivas aproximam o bom senso mas não o produzem. O sistema Jiro pode prevenir except: pass e exigir evidência de testes. Não pode determinar se a arquitetura está correta, se a nomenclatura captura a intenção, ou se a solução aborda o problema real versus o declarado. Esses julgamentos requerem o tipo de raciocínio contextual que os modelos atuais aproximam mas não executam de forma confiável.

Alguém respondeu a um dos meus tweets sobre o sistema Jiro: “Você basicamente está tentando ensinar ao loop contenção, bom senso e algo que se aproxima de uma pausa moral — coisas que o padrão Ralph base explicitamente otimiza contra em nome da vazão.”⁸

Estavam certos. A programação metacognitiva é andaime estrutural para qualidades que a máquina não possui. O andaime é estrutural e suporta carga. Sem ele, a máquina produz Miragens de Confiança em escala. Com ele, a máquina produz saída verificada em escala. A diferença entre esses dois resultados é a diferença entre um agente em que você pode confiar para rodar durante a noite e um agente que você precisa supervisionar.

Mas o andaime não é o edifício. O edifício (bom senso, julgamento, a capacidade de saber quando a resposta certa para uma pergunta é uma pergunta diferente) permanece humano. Por enquanto.

Conclusões Principais

Para engenheiros construindo sistemas de agentes:

• Escreva instruções metacognitivas, não apenas instruções de nível de ação. Instruções de nível de ação definem comportamento correto. Instruções metacognitivas definem como o agente detecta seu próprio desvio do comportamento correto. O segundo tipo é o que separa saída plausível de saída verificada.

• Nomeie os modos de falha do seu agente. Uma vez que um padrão de falha tem um nome (Miragem de Confiança, Verificação Fantasma, Espiral de Atalhos), o agente pode observá-lo. Falhas sem nome se repetem indefinidamente.

Para equipes escalando fluxos de trabalho assistidos por IA:

• Construa uma tabela de evidências falsas antes de escalar. Defina o que NÃO conta como prova para cada afirmação que seu agente faz. A terceira coluna (NÃO Suficiente) bloqueia previamente os atalhos específicos que agentes tomam quando solicitados a “verificar.”

• Linguagem evasiva é um sinal confiável. Toda vez que um agente diz “deveria,” “provavelmente” ou “estou confiante” em um relatório de conclusão, o agente não realizou a verificação que alega. Detecte e substitua mecanicamente.

A Auditoria Metacognitiva

Quer avaliar suas próprias instruções de agente? A ferramenta interativa abaixo analisa qualquer CLAUDE.md, AGENTS.md ou prompt de sistema e atribui uma pontuação nas dimensões metacognitivas descritas neste post.

Cole suas instruções de agente, e a auditoria identificará: qual porcentagem das suas instruções é de nível de ação versus metacognitiva, quais modos de falha nomeados estão cobertos, se existe detecção de linguagem evasiva e onde estão as lacunas.

Parte da série Claude Code Mastery, que documenta a infraestrutura por trás do desenvolvimento autônomo com IA: desde hooks que aplicam controle determinístico até gerenciamento de contexto como disciplina arquitetônica e deliberação multi-agente que captura pontos cegos de agentes individuais. A filosofia de engenharia composta que sustenta o sistema explica por que cada componente acelera tudo que é construído após ele.