O PR da IA compila, os testes simples passam e a tela abre. Mesmo assim, a revisão de arquitetura mostra um problema maior no código: a regra de negócio foi parar no controlador, a query aparece duplicada e o erro grava dado sensível no log.

Esse é o momento em que revisar arquitetura antes da IA gerar código vira uma decisão concreta. A ferramenta escreveu rápido, mas a decisão sobre camada, dado, falha e manutenção continuava sem dono claro.

Eu não colocaria todo pedido em uma cerimônia arquitetural pesada. Aqui na Promovaweb, eu separo tarefas localizadas de mudanças que podem alterar o jeito como o sistema será mantido depois.

Direto ao ponto

Revise arquitetura antes da IA gerar código quando a tarefa mexer em regra de domínio, persistência, permissão, integração, tratamento de erro, logging ou dependência externa. Para mudanças pequenas e localizadas, uma issue clara pode bastar, mas mudanças estruturais exigem limite, referência e critério antes de qualquer PR.

Quando revisar arquitetura antes do agente

Nem toda tarefa pede a mesma profundidade, porque corrigir um texto, adicionar um teste simples ou ajustar um estado visual pode seguir com um card objetivo. O risco muda quando a tarefa toca a forma como o sistema organiza responsabilidade.

Eu revisaria arquitetura antes de chamar o agente quando a mudança cria camada nova, altera a fonte oficial de dados, mexe em autorização, integra serviço externo, muda contrato de API, cria fila, registra logs ou trata exceções. Nesses casos, o código é consequência de uma decisão anterior.

Esse recorte conversa com o artigo sobre como conter custo no código gerado por IA. O custo não aparece só na quantidade de linhas, mas também quando a mudança deixa o próximo PR mais difícil de entender.

Separação de responsabilidades não é enfeite

Separar responsabilidades significa deixar claro onde cada decisão mora, com interface apresentando, aplicação coordenando, domínio concentrando regra importante e infraestrutura conversando com banco, fila, e-mail e APIs. Essa divisão pode ser simples, mas precisa existir para orientar manutenção e revisão.

Quando o agente recebe um pedido amplo, ele tende a seguir o caminho mais próximo do arquivo aberto. Se o controlador já mistura tudo, a próxima alteração provavelmente vai reforçar essa mistura; se a regra de negócio já está isolada, a IA tem um trilho melhor para seguir.

O Laravel ajuda quando suas convenções são usadas com critério, e o service container, descrito na documentação oficial do Laravel, é útil para gerenciar dependências e injeção. Ele organiza a resolução de classes, mas a escolha da dependência correta continua sendo decisão do projeto.

Erro e log fazem parte da arquitetura

Erro ruim cria dois problemas, porque pode expor detalhe interno para o usuário e esconder a referência necessária para diagnóstico de quem mantém o sistema. A OWASP Error Handling Cheat Sheet trata erro como parte da segurança da aplicação, e isso muda a prioridade da conversa.

Log também precisa de desenho, porque a OWASP Logging Cheat Sheet reforça que logs de aplicação devem ser consistentes e úteis. O mesmo guia alerta contra registrar segredos, tokens, senha, dado sensível e informação pessoal sem necessidade.

Eu escreveria essa política como parte da especificação da tarefa em projetos com IA, registrando qual evento merece log, qual identificador entra, qual dado precisa ser mascarado e qual falha deve interromper o fluxo. Sem essas respostas, o agente pode espalhar padrões diferentes em cada arquivo.

Camada extra só entra quando reduz manutenção

Arquitetura ruim pode nascer por falta de separação, mas também pode nascer por excesso de abstração. Criar interface, service, repository, factory e evento para uma regra pequena pode deixar o sistema mais difícil de ler.

Eu uso um critério simples: camada extra precisa reduzir acoplamento real, proteger regra importante ou facilitar teste e manutenção. Se ela existe apenas porque parece sofisticada, provavelmente é ruído.

Esse cuidado evita repetir o erro clássico de aprender padrão antes de aprender consequência. O critério não começa pelo padrão que cabe ali, mas pela responsabilidade que precisa ficar isolada para que a próxima mudança seja menor.

Dados precisam ter lugar definido antes do código

O lugar da informação precisa estar definido antes da implementação, porque fonte oficial, cache, fila, evento e relatório têm papéis diferentes. Misturar esses papéis cria divergência silenciosa entre telas, relatórios, integrações e suporte.

Se uma tarefa pede “mostrar status do cliente”, a arquitetura precisa dizer de onde esse status vem, quem pode alterá-lo, qual evento atualiza o valor e qual leitura é apenas derivada. Esse raciocínio está mais detalhado no post sobre como definir o lugar dos dados sem confundir arquitetura.

Esse ponto também encosta em LGPD quando há dado pessoal ou sensível, porque finalidade, acesso, retenção, log e suporte precisam estar claros antes da geração de código. A IA pode implementar a regra, mas a responsabilidade pelo desenho continua humana.

SDD ajuda quando a decisão é maior que a issue

Uma issue curta funciona bem para tarefa pequena, mas mudança estrutural costuma pedir especificação. O Spec Driven Development ajuda porque coloca intenção, regra, restrição e aceite antes da implementação.

No Vibe Coding, isso não precisa virar documento extenso para tudo, mas precisa virar referência suficiente para que o agente não invente domínio, camada, erro ou contrato. O Laravel orientando código gerado por IA é um exemplo prático: framework ajuda, mas convenção não substitui decisão.

Eu, Luiz, prefiro escrever uma especificação menor e revisável a receber um PR grande que exige reconstruir a intenção depois. O custo de pensar antes costuma ser menor que o custo de explicar depois por que a mudança não deveria ter sido feita daquele jeito.

Tabela para decidir antes de chamar a IA

Use a tabela como filtro rápido para separar tarefas localizadas de mudanças que alteram manutenção, dado, erro ou responsabilidade. Ela não substitui julgamento técnico, mas ajuda a identificar tarefas que pedem arquitetura antes do código.

Sinal da tarefa	Pode seguir com issue curta	Pede revisão arquitetural
Interface	Ajuste visual isolado.	Novo fluxo com estado, permissão e evento.
Dados	Leitura de campo existente.	Nova fonte oficial, cache ou sincronização.
Erro	Mensagem simples já prevista.	Exceção, log, segurança ou falha de integração.
Domínio	Regra já documentada.	Regra nova com impacto em cobrança, acesso ou suporte.
Dependência	Uso de serviço já integrado.	Nova API, fila, storage ou biblioteca crítica.
Revisão	PR pequeno e testável.	Mudança espalhada por camadas diferentes.

Se a tarefa cai na coluna da direita, eu não delegaria direto para o agente. Primeiro vem recorte, especificação ou comentário técnico, e só depois entra a execução assistida por IA.

Perguntas frequentes

Toda tarefa com IA precisa de arquitetura?

Nem toda tarefa com IA precisa de arquitetura formal, porque tarefa pequena pode seguir com issue clara, aceite e revisão. Arquitetura entra quando a mudança afeta responsabilidade, dado, permissão, integração, erro ou manutenção.

Arquitetura limpa exige muitas camadas?

Arquitetura limpa não exige muitas camadas, porque camada demais também atrapalha a leitura e a manutenção. A boa separação nasce quando cada parte tem uma responsabilidade real e reduz o esforço da próxima mudança.

Como saber se a IA misturou responsabilidades?

Leia onde a regra ficou depois da mudança gerada pela IA. Se controlador, componente de interface ou job de fila começam a decidir regra de domínio, acesso ou persistência diretamente, há sinal de mistura indevida.

Logging precisa entrar antes da implementação?

Sim, quando a tarefa envolve evento relevante, segurança, integração ou dado sensível. O log precisa ajudar diagnóstico sem vazar informação que não deveria estar ali.

Laravel protege a arquitetura por conta própria?

Laravel não protege a arquitetura por conta própria, embora ofereça convenções, container, filas, eventos e estrutura madura. O resultado depende de usar essas peças com responsabilidade clara e revisão humana.

O que revisar no PR gerado por IA?

Revise necessidade, camada afetada, teste, dado, erro, log, permissão e limite de escopo. A estética do código importa, mas ocupa segundo plano diante da leitura estrutural.

O próximo passo é escolher uma tarefa de risco

Pegue uma issue que você pensava em delegar para IA e marque se ela toca domínio, dado, permissão, integração, erro ou log. Se tocar dois ou mais pontos, escreva primeiro a decisão arquitetural em poucos parágrafos.

Depois peça um PR pequeno, com o agente trabalhando dentro do recorte e com o desenho do sistema já explicado. Esse é um uso mais prudente de IA no desenvolvimento.

Se você já usa agentes em Laravel, Vibe Coding, GitHub e Spec Driven Development, a Formação IA Makers aprofunda esse tipo de revisão na prática. Quando existe um sistema real em andamento, também faz sentido agendar uma consultoria para revisar arquitetura, escopo e manutenção antes de ampliar a delegação para IA.