Testes de especificação corrigiram a deriva arquitetural: um agente ajustou 637 tamanhos de fonte de uma só vez

Existe um experimento conhecido: você pede ao ChatGPT que faça uma cópia exata de uma imagem, sem alterar nada, e repete isso 101 vezes. No fim, a fotografia de Dwayne Johnson se transforma em uma massa cartunesca. Cada etapa isolada é quase fiel, mas o resultado acumulado é algo completamente diferente.

O mesmo acontece com o código mantido por um agente de IA. O autor da análise chama isso de deriva arquitetural. O exemplo do frontend é o mais evidente: a fonte está definida e é a mesma em todos os lugares, mas cada página adota tamanhos próprios, e o estilo geral do site se desfaz. O princípio vale para qualquer área de desenvolvimento: a fonte da verdade começa a divergir.

A verdade está na especificação, não no código

O autor não lê o código; ele controla apenas as especificações. A lógica é a seguinte: a especificação é o projeto técnico, o código é a peça, e a peça deve ser comparada ao projeto, não a outra peça. Duas fontes da verdade geram caos.

Toda a documentação fica na pasta docs, na raiz do projeto. Em 5 de novembro de 2026, ela continha 7.478 arquivos .md, distribuídos por 11 níveis de aninhamento. Em 95,3% das pastas havia no máximo 7 arquivos; em 97,4%, no máximo 9. É a regra de “7 mais ou menos 2”: assim, tanto pessoas quanto agentes entendem com mais facilidade onde cada coisa está. Os agentes escrevem e leem as especificações, enquanto uma pessoa as consulta em um formato conveniente no painel administrativo.

Por exemplo, todas as regras de tipografia ficam em um único arquivo typography.md. Ele contém 22 funções, cada uma com família tipográfica, tamanho para desktop e dispositivos móveis, peso e cor. Um parágrafo de artigo, por exemplo, usa Charis 21/30, enquanto o estilo-base usa Inter 14/21. O site inteiro utiliza duas famílias e somente os pesos 400 e 700. A regra principal é que nenhum estado pode existir fora do registro: uma nova combinação exige uma nova linha aprovada por um veredito.

Obrigar a leitura e verificar de forma determinística

Sozinhas, as especificações funcionam de forma probabilística: o agente pode segui-las ou não. Por isso, há duas camadas de proteção.

A primeira é o arquivo AGENTS.md. Ele determina que, antes de uma tarefa, o agente deve ler a documentação da pasta correspondente. Se for necessária uma auditoria dos custos de nuvem, ele acessa a pasta de nuvem e analisa todos os provedores. Segundo a estimativa do autor, as regras não são violadas em 9 de cada 10 casos.

A segunda camada são os testes de especificação para o “décimo caso”. Um teste lê as tabelas de typography.md, reúne os pares de tamanhos permitidos e percorre todo o frontend. Qualquer par fora da especificação faz a compilação falhar, indicando o nome do arquivo e a linha.

O que o teste revelou

Até 6 de novembro, o teste usava uma lista de bloqueio com nove pares obsoletos. Enquanto preparava o artigo, o autor descobriu que havia cerca de 150 pares fora da especificação no código. Em uma única passagem, o agente adequou 637 usos à especificação, acrescentou as 4 linhas que faltavam e reescreveu o teste para usar uma lista de permissões. Esta é a principal lição prática: uma lista de bloqueio detecta apenas aquilo que você já conhece; uma lista de permissões detecta todo o resto.

Se a documentação e o código ainda divergirem, uma ordem de escalonamento ajuda: primeiro os testes, depois a autorreparação em produção—sobre a qual o autor promete um artigo separado—e só então uma pessoa. A tarefa humana não é encontrar o bug, mas entender por que ele passou e fechar essa lacuna.

Limitações e conclusão

A abordagem exige disciplina: é preciso manter milhares de documentos consistentes, e os exemplos do autor tratam principalmente de tipografia, cuja verificação é simples. Escrever testes de especificação para regras de negócio é mais difícil. Trata-se da experiência de um único projeto, os números são autodeclarados e a enquete abaixo do artigo recebeu um voto.

A conclusão prática para quem trabalha com agentes é transferir as regras para especificações legíveis por máquinas, tornar obrigatória no AGENTS.md a leitura delas antes de cada tarefa e transformar os desvios mais frequentes em testes baseados em listas de permissões. O autor publicou no GitHub a própria estrutura—AGENTS.md, CLAUDE.md e uma pasta docs sem código—, permitindo começar com um modelo pronto.