O que um arquiteto deve revisar em código gerado por IA

Em código gerado por IA eu reviso quatro coisas: se o escopo foi respeitado, se a regra de negócio foi respeitada, se as convenções de implementação foram respeitadas e se há erros de implementação. Reviso tudo, sempre. Não existe uma parte do diff que eu tenha deixado de olhar porque a IA costuma acertar.

Os dois casos que conto aqui têm uma coisa em comum: o código funcionava. O problema, nos dois, estava no que ele fazia além do que eu tinha pedido.

Dois diffs que funcionavam

Em Claude, ChatGPT ou Gemini para desenvolvimento: como escolher contei que pedi o mapeamento de um arquivo de importação e recebi, junto com ele, alterações em regras de negócio que não faziam parte do pedido. Não contei quem percebeu. Fui eu, lendo o diff.

O segundo caso aconteceu em um sistema de cliente. A demanda era fechar algumas brechas de segurança, aplicando o motor de verificação de permissões nas rotas da API. A IA aplicou, e os testes unitários e de integração estavam corretos.

Só que ela foi além do pedido. Fechou também portas que não eram brechas: estavam abertas por determinação do negócio. Alguém tinha decidido que aquelas rotas deveriam ficar abertas, e a IA as fechou junto com as outras.

Lendo só a rota, uma porta esquecida e uma porta aberta de propósito se parecem. O que separa uma da outra é uma decisão do negócio, e essa decisão a IA não tinha como ver ali.

Nos dois casos ela fez bem o que foi pedido e fez também o que não foi. E nos dois o excesso caiu no mesmo lugar, a regra de negócio.

O escopo foi respeitado?

O que me faz parar diante de um diff é perceber que tem muito código fora do escopo pedido.

Coloco o escopo em primeiro na lista porque é a pergunta que dá para fazer antes de entender qualquer linha. O pedido era um; o que mudou cabe nele? No primeiro caso cabia o mapeamento. No segundo cabiam as brechas.

Código fora do escopo não está necessariamente errado. Mas é código que ninguém pediu, e por isso é uma decisão que ninguém tomou. Em Como usar IA para programar sem terceirizar seu raciocínio defendi que delegar execução não é delegar pensamento. Mudança fora do escopo é o ponto em que a execução começa a decidir sozinha.

A regra de negócio foi respeitada?

É a primeira coisa que leio de fato no código, e é a parte da revisão que não consigo delegar.

Uso uma segunda sessão de IA só para revisar, que chamo de Revisor. Ela é boa em pegar inconsistências lógicas entre a aplicação, os diagramas e o banco de dados. Quanto ela pega depende da capacidade de raciocínio do modelo que está rodando.

O que é ligado a regra de negócio, só eu pego.

Os testes também não resolveram. No caso das permissões, nenhum deles reprovou o fechamento das portas que deveriam continuar abertas. Um teste confere o comportamento que alguém descreveu nele, e a determinação do negócio não estava descrita em nenhum.

É por isso que essa revisão cabe a quem conhece o sistema além do código. Quem revisa precisa saber por que cada porta está aberta.

As convenções de implementação foram respeitadas?

Depois da regra de negócio, olho se a IA seguiu as diretivas de implementação do projeto.

Parte desse trabalho eu faço antes de o diff existir. São três barreiras: um arquivo de instruções para o agente, o AGENTS.md ou o CLAUDE.md; TDD; e commits focados.

O repositório deste site funciona assim. O AGENTS.md dele exige commits pequenos e coesos no padrão Conventional Commits e TDD quando o plano da tarefa prevê. Traz também uma regra que serve aos dois casos acima: material existente deve ser preservado quando não está explicitamente no escopo da mudança.

O commit focado ajuda na primeira pergunta da lista. Num commit que faz uma coisa só, o que não pertence a ela aparece.

Essas barreiras diminuem o que chega errado à revisão. Não me dispensam dela.

Há erros de implementação?

Por último vem o erro no sentido comum da palavra: a lógica que não fecha, o código que diz uma coisa e o banco de dados que diz outra.

É o ponto em que tenho mais ajuda. Inconsistência lógica é o que a sessão Revisor pega bem. Leio essa parte mesmo assim.

Já aconteceu de eu descartar uma implementação inteira em vez de corrigir. Foi com IAs menos potentes.

A lista

São quatro perguntas, nesta ordem:

1. O escopo foi respeitado?
2. A regra de negócio foi respeitada?
3. As convenções de implementação foram respeitadas?
4. Há erros de implementação?

Para a terceira, as regras escritas ajudam. Para a quarta, a IA revisora ajuda. As duas primeiras dependem de saber o que foi pedido e por que o sistema é como é, e nos dois casos que contei quem viu o problema fui eu, lendo o código.

Código gerado por IA chega funcionando e com os testes passando. Isso não me diz se ele ficou dentro do que pedi, nem se respeitou o que o negócio decidiu.