Specification-first convergence with an AI coding agent: a case study of dismantling a core architectural invariant across 189 files in a 717k-line codebase with no test oracle and no human code review

No mundo do software, os programas são construídos como cidades vastas e intrincadas. Eles consistem em milhões de linhas de instruções que dizem a um computador como se comportar, como lembrar das coisas e como reagir quando um usuário clica em um botão. Por décadas, a maneira padrão de alterar essas cidades tem sido enviar um arquiteto humano para inspecionar cada novo tijolo que uma inteligência artificial possa assentar. Esta revisão humana é considerada essencial porque as conexões entre diferentes partes de um programa são tão profundas e emaranhadas que um pequeno erro em um canto pode causar um colapso em outro. Quando uma mudança é grande o suficiente para tocar centenas de arquivos de uma vez, a tarefa de verificar o trabalho torna-se um gargalo; nenhum ser humano consegue manter todo o mapa das mudanças em sua mente ao mesmo tempo. Essa limitação levou muitos a acreditar que, para as mudanças arquitetônicas mais complexas, o único caminho seguro é derrubar a estrutura antiga e construir uma nova do zero, um processo que é lento, caro e arriscado.

Um estudo de caso recente desafia a ideia de que a revisão humana é a única maneira de garantir a segurança em mudanças tão massivas. Ele explora um método onde o foco muda de verificar o produto acabado para aperfeiçoar a planta antes que um único tijolo seja assentado. Em vez de pedir a uma inteligência artificial que escreva código e depois esperar que um humano encontre os erros, esta abordagem pede à máquina que primeiro escreva uma descrição formal detalhada do que ela pretende fazer exatamente. Essa descrição é então rigorosamente verificada contra o código existente, não para ver se o código funciona, mas para ver se o plano em si faz sentido. O plano é refinado, corrigido e congelado até que pare de produzir achados. Somente então a máquina começa a construir e, mesmo assim, ela é constantemente auditada contra esse plano congelado. O resultado é uma demonstração de que uma mudança arquitetônica massiva e complexa pode ser concluída sem que um único humano sequer leia o código gerado, desde que o processo de definir e verificar a intenção seja robusto o suficiente.

O experimento ocorreu dentro de uma aplicação de software proprietária de grande porte usada para assistência de codificação por inteligência artificial. O sistema, escrito em uma linguagem chamada TypeScript, continha mais de 717.000 linhas de código espalhadas por quase 3.650 arquivos. Era uma peça de software viva e pulsante, usada diariamente, não um modelo teórico. A tarefa atribuída ao agente de inteligência artificial era desmantelar uma regra central que governava o sistema desde a sua criação. Esta regra, conhecida como um invariante, garantia que, sempre que um usuário iniciasse uma conversa com a IA, a janela exibindo essa conversa permaneceria aberta durante toda a duração da requisição. Se o usuário fechasse a janela, a conversa morria. O objetivo era quebrar essa regra: o usuário deveria ser capaz de fechar a janela, e a conversa continuaria rodando em segundo plano, pronta para ser reaberta e retomada exatamente de onde parou, sem perder nenhum dado ou repetir nenhuma palavra.

Esta mudança específica era considerada quase impossível de ser alcançada através de refatoração padrão. Na avaliação do autor, a interdependência do código era tão apertada que modificar o tempo de vida de uma conversa sem quebrar todo o sistema normalmente exigiria uma reescrita completa dos componentes afetados. A tarefa envolvia gerenciar questões complexas de tempo, como o que acontece quando uma janela fecha enquanto dados ainda estão sendo transmitidos, e como reatachar um usuário a um fluxo ao vivo que tem rodado sem ele. Para resolver isso, o autor empregou um protocolo de cinco fases projetado para manter a inteligência artificial em um trilho estrito. O processo começou com o agente analisando a requisição e produzindo uma especificação formal, um documento detalhado descrevendo exatamente como a mudança deveria funcionar.

A parte mais crítica do processo foi a fase de refinamento. O agente foi solicitado a pegar sua própria especificação e verificá-la contra o código-fonte real, procurando por quaisquer contradições ou detalhes ausentes. Esta não foi uma verificação de uma única vez. O agente passou por quatorze ciclos desta auditoria. Em cada ciclo, ele encontrava erros em seu próprio plano — talvez um arquivo que havia esquecido de atualizar, ou uma dependência que havia mal compreendido — e reescrevia a especificação para corrigir o erro. Ao longo desses quatorze ciclos, o plano foi corrigido aproximadamente oitenta e cinco vezes, expandindo o escopo da mudança de 110 arquivos para 160 arquivos à medida que conexões ocultas eram descobertas. Ao final do décimo quarto ciclo, a especificação estava congelada. Era uma planta fixa que havia sido auditada contra a realidade da base de código até que o ciclo final não retornasse mais achados, ponto no qual foi travada como a referência para todas as fases subsequentes.

Com o plano travado, o agente passou para a fase de implementação. Ele foi instruído a gerar as alterações de código necessárias para corresponder à especificação congelada. O agente recusou-se a fazer mudanças parciais, identificando corretamente que uma migração inacabada quebraria o sistema. Em vez disso, executou o trabalho em três etapas distintas e confirmadas. Uma vez que o código foi escrito, a fase de verificação começou. Assim como o plano havia sido verificado contra o código, o novo código agora era verificado contra o plano congelado. O agente executou dezessete ciclos desta auditoria, comparando o código real na tela com as regras escritas na especificação. Em cada ciclo, ele encontrava e corrigia desvios, corrigindo falhas arquitetônicas sutis que um humano poderia ter perdido. Ao longo dessas dezessete rodadas, o agente corrigiu 116 defeitos no próprio código. O processo parou apenas quando duas auditorias consecutivas retornaram zero erros, confirmando que o código correspondia ao plano dentro do critio de convergência definido.

Toda a operação tocou 189 arquivos, com um total de 288 arquivos alterados ao incluir a extração do código antigo. As mudanças envolveram mais de 34.000 novas linhas de código e a exclusão de mais de 16.000 linhas. Notavelmente, esta reestruturação massiva foi concluída em três dias. O custo do processamento de inteligência artificial necessário para a tarefa foi de 2.430 dólares americanos. Durante todo o período de três dias, o programa nunca foi executado uma única vez por um humano. A primeira vez que o software foi realmente executado foi após o décimo sétimo ciclo de verificação, quando o autor finalmente testou o novo comportamento.

O resultado foi um sucesso. Quando o programa foi lançado, o novo comportamento funcionou exatamente como a especificação descrevera. Um usuário podia iniciar uma conversa, fechar a janela, e a conversa continuaria rodando em segundo plano. Quando o usuário reabria a janela, a conversa retomava instantaneamente, sem perda de dados ou duplicação de texto. Um novo botão de parada apareceu na barra lateral, permitindo que o usuário matasse o processo em segundo plano, se necessário. Os testes automatizados existentes, que rodavam no software há anos, não apresentaram falhas, indicando que o novo sistema não quebrou nenhuma das funcionalidades antigas. O software foi lançado ao público como a versão 2.3.0 e, nas aproximadamente trinta sessões de uso que se seguiram ao lançamento, nenhum bug foi observado.

Este estudo de caso não afirma que a inteligência artificial pode agora substituir engenheiros humanos em todos os cenários, nem sugere que este método funcione para todo tipo de problema. O autor é cuidadoso ao notar que este foi um caso único e específico em uma única base de código, e que os resultados não podem ser automaticamente assumidos como aplicáveis a outros sistemas ou outras tarefas. O estudo explicitamente descarta a ideia de que um conjunto pré-existente de testes poderia ter resolvido este problema, porque o comportamento desejado não existia antes da mudança ser feita. Não havia uma resposta "correta" para verificar no código antigo; a correção tinha que ser definida do zero. O estudo também reconhece que o processo dependeu de um modelo de inteligência artificial específico e poderoso, e que os resultados podem diferir com modelos mais fracos.

A significância do trabalho reside em sua demonstração de uma nova maneira de gerenciar a complexidade. Ao deslocar o fardo do controle de qualidade da inspeção do produto final para a definição e verificação rigorosa do plano, os pesquisadores mostraram que uma máquina poderia navegar por um campo minado de códigos interdependentes sem intervenção humana. A chave não foi que a máquina fosse infalível, mas que o processo permitiu que ela capturasse seus próprios erros repetidamente antes que se tornassem permanentes. A especificação foi desafiada quatorze vezes, e o código foi verificado dezessete vezes, criando um loop de autocorreção que impulsionou o sistema em direção a uma correspondência entre intenção e realidade baseada em uma regra de parada empírica. Os logs de todo este processo, abrangendo mais de 1.500 páginas, foram publicados para que qualquer pessoa possa inspecionar, oferecendo um olhar transparente sobre como uma máquina pode desmantelar uma regra arquitetônica central e reconstruí-la, tijolo por tijolo, sem nunca precisar que um humano olhe por cima de seu ombro.