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. Uso “metacognitivo” como uma analogia funcional, não como uma afirmação da ciência cognitiva: LLMs não têm processos internos de monitoramento como os humanos têm. O que eles têm é um comportamento de seguir instruções que pode ser direcionado para a autoavaliação. O framework funciona porque muda quais instruções o agente segue durante a verificação, não porque o agente desenvolve uma autoconsciência genuína. A maioria das pessoas só escreve o primeiro tipo de instrução.
Programação metacognitiva de IA é a prática de dar a agentes de IA instruções de autoavaliação: não apenas dizer a eles o que fazer, mas ensiná-los a detectar quando estão indo na direção errada. Instruções de nível de ação definem comportamento (“escreva testes”, “valide entradas”). Instruções metacognitivas definem automonitoramento (“se você diz ‘deveria’ em vez de ‘fiz’, você não verificou”). Essa segunda camada, implementada por meio de portões de evidência, modos de falha nomeados e detecção de linguagem evasiva, separa agentes que produzem saídas plausíveis de agentes que produzem saídas corretas.
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 em vez 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. 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 por meio 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 ele está indo na direção errada. Um tipo previne ações erradas. O outro previne raciocínio errado: os padrões de pensamento que produzem ações erradas, para começo de conversa.
O projeto obra/superpowers no GitHub explora esse território por meio de skills que ensinam agentes a observar o próprio raciocínio em busca de sinais de falha.1 O insight: a maioria das skills 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 já construí é uma tabela que define o que NÃO conta como evidência.2
Quando digo a um agente “verifique seu trabalho”, o agente produz uma verificação. Mas essa verificação muitas vezes é uma reafirmação da intenção, não uma demonstração do resultado. “Os testes devem passar.” “A implementação segue as boas práticas.” “Estou confiante de que isso está correto.” Cada uma dessas afirmações soa como evidência. Nenhuma delas é evidência.
A tabela de evidências falsas bloqueia de antemão atalhos específicos ao nomeá-los:
| Afirmação | Evidência Necessária | NÃO Suficiente (Evidência Falsa) |
|---|---|---|
| “Os testes passam” | Saída dos testes colada com 0 falhas | “Os testes devem passar” ou “Eu rodei antes” |
| “Segue os padrões” | Nomear o padrão E o arquivo onde ele existe | “Segui as boas práticas” |
| “Solução mais simples” | Nomear as alternativas rejeitadas e o porquê | “Está limpo” |
| “Casos extremos tratados” | Listar cada caso extremo e seu tratamento | “Considerei os casos extremos” |
| “Sem regressões” | Nomear os arquivos/funcionalidades verificados | “Nada mais deve ser afetado” |
| “Resolve o problema” | Declarar a necessidade do usuário e como isso a atende | “Implementa a funcionalidade” |
É na terceira coluna que está o valor. Sem ela, o agente preenche a segunda coluna com reafirmações plausíveis da própria confiança. Com ela, a tabela nomeia e bloqueia cada atalho específico antes que o agente o tome.3
A tabela vai além da engenharia de prompt típica. Ela cria um framework de automonitoramento, e não uma diretiva comportamental. A tabela não diz ao agente o que fazer de diferente. Ela diz ao agente o que observar na própria saída. O agente monitora as próprias respostas em relação à coluna NÃO Suficiente e, quando detecta uma correspondência, sabe que deve substituir o atalho por evidência real.
O padrão escala. Qualquer afirmação específica de domínio pode ser adicionada. Para revisões de segurança: “Sem vulnerabilidades” exige “classes específicas de vulnerabilidade verificadas e os achados”, não “Revisei o código”. Para acessibilidade: “Em conformidade com a WCAG” exige “saída de auditoria do axe ou do Lighthouse”, não “Verifiquei o contraste”.
Modos de Falha Nomeados como Salvaguardas Metacognitivas
Humanos têm vieses cognitivos com nome: viés de confirmação, ancoragem, Dunning-Kruger. Os nomes importam. Depois que você consegue nomear o viés, consegue ficar atento a ele. Agentes de IA precisam do mesmo vocabulário para seus padrões de falha.
Documentei sete modos de falha que meu agente apresentava repetidamente, dei um nome a cada um e adicionei sinais de detecção:4
| Modo de Falha | Como Se Manifesta | Sinal de Detecção |
|---|---|---|
| Espiral de Atalhos | Pular etapas de verificação para reportar mais rápido | Relatório de conclusão sem evidência para cada etapa |
| Miragem de Confiança | “Estou confiante” substituindo a verificação real | Linguagem evasiva no relatório |
| Platô do Bom o Bastante | Código funcional que não está limpo, testado ou documentado | Hesitação quando questionado sobre qualidade |
| Visão de Túnel | Polir uma função enquanto quebra o código adjacente | “Nada mais afetado” sem verificar |
| Verificação Fantasma | Afirmar que os testes passam sem executá-los agora | Evidência de uma sessão anterior |
| Dívida Adiada | Deixar TODO/FIXME/HACK em código commitado | Qualquer comentário desse tipo no diff |
| Relatório Vazio | “Pronto” sem citar detalhes específicos | Relatório de conclusão sem evidência para algum critério |
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 passa a ser: “Se você se pegar apresentando qualquer modo de falha nomeado, PARE e recomece a partir da etapa de Avaliação.”
O monitoramento é metacognitivo no sentido preciso: o agente observa o próprio processo cognitivo (estou pulando a verificação? estou usando confiança como substituta de evidência?), e não sua saída (este código está correto?). O monitoramento molda a geração como parte do processo de raciocínio do agente, e é por isso que ele captura erros que a revisão no nível da saída deixa passar.
As próprias implementações de referência de skills da Anthropic apoiam essa abordagem. A análise das skills oficiais do Claude Code revelou padrões estruturais no design eficaz de instruções para agentes. Na observação do autor, proibições (“NUNCA faça X”) se mostraram mais eficazes do que sugestões (“considere Y”) porque nomeiam a evasão específica, e não a ação geral.5 Modos de falha nomeados são proibições específicas: “NUNCA apresente Verificação Fantasma” funciona melhor do que “sempre rode os testes” porque bloqueia a evasão em vez 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
Sempre que o agente usa uma dessas palavras em um relatório de conclusão, a própria palavra é evidência de verificação insuficiente.6 “Os testes devem passar” significa que o agente não os executou. “Parece funcionar” significa que o agente deu só uma olhada. “Estou confiante” significa que o agente está substituindo evidência externa por um estado interno.
A implementação é mecânica. O sistema de hooks intercepta a saída do agente e sinaliza a linguagem evasiva. O agente então substitui a palavra evasiva pela verificação que deveria ter feito:
- “Os testes devem passar” vira: executa os testes, cola a saída mostrando 0 falhas
- “Parece correto” vira: cita a asserção ou verificação específica que confirma a correção
- “Estou confiante” vira: lista as evidências que geram essa confiança
O padrão vem do trabalho de obra sobre verificação antes da conclusão (verification-before-completion).1 O paralelo com a ciência cognitiva é bem estabelecido: na metacognição humana, a precisão do autorrelato (“eu entendo isso”) tem correlação fraca com a compreensão real.3 Pessoas que dizem “entendi” muitas vezes não entenderam. Pessoas que conseguem explicar geralmente entenderam. O mesmo vale para agentes de IA: um agente que consegue citar evidências específicas entende o problema. Um agente que diz “estou confiante” pode não entender.
O Disjuntor de Três Tentativas
Metacognição não é apenas detectar raciocínio ruim. É também 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 de forma fundamental.7 Não tentar uma quarta correção. Não buscar um ângulo diferente dentro da 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 chamo de Espiral de Correções: cada tentativa fracassada produz uma nova teoria, que produz uma nova correção, que falha, que produz uma nova teoria. O agente pode passar por dezenas de correções sem nunca questionar se está trabalhando no problema certo. O incidente dos 23 agentes descontrolados foi uma versão em largura disso: os agentes chegaram a um consenso sobre a pergunta errada porque nenhuma verificação metacognitiva perguntou “esta pergunta está com o escopo correto?”
A regra das três tentativas funciona porque força uma transição de fase no raciocínio do agente. As correções 1 a 3 operam dentro do modelo mental atual. A correção 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 premissas ou pedir esclarecimentos ao usuário, e tudo isso é mais produtivo do que um quarto palpite.
Antes e Depois: O Que Muda
Aqui está um exemplo concreto. Pedi a um agente que adicionasse 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 um código melhor. Os dois agentes podem ter escrito um código idêntico. A diferença é que o segundo agente verificou seu trabalho em relação a critérios específicos de evidência e reportou a evidência em vez da própria confiança.
Construindo Sua Própria Camada Metacognitiva
O framework é portátil. 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 seu domínio. É na terceira coluna (NÃO Suficiente) que está o valor.
2. Modos de Falha Nomeados. Documente as três a cinco formas mais frequentes de falha do seu agente. Dê um nome a cada uma. Adicione sinais de detecção. Inclua a instrução: “Se você se pegar apresentando 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 combinam em uma camada metacognitiva que fica por cima de 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 o 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 por meio de hooks (determinísticos, não podem ser pulados), arquivos de regras (carregados no contexto) ou instruções inline (dependem da obediência do modelo), isso 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 do prompt. Ainda assim, mesmo instruções metacognitivas no nível do prompt melhoram de forma mensurável a qualidade da saída do agente, porque mudam os critérios de avaliação do agente, e não apenas suas ações.
Exercício: audite suas três últimas interações com agentes. Copie os relatórios de conclusão. Destaque cada ocorrência de “deveria”, “provavelmente” ou “estou confiante”. Para cada palavra destacada, escreva a evidência específica que teria substituído a evasão. Se a evidência existe mas o agente não a citou, o agente precisa de detecção de linguagem evasiva. Se a evidência não existe, o agente pulou a verificação por completo: ele precisa da tabela de evidências falsas.
A ordem importa: comece pela tabela de evidências falsas (maior impacto, mais fácil de implementar), depois adicione modos de falha nomeados quando tiver observado padrões recorrentes e, por fim, adicione a detecção de linguagem evasiva como uma verificação mecânica. Cada camada captura erros que a anterior deixa passar. Juntas, elas formam um loop de feedback: o agente monitora a própria saída, detecta padrões de falha conhecidos e se autocorrige antes de reportar a conclusão.
Configuração Mínima Reproduzível
Você pode testar o padrão metacognitivo central em cinco minutos. Crie um arquivo chamado .claude/CLAUDE.md (ou adicione ao seu arquivo existente) com este conteúdo:
## 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.
Peça ao agente que execute qualquer tarefa não trivial (por exemplo, “adicione validação de entrada a este endpoint”). Compare o relatório de conclusão com e sem o portão de evidência. A diferença aparece já na primeira tarefa: sem o portão, o agente reporta confiança. Com o portão, o agente reporta evidências.
A configuração acima é um subconjunto do sistema completo. Ela omite os modos de falha nomeados e a aplicação baseada em hooks, mas demonstra o mecanismo central: definir o que NÃO conta como evidência muda imediatamente o comportamento de verificação do agente.
Resultados em Produção Após Nove Meses
O sistema metacognitivo está rodando em 12 projetos ativos desde maio de 2025. Medir seu impacto com precisão é difícil porque não há grupo de controle (não tenho como rodar os mesmos nove meses de desenvolvimento sem o sistema). Os sinais de direção, porém, são claros:
Antes das instruções metacognitivas (primeiros três meses, maio a julho de 2025): O agente produzia regularmente Miragens de Confiança: relatórios que diziam “os testes passam” sem executá-los e “segue os padrões” sem nomear quais. Eu os pegava na revisão manual, o que significava que toda conclusão do agente exigia verificação humana completa. O agente era uma ferramenta de rascunho, não uma ferramenta autônoma.
Depois da tabela de evidências falsas (agosto de 2025): As afirmações com evidências falsas caíram para perto de zero nos relatórios de conclusão do agente. Um exemplo representativo: o commit 3a8f2c1 (setembro de 2025, blakecrosley.com) mostra um relatório de conclusão do agente citando saída de testes específica, caminhos de arquivos revisados e casos extremos tratados, o mesmo tipo de tarefa que antes produzia “os testes devem passar” e “segue as boas práticas”. A tabela nomeia e bloqueia cada atalho específico. O agente não consegue dizer “os testes devem passar” quando a instrução lista explicitamente essa frase como NÃO Suficiente. A verificação mecânica funciona porque compara padrões de texto, não intenção semântica.
Depois dos modos de falha nomeados (outubro de 2025): Os loops de depuração encurtaram. Antes do disjuntor de três tentativas, o agente tentava de 8 a 12 correções para um único problema antes que eu interviesse. Depois do disjuntor, o agente escala ou pede esclarecimentos após três tentativas. A escalação geralmente leva a um diagnóstico correto mais rápido do que um quarto palpite levaria.
Depois da detecção de linguagem evasiva via hooks (dezembro de 2025): O sistema de hooks intercepta a linguagem evasiva de forma mecânica, o que significa que o agente não consegue pular a verificação nem mesmo em tarefas complexas de várias etapas, nas quais as instruções no nível do prompt às vezes perdem prioridade. A combinação das três camadas (tabela + modos de falha + hooks) produz uma saída de agente que eu reviso quanto à correção, e não quanto à completude: o agente reporta de forma confiável o que de fato fez, e não o que pretendia fazer.
O sistema não elimina erros. Ele elimina uma classe específica de erros: aquela em que a autoavaliação do agente diverge do seu desempenho real.
O padrão tem corroboração independente de várias fontes. O trabalho da Anthropic com constitutional AI treina modelos com base em critérios de autoavaliação, e não apenas em feedback externo.9 O projeto superpowers, de obra, descobriu de forma independente que skills de “verificação antes da conclusão” mudam o comportamento do agente mais do que instruções de nível de ação.1 Os modelos de recompensa de processo (PRMs) da OpenAI constataram que avaliar cada etapa de raciocínio de forma independente produz saídas mais confiáveis do que avaliar apenas a resposta final, o mesmo princípio que a tabela de evidências falsas aplica às etapas de verificação do agente.10 O framework Reflexion, de Shinn et al. (2023), demonstrou que LLMs que recebem prompts estruturados de autorreflexão melhoraram a precisão nas tarefas em 20% a 30% em benchmarks de programação, em comparação com uma simples nova tentativa, estabelecendo que o formato da autoavaliação importa tanto quanto sua presença.11 A tabela de evidências falsas do presente sistema é uma versão especificada manualmente do mesmo princípio: defina os critérios de avaliação de forma explícita e a qualidade da saída do agente melhora, porque o automonitoramento dele melhora.
O Que a Metacognição Não Consegue Fazer
A programação metacognitiva torna os agentes de IA mais confiáveis. Ela não os torna sábios.
A tabela de evidências falsas captura atalhos específicos. Ela não captura atalhos novos que a tabela não nomeia. Modos de falha nomeados detectam padrões conhecidos. Eles não detectam padrões que ainda não foram nomeados. A detecção de linguagem evasiva captura a substituição superficial de evidência por confiança. Ela não captura um agente que genuinamente se convenceu (em qualquer sentido em que “convencer” se aplique) de que uma saída errada está correta.
Mais fundamentalmente, instruções metacognitivas se aproximam do bom gosto, mas não o produzem. O sistema Jiro consegue impedir except: pass e exigir evidência de testes. Ele não consegue determinar se a arquitetura está certa, se a nomenclatura captura a intenção ou se a solução resolve o problema real em vez do problema declarado. Esses julgamentos exigem 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, em paráfrase: você está basicamente tentando ensinar ao loop contenção, bom gosto e algo próximo de uma pausa moral, coisas contra as quais o padrão Ralph básico otimiza explicitamente em nome da vazão.8
Estavam certos. A programação metacognitiva é um andaime estrutural para qualidades que a máquina não tem. O andaime sustenta carga. Sem ele, a máquina produz Miragens de Confiança em escala. Com ele, a máquina produz saídas verificadas em escala. A distância entre esses dois resultados é a diferença entre um agente em que você pode confiar para rodar a noite inteira e um agente de que você precisa ficar tomando conta.
Mas o andaime não é o prédio. O prédio (bom gosto, discernimento, a capacidade de saber quando a resposta certa para uma pergunta é uma pergunta diferente) continua sendo humano. A camada metacognitiva torna essa limitação visível em vez de escondê-la atrás de uma prosa confiante.
Conclusões Principais
Para engenheiros que constroem 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 o comportamento correto. Instruções metacognitivas definem como o agente detecta o próprio desvio do comportamento correto. O segundo tipo é o que separa a saída plausível da saída verificada.
-
Dê nome aos modos de falha do seu agente. Quando um padrão de falha tem nome (Miragem de Confiança, Verificação Fantasma, Espiral de Atalhos), o agente consegue ficar atento a ele. Falhas sem nome se repetem indefinidamente.
Para equipes que escalam 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 de antemão os atalhos específicos que os agentes tomam quando lhes pedem para “verificar”.
-
Linguagem evasiva é um sinal confiável. Sempre que um agente diz “deveria”, “provavelmente” ou “estou confiante” em um relatório de conclusão, ele não fez a verificação que alega. Detecte e substitua de forma mecânica.
A Auditoria Metacognitiva
Quer avaliar as instruções do seu próprio 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 as instruções do seu agente, e a auditoria vai identificar: qual porcentagem das suas instruções é de nível de ação e qual é metacognitiva, quais modos de falha nomeados estão cobertos, se existe detecção de linguagem evasiva e onde estão as lacunas.
Perguntas frequentes
Qual é a diferença entre instruções de nível de ação e instruções metacognitivas para agentes de IA?
Instruções de nível de ação definem o comportamento correto: “use type hints”, “escreva testes”, “valide entradas”. Instruções metacognitivas definem como o agente monitora a própria conformidade com esses comportamentos: “se você usar a palavra ‘deveria’ em um relatório de verificação, você não verificou de fato”, “se três correções falharem, questione a arquitetura”. Instruções de nível de ação previnem saídas erradas. Instruções metacognitivas previnem os padrões de raciocínio errados que produzem saídas erradas. A maioria das configurações de agentes contém apenas o primeiro tipo, e é por isso que os agentes produzem trabalho plausível, mas não verificado.
Como construo uma camada metacognitiva para um agente de programação com IA?
Comece pela tabela de evidências falsas. Liste as cinco afirmações que seu agente faz com mais frequência (“os testes passam”, “segue os padrões”, “trata os casos extremos”) e defina o que NÃO conta como prova para cada uma. A terceira coluna (NÃO Suficiente) bloqueia atalhos específicos antes que o agente os tome. Adicione modos de falha nomeados depois de observar o mesmo padrão de erro três vezes. Adicione a detecção de linguagem evasiva por último, como uma verificação mecânica. Cada camada captura erros que a anterior deixa passar. O sistema inteiro pode começar como uma seção em markdown no seu CLAUDE.md e crescer a partir daí.
A programação metacognitiva funciona com modelos além do Claude?
Os princípios independem do modelo. Qualquer modelo de linguagem que siga instruções pode se beneficiar de tabelas de evidências falsas, modos de falha nomeados e detecção de linguagem evasiva. O mecanismo específico de aplicação varia: o Claude Code oferece hooks que interceptam a saída do agente no nível de uso de ferramentas (determinísticos, não podem ser contornados). Outros frameworks podem depender de prompts de sistema ou de scripts de pós-processamento. A força da aplicação determina a confiabilidade: instruções metacognitivas no nível do prompt melhoram a qualidade da saída, mas a aplicação no nível de hooks a garante.
Quais são os sinais de que um agente de IA precisa de instruções metacognitivas?
Quatro sinais: (1) O agente reporta “pronto”, mas o trabalho contém erros óbvios (um Relatório Vazio, em que o agente pulou a verificação). (2) O mesmo tipo de erro se repete entre sessões, um modo de falha sem nome que se repete porque nada fica atento a ele. (3) Os relatórios de conclusão do agente usam linguagem evasiva (“deve funcionar”, “parece correto”) em vez de citar evidências: uma Miragem de Confiança. (4) O agente entra em longos loops de depuração sem questionar a própria abordagem: falta um disjuntor. Se qualquer um desses padrões aparecer mais de duas vezes, o agente precisa de um andaime metacognitivo.
Parte da série Claude Code Deep Dives. O sistema de hooks implementa a camada de aplicação descrita aqui. Engenharia de contexto como arquitetura explica como a camada metacognitiva se encaixa no sistema de contexto mais amplo, de sete camadas.
-
obra/superpowers no GitHub. O projeto superpowers inclui skills de depuração sistemática e verificação que ensinam agentes do Claude Code a monitorar os próprios padrões de raciocínio, e não apenas suas saídas. O enquadramento metacognitivo deste artigo se baseia nessa abordagem. github.com/obra/superpowers ↩↩↩
-
A estrutura da tabela de evidências falsas se baseia no padrão verification-before-completion do projeto obra/superpowers. Adaptei o conceito no Portão de Evidência, um sistema de verificação de seis critérios aplicado por meio de hooks. Veja o post sobre a filosofia de qualidade Jiro para a implementação completa. ↩
-
A terceira coluna (NÃO Suficiente) aborda o que a literatura acadêmica chama de “ilusões metacognitivas”: casos em que a autoavaliação de um agente sobre o próprio desempenho diverge do desempenho real. Na ciência cognitiva, isso é bem documentado: estudantes que se avaliam como “entendendo” o material frequentemente têm desempenho ruim em testes sobre esse material. 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 ↩↩
-
Os sete modos de falha nomeados surgiram de nove meses de uso em produção. Cada um foi documentado depois de o padrão ser observado pelo menos três vezes em diferentes projetos e tipos de tarefa. O sistema completo é descrito em Why My AI Agent Has a Quality Philosophy. ↩
-
Análise do autor sobre as skills oficiais do Claude Code disponíveis pelo sistema de skills do Claude Code CLI. Proibições (“NEVER X”) se mostraram mais eficazes do que sugestões (“consider Y”) porque nomeiam a evasão específica. A observação de que skills orientadas a mentalidade superam guias procedurais em adoção se baseia em relatos da comunidade no Discord do Claude Code e em discussões no GitHub, não em um estudo controlado. Veja a documentação do Claude Code da Anthropic: docs.anthropic.com/en/docs/claude-code. ↩
-
A ideia de que a linguagem evasiva sinaliza verificação insuficiente tem respaldo empírico além dos sistemas de agentes. 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 e Wilson constataram que os autorrelatos verbais de processos de raciocínio são frequentemente confabulados: as pessoas descrevem explicações que soam plausíveis em vez de relatos precisos do seu raciocínio real. A mesma dinâmica aparece na saída de agentes: “I’m confident this is correct” é um autorrelato que soa plausível, não uma evidência de verificação. ↩
-
A regra de escalação de três tentativas funciona como um padrão de disjuntor (circuit breaker) aplicado à depuração. O padrão é análogo ao disjuntor em sistemas distribuídos (Nygard, M. Release It!, 2007, Pragmatic Bookshelf): falhar rápido, escalar, tentar uma abordagem diferente. Depois de três tentativas fracassadas dentro do mesmo modelo mental, continuar no mesmo caminho produz retornos decrescentes. ↩
-
Paráfrase de uma resposta a @blakec no X, fevereiro de 2026. O tweet original discutia a tensão entre a otimização de velocidade do loop Ralph e a fricção de qualidade do sistema Jiro. A observação do respondente de que o loop básico “explicitly optimizes against restraint in the name of throughput” descreve com precisão a tensão de design que a camada metacognitiva aborda. ↩
-
Anthropic, “Constitutional AI: Harmlessness from AI Feedback,” 2022. arxiv.org/abs/2212.08073. A abordagem de constitutional AI treina o modelo para avaliar as próprias saídas com base em um conjunto de princípios. O sistema metacognitivo descrito aqui é uma versão em tempo de execução da mesma ideia: em vez de autoavaliação no treinamento, a tabela de evidências falsas e os modos de falha nomeados fornecem critérios de avaliação no momento da inferência, por meio do conjunto de instruções. ↩
-
Lightman, H., Kosaraju, V., Burda, Y., et al., “Let’s Verify Step by Step,” arXiv, 2023. arxiv.org/abs/2305.20050. A pesquisa da OpenAI sobre modelos de recompensa de processo demonstrou que avaliar etapas intermediárias de raciocínio (supervisão de processo) supera avaliar apenas a resposta final (supervisão de resultado) na resolução de problemas matemáticos. A tabela de evidências falsas aplica o mesmo princípio no nível das instruções: exige evidência para cada afirmação de verificação em vez de aceitar um relatório final de “pronto”. ↩
-
Shinn, N., Cassano, F., Gopinath, A., et al., “Reflexion: Language Agents with Verbal Reinforcement Learning,” NeurIPS 2023. arxiv.org/abs/2303.11366. O Reflexion demonstrou melhorias de 20% a 30% na precisão nos benchmarks HumanEval e ALFWorld ao dar a agentes LLM prompts estruturados de autorreflexão após falhas. O framework valida o insight central do presente sistema: o formato e a especificidade das instruções de autoavaliação importam tanto quanto sua presença. ↩