[ARTIGO] Como eliminamos a maior parte dos erros de agentes de IA em produção que fazem deploy com três subsistemas: Memória, Vault e Sonhos · macnator

Olá pessoal, vou deixar para vocês um roadmap de implantação de uma stack ou harness para você poder alinhar seu trabalho com Agentes de IA que fazem deploy, da forma que testamos e implementamos, os mecanismos descritos aqui são aguinosticos de linguagem então você pode produzir isso em cima da sua linguagem preferida, isso pode ser implementado direto em sistemas de harness e até mesmo de um opencode da vida.

Um agente de IA autônomo editando sistemas reais não falha de forma aleatória. Ele falha de forma previsível, repetindo os mesmos padrões de erros em sessões diferentes. Descobrimos isso da pior forma possível: auditando o nosso próprio trabalho.

Auditamos 392 sessões de desenvolvimento (~3 meses de operação em produção) e encontramos padrões de erro recorrentes e mensuráveis. Os mais comuns, em ordem de frequência:

48% das sessões pularam o protocolo básico de sessão (registro, pendências, encerramento);
42% das sessões que envolveram edição editaram arquivos de produção fora do fluxo seguro;
36% declararam uma entrega como "pronta" sem testar o fluxo real;
30% afirmaram a causa de um bug sem nenhuma evidência, editando código com base em hipótese não confirmada;
18% validaram interfaces visuais em uma única resolução de tela;
além de uma família menor, porém cara: edições que quebravam o próprio sistema (nome errado de função, sintaxe inválida, rota duplicada) por falta de validação entre um passo e o outro.

A lição central da auditoria é desconfortável: as regras já estavam escritas. O agente tinha um manual. E mesmo assim os erros aconteciam, sessão após sessão. Texto educa, mas não obriga. O que obriga é mecanismo físico e determinístico.

Com base nessa evidência, desenhamos três subsistemas que hoje rodam em produção: uma Memória (indexada e de consulta obrigatória), um Vault (que torna impossível editar fora do fluxo seguro) e os Sonhos (subagentes que auditam as próprias sessões e consolidam o aprendizado). Neste artigo explico cada um, passo a passo, de forma agnóstica de stack e de modelo.

Por que instruções em texto falham

O comportamento observado é simples: sob pressão de entregar resultado, o agente otimiza o caminho mais curto. Se a regra de segurança está apenas escrita num manual, "pular" a regra é uma escolha disponível - e o modelo a faz. O padrão "edição fora do fluxo seguro" virou praticamente universal em sessões com edição, apesar da regra estar escrita em negrito no topo do manual.

A mesma auditoria mostrou o contrário também: quando existia um mecanismo (uma ferramenta de validação, um script de deploy, um teste automático), o erro sumia naquele ponto. Conclusão operacional: toda lição importante deve virar um de três artefatos - uma memória indexada, uma salvaguarda mecânica ou uma ferramenta determinística. Nunca apenas texto.

Subsistema 1 - Memória (Cortex): conhecimento indexado com consulta obrigatória

O problema

Um agente sem memória adivinha. Adivinha caminhos de arquivo, nomes de serviço, portas, convenções de código, textos de interface. Cada adivinhação errada é um bug em potencial - e o padrão de 30% de "hipóteses sem evidência" era exatamente isso: o agente chutando onde estava a causa de um problema e editando o arquivo errado, às vezes três ou quatro vezes, antes de achar o real.

O design

Uma base de conhecimento organizada por área: cada página do produto, cada módulo de código, cada serviço tem um cartão de memória contendo o mapa real - onde está o código, como funciona, quais as convenções, quais as armadilhas conhecidas, o que já foi tentado e por quê.

Três características tornam essa memória eficaz:

Busca determinística e barata. Nada de depender de um modelo caro por consulta. Um motor de similaridade simples e offline (baseado em características e palavras-chave) devolve o cartão certo em milissegundos, com custo praticamente zero.
Consulta obrigatória antes de agir. A ordem de decisão do agente é fixa: primeiro consultar a memória da área, depois ler o código, nunca o contrário. O cartão acelera a localização; a leitura completa do código continua sendo a regra suprema.
Atualização obrigatória depois de agir. Toda mudança relevante volta para a memória (com versão incrementada). Memória desatualizada é pior do que memória ausente: ela faz o agente confiar num mapa errado.

Passo a passo de implantação

Liste as áreas críticas do sistema: páginas públicas, telas autenticadas, serviços, módulos de infraestrutura.
Escreva um cartão por área, com fatos verificáveis (nunca opiniões): arquivos, rotas, convenções, armadilhas, histórico de incidentes daquela área.
Indexe os cartões num motor de busca determinístico, com limite mínimo de relevância (abaixo do corte, o resultado é descartado - melhor nenhum mapa do que um mapa errado).
Torne a consulta obrigatória no protocolo de início de qualquer trabalho.
Crie a regra simétrica: terminou de alterar uma área, atualizou o cartão dela.
Meça: erros por adivinhação de caminho/nome devem cair nas semanas seguintes.

Efeito observado

Depois da memória indexada, o custo de re-descobrir o sistema a cada sessão caiu drasticamente: sessões mais curtas, menos contexto consumido, menos "hipóteses" chutadas. O agente passa a errar menos por ignorância - que era a maioria dos erros.

Subsistema 2 - Vault: tornar impossível editar fora do fluxo seguro

O problema

O erro mais caro de todos é editar o arquivo errado ou com erro, sem validação e sem cópia anterior, e como manter copia anterior sem backup manual a cada alteração? Foi o padrão mais universal da auditoria: praticamente todas as sessões com edição o cometiam. E o pior efeito não é o bug em si - é que, sem cópia anterior, a correção vira arqueologia.

O design

Três camadas, nesta ordem de importância:

Camada 1 - Gate físico de edição. O editor de código é configurado com uma lista de permissão invertida: por padrão, TUDO é negado; apenas uma única pasta de trabalho é permitida. A negação é silenciosa - o editor simplesmente recusa, sem pedir autorização humana item a item (pedir autorização por edição destrói a produtividade e devolve o problema ao humano). Veja bem, aqui esta o pulo do gato, O caminho errado não é proibido por disciplina: ele não existe.

Camada 2 - Cópia fiel sincronizada. Todo arquivo editável tem uma cópia baseline num repositório. Antes de cada edição, a cópia é ressincronizada com a produção atual. Isso resolve um bug sutil e real: comparar alterações contra um snapshot desatualizado (que esconde código ausente ou corrompido). Com a cópia fiel, o backup existe por construção - mesmo quando o backup externo falha ou atrasa, há sempre uma versão para comparar e restaurar.

Camada 3 - Fluxo obrigatório de cinco passos. Sincronizar baseline, copiar para a área de trabalho, editar, validar integridade, publicar (com cópia de volta para produção e conferência de igualdade entre as duas pontas). A ferramenta que executa o fluxo é uma ponte direta, sem IA - comandos determinísticos de arquivo e banco.

Passo a passo de implantação

Liste TODA a superfície editável do sistema e registre uma cópia baseline de cada arquivo (uma tarde de trabalho).
Configure o gate do editor com allow-list: padrão negado, permitida apenas a pasta de trabalho, mais as exceções documentadas (se houver).
Automatize o fluxo numa ferramenta de linha de comando sem IA: sincronizar, copiar, comparar, validar, publicar.
Adicione um validador pré-publicação: antes de reiniciar qualquer serviço, o código editado precisa passar numa checagem de sintaxe automática - se falhar, o reinício é abortado.
Teste o gate de verdade. Não confie na configuração: tente editar um arquivo de produção (deve falhar) e um arquivo da área de trabalho (deve passar). Guarde o registro.
Confira a igualdade entre repositório e produção depois de cada publicação.

Uma lição técnica que pagamos para aprender: o casamento de padrões de permissão do editor usa caminhos relativos à raiz do workspace, não caminhos absolutos. A primeira versão do nosso gate usava caminhos absolutos - o bloqueio funcionava, mas as exceções permitidas não, e o sistema ficou travado até diagnosticarmos. Verifique o formato exato dos caminhos no log do seu editor antes de confiar no gate. Esse é exatamente o tipo de detalhe que uma auditoria de sessão (subsistema 3) revela.

Efeito observado

A família "edição fora do fluxo seguro" caiu para zero no dia em que o gate entrou no ar - não ficou "menos provável", ficou impossível. De quebra, ganhamos um backup estrutural permanente e um validador que aborta publicação inválida antes de derrubar serviço.

Subsistema 3 - Sonhos: subagentes que auditam as próprias sessões e consolidam o aprendizado

O problema

A lição aprendida ontem morre com a sessão de ontem. O mesmo erro volta em sessões diferentes, com agentes diferentes, semanas depois. Manual não resolve, como já vimos. É preciso um processo que converta experiência em estrutura.

O design

Um processo periódico e separado - chamamos de sonhos - que roda depois do trabalho, nunca durante. Subagentes autônomos e somente-leitura analisam as sessões gravadas e produzem consolidação de aprendizado.

Por que subagentes separados? Três motivos: contexto limpo (não herdam o viés nem a pressão da sessão original), custo baixo (rodam em lote, em paralelo, sobre textos exportados) e independência (analisam o trabalho de outros como analisariam o de terceiros - sem defender a própria entrega).

Passo a passo de implantação

Grave as sessões de forma estruturada: mensagens, ferramentas usadas, decisões, erros e correções. É a matéria-prima de tudo.
Rode os analisadores em lote e em ciclos: cada subagente recebe um recorte (um lote de sessões) e um questionário fixo - o que foi feito, quais erros ocorreram, com que evidência, qual o desfecho.
Consolide os resultados por período: tabelas de padrões com frequência e tendência. Sem prosa: número, evidência, desfecho.
Classifique cada padrão confirmado em uma de duas saídas possíveis: lição de memória (vira cartão no subsistema Memória) ou salvaguarda mecânica (vira regra ou ferramenta no subsistema Vault). A regra de ouro: nunca vira apenas texto.
Exija aprovação humana antes de aplicar qualquer mudança. O sonho propõe; o dono aprova. Nenhuma regra entra em produção por autoaprovação.
Meça a reincidência do padrão no período seguinte. Se não caiu, a salvaguarda foi mal desenhada - o ciclo recomeça.

Casos reais do nosso ciclo

Três exemplos genéricos do que esse processo produziu na nossa operação:

"Declarar pronto sem testar" (36% das sessões) virou um script de validação de entrega: nenhuma comunicação de "pronto" é aceita sem o teste do fluxo real na mesma rodada. A regra já existia como texto; o script a tornou obrigatória.
"Quebra autoinfligida por edição sem validar" virou um script de reinício seguro: compila e valida os arquivos editados antes de reiniciar o serviço; se a validação falha, o reinício é abortado. O erro que derrubou o sistema duas vezes não acontece mais por esse caminho.
"Edição fora do fluxo seguro" virou o gate físico descrito no subsistema 2. Zero ocorrências desde então.

A matemática do investimento inicial

O custo de implantar os três subsistemas é pequeno e pago uma vez:

Memória: escrever os primeiros cartões por área (alguns dias de engenharia).
Vault: baseline da superfície editável (uma tarde), gate de permissões (um dia), ferramenta de fluxo e validador (um dia).
Sonhos: exportação estruturada das sessões (um dia) e a primeira rodada de análise em lote (custo marginal baixo - subagentes processam texto).

Contra esse custo fixo, a redução de custo variável recorrente:

Cada bug autoinfligido em produção custa uma sessão inteira de correção, além do risco de interrupção do serviço e da confiança do cliente.
Na nossa auditoria, 36% das sessões tinham retrabalho por entrega não validada e, num período do histórico, 12 de 26 sessões eram correção de regressão autoinfligida - quase metade da capacidade de engenharia queimada apagando fogo que nós mesmos acendemos.
O gate elimina uma família inteira de erro de uma só vez (de "provável" para "impossível"), o que nenhuma revisão de código alcança.
A memória indexada reduz o custo de re-descobrir o sistema a cada sessão: sessões mais curtas, menos contexto, menos tokens.
O sonho converte incidente em ativo: cada falha vira uma regra que previne a próxima falha do mesmo tipo.

A fórmula é simples: um investimento fixo pequeno, aplicado uma única vez, elimina uma fração constante dos custos variáveis recorrentes. Para qualquer sistema editado diariamente por agentes, o ponto de equilíbrio chega em poucas semanas - no nosso caso, chegou na primeira quinzena.

Checklist de implantação em ordem recomendada

Semana 1

Ative a gravação estruturada das sessões.
Liste as áreas críticas e escreva os primeiros cartões de memória.
Registre a baseline de todos os arquivos editáveis.

Semana 2

Configure o gate de permissões allow-list no editor.
Automatize o fluxo de edição (sincronizar, copiar, editar, validar, publicar, conferir).
Crie o validador pré-publicação e o reinício seguro.

Semana 3

Rode a primeira rodada de sonhos: análise em lote das sessões gravadas.
Aprove (humanamente) as primeiras regras e ferramentas derivadas dos padrões confirmados.

Mês 2 em diante

Meça a reincidência por padrão.
Itere: o que caiu, vira rotina; o que não caiu, vira salvaguarda melhor desenhada.

Regras de ouro de modelos

Texto educa, mecanismo obriga. Toda lição aprovada vira memória indexada ou salvaguarda mecânica - nunca apenas parágrafo num manual.
A negação deve ser silenciosa. Pedir autorização humana por edição devolve o trabalho ao humano e mata a produtividade. O caminho errado deve simplesmente não existir.
O agente nunca valida o próprio trabalho sozinho. O teste final é sempre um processo separado, determinístico, rodando na mesma rodada da entrega.
A auditoria precisa ser de fora para dentro. Quem analisa as sessões não pode ser quem as executou - por isso os subagentes dos sonhos são separados e somente-leitura.
Memória desatualizada é pior que memória ausente. Sincronizar antes de usar e atualizar depois de mudar, sempre.

Conclusão

A maior sacada: o comportamento dos agentes é estatisticamente previsível - e eliminável em famílias

Se há uma descoberta que separa o antes do depois nesta jornada, é esta: depois de algumas dezenas de sessões auditadas, o comportamento do agente deixa de parecer caótico. Ele forma uma distribuição previsível de tipos de erro. Os mesmos tipos voltam, com frequência mensurável, independentemente da tarefa, do dia. O erro individual é imprevisível; a família do erro não é.

E aqui está a distinção que vale dinheiro. Memória ajuda na descoberta rápida do sistema: reduz o custo de re-descobrir caminhos e convenções a cada sessão, encurta contexto, diminui adivinhação. Isso é eficiência. Mas catalogar os padrões de repetição dos tipos de erro é outra coisa. Não se trata de dizer "tivemos trinta erros de edição neste mês". Trata-se de descobrir qual padrão de comportamento causou exatamente esses trinta erros de edição - o que os trinta tinham em comum antes de cada falha. Esse padrão causal é o ativo.

Quando o padrão é identificado, uma única ferramenta determinística que impede esse padrão elimina a família inteira de uma vez. Os trinta erros não caem para vinte, nem para cinco: caem para zero, e permanecem zero. Não porque o agente ficou mais cuidadoso, mas porque o caminho que levava ao erro deixou de existir. Foi exatamente o que aconteceu com a nossa pior família: edição fora do fluxo seguro, presente em praticamente todas as sessões com edição, zerou no dia em que o gate físico entrou no ar.

A consequência estratégica é ainda maior: isso permite maximizar modelos mais baratos. Modelos menores e mais baratos erram mais em tarefas abertas e sem guarda-corpos - é esperado. Mas se as famílias de erro estruturais estão fechadas por mecanismos determinísticos, o erro residual do modelo fica barato de gerenciar: ele se concentra em julgamentos pontuais, que uma auditoria simples pega e corrige. A engenharia de ferramentas passa a fazer o trabalho que antes se comprava com um modelo maior e mais caro. O modelo barato fica confiável por design - porque a confiabilidade deixa de vir do modelo e passa a vir da infraestrutura que o cerca. Foi assim que conseguimos sustentar qualidade com custo de inferência decrescente, em vez de crescente.

Nós rodamos os três subsistemas em produção: memória indexada por área, gate físico de edição com fluxo de cinco passos e auditoria periódica das próprias sessões feita por subagentes. O resultado foi a queda mensurável de famílias inteiras de erro - inclusive a pior delas, que era praticamente universal - com um custo de implantação pago em poucas semanas de operação.

Se você roda agentes de IA editando sistemas reais, o convite é simples: grave as sessões, meça os padrões e transforme cada lição em mecanismo. O resto é consequência.