A Falha do Seu Agente É um Relatório sobre o Seu Código

Quase 16 mil merges já foram barrados dentro da Cloudflare por um sistema chamado Codex, que lê pull requests contra as RFCs de engenharia da empresa. Desde a criação dele, no começo deste ano, foram sinalizadas perto de 230 mil violações. Só uma parte dessas violações tem poder de impedir um merge, e qual parte é uma decisão que um humano tomou deliberadamente, RFC por RFC.

Essa distinção é o produto inteiro. Na mesma semana, Matthew Phillips publicou como os mantenedores da Astro levaram a contagem de issues abertas de mais de 200 para cerca de 30, com expectativa de chegar a zero, a primeira vez que o repositório veria zero issues abertas em mais de cinco anos de história. Dois problemas diferentes, duas empresas diferentes, e o mesmo movimento de fundo: os dois times tratam o que o agente produz como uma medição da organização, e não como um veredito sobre o modelo.

Aprovado e obrigatório são dois estados distintos

O corpus de RFCs da Cloudflare é o que a maioria das organizações de engenharia já tem em alguma forma. Documentos de design, páginas de padrões, um wiki de arquitetura. O que eles acrescentaram foi uma máquina de estados em cima disso. Um padrão pode estar aprovado, ou seja, a organização concorda com ele. Um padrão pode estar obrigatório, ou seja, violar suas afirmações do tipo MUST impede a aprovação de um pull request.

Escrever o padrão não é o ato de governança. Promovê-lo de aprovado para obrigatório é. Essa promoção é o momento em que um humano aceita o custo operacional da regra: os merges que ela vai travar, as discussões que vai iniciar, as exceções que vai exigir. Quase 16 mil aprovações retidas são a etiqueta de preço dessa decisão, tornada visível.

A maior parte dos times que adota revisão de código com IA pula essa etapa. Aponta um modelo para um guia de estilo e deixa comentar tudo, o que produz uma superfície de revisão que ninguém consegue calibrar. Os achados consultivos e os achados bloqueantes se misturam em um só fluxo de sugestões, e os engenheiros aprendem a rolar a página passando por cima de todos. Separar os dois estados dá à organização um botão que ela de fato consegue girar, uma RFC de cada vez, com uma consequência mensurável presa a cada giro.

Já argumentamos, em padrões de equipe como governança executável, que arquivos de instrução são ferramentas de desenvolvimento e merecem a mesma disciplina de revisão que o código. A etapa de promoção é como essa disciplina se parece quando chega em produção. É também a resposta à objeção levantada em governança mora no backlog: imposição tem custo, e uma máquina de estados é como se agenda o pagamento dele.

O corpus não entra na janela de contexto

A Cloudflare tem mais de 60 RFCs, número que segue crescendo. Eles rejeitaram a implementação óbvia, que seria entregar o corpus inteiro ao modelo e pedir um julgamento sobre o diff. A razão declarada é que o volume do corpus imporia muito estresse à janela de contexto.

O desenho que foi para produção é outro: cada RFC é decomposta em afirmações normativas individuais, extraídas para JSON, e cada afirmação carrega um slug estável. O revisor avalia um pull request contra um conjunto selecionado de afirmações, não contra uma pilha de prosa. Como o slug é estável, uma violação registrada em março continua identificável em agosto mesmo depois de a RFC ao redor ter sido reescrita.

Essa estabilidade é o que transforma o número de 230 mil em medição, e não em log. Dá para perguntar qual afirmação dispara mais, qual gera mais exceções, qual foi promovida a obrigatória e em seguida produziu silenciosamente uma fila de contornos. Um corpus enfiado num prompt não entrega nada disso. Entrega uma opinião por diff e nenhuma forma de comparar opiniões ao longo do tempo.

A Cloudflare roda a mesma arquitetura em outras duas superfícies. Um revisor de especificações já avaliou perto de 600 designs técnicos em mais de 3.200 invocações desde maio de 2026, com achados distribuídos em maiores (65%), menores (29%) e críticos (6%). Um revisor de relatórios de incidente já analisou mais de 200 relatórios, e o dado interessante ali não é o volume: 93% cobriam incidentes de baixo impacto, internos ou declarados preventivamente. Isso é uma afirmação sobre quais incidentes uma organização documenta, e saiu de um pipeline de revisão que não foi construído para responder a essa pergunta.

A taxonomia de falhas da Astro aponta para o repositório

A fábrica de software da Astro roda quatro subagentes isolados sobre uma issue que chega ao GitHub: Reproduzir, Diagnosticar, Verificar, Corrigir. Cada um passa um report.md adiante. O isolamento é deliberado, e Phillips explica o porquê: evitar o viés frequente de LLMs de forçar uma solução quando o bug pode nem existir. Um agente que passou 40 turnos diagnosticando vai encontrar uma correção, com ou sem motivo para ela. Cortar o contexto entre as etapas elimina o custo afundado.

O sistema guarda quase nenhum estado. Dois rótulos, triage needed e fix verified. A thread da issue é a memória. Quem reportou originalmente confirma a correção antes de qualquer pull request ser aberto, o que significa que o sinal de aceite vem de quem tem o caso que falha, não do agente que escreveu o patch.

A parte que vale copiar é o que acontece quando o pipeline falha. A Astro classifica toda falha de agente em um de três defeitos do próprio código: abstrações opacas, documentação ausente, testes insuficientes. Phillips coloca a inferência de forma direta: se um agente não consegue interpretar as fronteiras entre componentes, provavelmente os desenvolvedores humanos também têm dificuldade com a estrutura do código.

A correção vai para o repositório. Não para o prompt.

A inversão

Isso inverte o reflexo padrão. Quando um agente produz algo errado, o instinto é ajustar as instruções, acrescentar um exemplo, trocar de modelo, aumentar o orçamento de raciocínio. Tudo isso trata o agente como a unidade sob teste.

Lida ao contrário, a falha vira diagnóstico gratuito sobre um sistema que já é seu. Um agente que não consegue dizer onde um módulo termina e outro começa está reportando uma abstração sem fronteira observável. Um agente que chuta o contrato de uma função está reportando comportamento não documentado que as pessoas recém-contratadas também estão chutando, mais devagar e de forma menos visível. Um agente cuja correção quebra algo alheio ao problema está reportando uma suíte de testes que não defende aquilo que foi quebrado.

Nenhuma dessas leituras exige confiar no julgamento do modelo. Exige apenas reparar onde ele trava. A confusão de uma pessoa júnior carrega o mesmo sinal, mas você a recebe uma vez por contratação, filtrada pela relutância dela em parecer lenta. Um agente trava a cada execução, em log, no volume que você apontar para ele.

Este é o complemento ao argumento de contenção descrito em o padrão gaiola. Contenção limita o estrago que um agente pode causar enquanto trabalha. Ler o log de falhas revela o que esse trabalho descobriu sobre o código embaixo.

Faça isto agora

Pegue as últimas vinte vezes em que um agente produziu algo que você rejeitou no seu repositório. Descarte as recusas do modelo e as APIs alucinadas; fique com os casos em que ele escreveu código plausível e errado para o seu sistema. Classifique cada um nos três baldes da Astro: a fronteira estava confusa, o comportamento não estava documentado, o teste não existia. Conte.

O balde que vencer é o seu próximo ticket de refatoração, sustentado por evidência que um humano levaria um trimestre para produzir. Se aparecer um quarto balde que nenhum dos três descreve, dê um nome a ele e siga contando. Essa é a taxonomia de defeitos da sua própria organização se formando.

Depois pegue o único padrão sobre o qual seu time mais discute e pergunte em qual estado ele está. Se todo mundo concorda com ele e nada o impõe, ele está apenas aprovado. Decida em voz alta se ele deveria ser obrigatório, e aceite que a resposta pode ser não. Uma regra que ninguém aceita ver travando um merge é uma regra que a organização já recusou ter.

Fontes

Cloudflare. “How Cloudflare enforces engineering standards using AI.” Agosto de 2026.
Cloudflare / Astro. “How we built a software factory to drive Astro’s GitHub issue count to zero.” Agosto de 2026.

A Victorino ajuda organizações de engenharia a transformar logs de falha de agentes em um plano priorizado de correção do código: contato@victorino.com.br | www.victorino.com.br