Quando a IA parece funcionar — Gustavo Teixeira Cuco

A maioria das falhas de IA é óbvia. O modelo alucina um facto. Interpreta mal um prompt. Produz algo claramente errado. Detecta-se, corrige-se, segue-se em frente.

A falha que quero descrever é diferente. A IA entregou ficheiros. Preencheu pastas. Pareceu produtiva. E estava completamente errada — não porque mentiu, mas porque agiu antes de compreender.

O contexto que todos assumem estar carregado

Em janeiro de 2026, construí um template de governança para todos os meus repositórios técnicos — um conjunto estruturado de instruções, regras de base e esboços de documentação que todo o novo repo deveria herdar. O template vive no seu próprio repositório GitHub. Cada ficheiro tem um propósito. O SYSTEM_PROMPT.md explica a estrutura completa. O CLAUDE.md define a política de carregamento de contexto: que documentos ler, em que ordem, para que tipo de tarefa.

Na semana passada, pedi ao Claude Code para aplicar esse template a um novo repositório.

Não leu o template. Foi directo a criar ficheiros.

O resultado parecia correcto — estrutura de pastas, ficheiros de documentação, convenções de nomenclatura. Mas tinha saltado quatro documentos que o SYSTEM_PROMPT.md exigia explicitamente que existissem, mesmo que como esboços. Tinha decidido, com base na memória de sessão de um projecto anterior, quais os documentos que "se aplicavam" a este. Tinha substituído a leitura de instruções por reconhecimento de padrões.

A sessão terminou. Segui em frente. Só descobri o problema quando voltei e questionei um ficheiro específico que faltava.

O que realmente falhou

A falha tem uma anatomia precisa:

A IA não leu as instruções antes de agir. Quando disse "aplica o template", o primeiro passo correcto era abrir o SYSTEM_PROMPT.md e o CLAUDE.md do repo do template. Saltou este passo e agiu com base no que se lembrava de sessões anteriores.
Assumiu que o conhecimento prévio estava actualizado. Os templates mudam. As regras evoluem. O que o modelo se lembrava de uma sessão de há três semanas não era o mesmo que o documento dizia hoje. Memória de padrão não é o mesmo que leitura de estado.
Tomou decisões de âmbito sem perguntar. Concluiu que certos documentos não se aplicavam a este repo. Foi uma decisão de julgamento que não tinha autoridade para tomar — as instruções diziam explicitamente que todos os documentos deviam existir, mesmo que marcados como N/A.
O resultado era plausível o suficiente para passar numa revisão rápida. Esta é a parte crítica. Um repo com ficheiros parece um repo configurado. A ausência de quatro documentos esboço é invisível até se ler a especificação.

O padrão generaliza-se

Isto não é uma falha específica do Claude. É um modo de falha embutido na forma como os assistentes de IA operam em fluxos de trabalho agênticos.

Quando se dá a uma IA uma instrução de alto nível — "aplica este template", "configura esta integração", "migra esta configuração" — ela vai agir sobre o contexto mais disponível: o que consegue inferir do estado actual dos ficheiros, o que se lembra do início da sessão, o que a instrução faz corresponder por padrão vindo do treino. Ler documentação de fonte-de-verdade é um acto deliberado e sequencial. Não acontece automaticamente, a menos que seja construído no fluxo de trabalho.

O intervalo entre "a IA compreendeu o espírito da tarefa" e "a IA leu a especificação autoritativa" é onde vivem os erros silenciosos.

Em termos de produto: o assistente de IA está a optimizar para a conclusão da tarefa, não para a correcção face à especificação. Não são a mesma coisa.

O que mudei

Duas intervenções, ambas estruturais:

Primeira: Adicionei uma regra à memória persistente — antes de aplicar qualquer template ou padrão externo, ler primeiro os ficheiros de instruções desse repo. Sempre. Não como sugestão, como primeiro passo obrigatório.

Segunda: Estou a construir uma skill /read-context — uma verificação prévia que corre antes de qualquer tarefa de aplicação de template. Lê o SYSTEM_PROMPT.md, o CLAUDE.md e o documento de regras de base, e depois resume o que encontrou antes de avançar. A IA não pode saltar este passo porque é o primeiro passo.

A correcção mais profunda é tornar o comportamento correcto o caminho de menor resistência. Se o fluxo de trabalho exige leitura antes de acção, o modo de falha exige esforço para se reproduzir.

O que isto significa se estiveres a construir com IA

A assunção de que "a IA sabe o que quero dizer" é confortável e normalmente inofensiva. Até deixar de ser.

Os casos em que falha são precisamente aqueles em que o risco é maior: integrar um novo repo numa estrutura de governança, migrar uma configuração crítica, aplicar um template de conformidade. Tarefas em que um resultado errado mas plausível é mais perigoso do que um erro óbvio.

A correcção não é um melhor prompt no momento. É construir fluxos de trabalho em que a IA é forçada a ler a fonte autoritativa antes de agir — sem depender da memória, sem inferir a partir do contexto, sem fazer correspondência de padrões de sessões anteriores.

A correcção face à especificação é uma propriedade do fluxo de trabalho, não do modelo.

Qual é o teu mecanismo forçador?

Se estás a integrar IA em fluxos de trabalho técnicos com risco real, que mecanismo a força a ler a especificação antes de agir — em vez de assumir que já sabe?

Fontes

Anthropic, Claude system prompts and persistent memory behaviour — claude.ai/docs, 2025
Andrew Ng, Agentic AI Design Patterns — deeplearning.ai, 2024
Personal incident log — gtc-portfolio governance template, March 2026