O PR gerado pela IA compila, passa no lint e entrega a tela pedida. Na revisão, porém, aparece outro problema: a regra de permissão foi parar no componente, uma dependência nova entrou sem motivo forte e o tratamento de erro começou a registrar informação que não deveria ir para log. Esse é o tipo de revisão que torna controle arquitetural com IA no código uma preocupação prática, não uma discussão abstrata.

A ferramenta pode escrever, editar arquivos, rodar comandos e abrir pull requests. A decisão sobre estrutura, dado, permissão, dependência e aceite continua precisando de uma pessoa responsável.

Eu não vejo agentes de código como ameaça ao desenvolvimento. Vejo como uma mudança no lugar da atenção. Se a IA reduz parte da digitação, o tempo economizado precisa voltar para revisão, escopo e decisão arquitetural.

Aqui na Promovaweb, dentro da Formação IA Makers, eu conecto Vibe Coding com Git, PR pequeno, instrução persistente e revisão humana. Sem esse desenho, a pessoa ganha código rápido e perde a capacidade de explicar por que aquela base ficou daquele jeito.

Direto ao ponto

Para manter controle arquitetural com IA no código, limite o escopo antes da tarefa, registre decisões importantes, revise o diff por camada, dado, permissão, dependência e teste, e não aceite PR apenas porque compila. A IA pode escrever e sugerir; a arquitetura continua sob responsabilidade humana.

Código gerado não pode virar decisão estrutural automática

OpenAI descreve o Codex web como agente capaz de ler, editar e executar código, trabalhando em tarefas de fundo e criando pull requests em repositórios conectados ao GitHub. Claude Code segue a mesma direção: lê codebase, edita arquivos, roda comandos e trabalha em terminal, IDE, desktop e web.

Essa capacidade muda a rotina. O agente ultrapassa o papel de autocomplete. Ele pode receber uma tarefa, mexer em vários arquivos, criar branch e propor PR. Quando isso acontece, a revisão precisa subir de nível.

Eu não revisaria apenas se o código está bonito. Olharia primeiro para o que a mudança decidiu sem pedir autorização: lugar da regra, dependência criada, autorização alterada, contrato de API, novo dado em log e impacto no banco.

Essas perguntas protegem a arquitetura porque tiram a revisão do campo estético. Código bonito no lugar errado continua sendo problema.

O controle aparece no tamanho da mudança

Agente de código trabalha melhor quando a tarefa cabe em um diff legível. Quanto maior o pedido, maior a chance de a IA preencher lacunas com escolhas plausíveis. Plausível, em software real, ainda precisa passar por revisão.

Eu prefiro pedir alterações pequenas, com uma intenção clara e um limite explícito. Uma tarefa para ajustar validação de formulário não deveria também reorganizar autenticação, trocar biblioteca, mexer em layout e alterar schema de banco.

O artigo sobre quando revisar arquitetura antes da IA gerar código cobre o momento anterior à implementação. Aqui, a preocupação é o ciclo seguinte: cada PR gerado por IA precisa respeitar o desenho que já foi decidido.

Quando a mudança cresce demais, a revisão vira investigação. Nesse ponto, o ganho do agente se perde porque a pessoa revisora precisa reconstruir a intenção depois do código pronto.

Instruções persistentes reduzem improviso

Claude Code documenta o uso de arquivos de instrução para registrar padrões de código, decisões arquiteturais, bibliotecas preferidas e checklists de revisão. GitHub Copilot code review também aceita custom instructions no repositório, inclusive instruções por caminho.

Essas instruções não precisam virar um manual extenso. Elas precisam dizer o que o agente deve preservar. Em um projeto real, isso pode incluir padrões de pasta, política de dependências, regra de autenticação, tratamento de erro, logging, testes mínimos e convenções de PR.

O post sobre instruções de agentes no código com referência aprofunda essa camada. A instrução não substitui documentação técnica completa, mas orienta a execução do agente no ponto em que ele decide o próximo arquivo a tocar.

Eu manteria instruções curtas e revisáveis. Regra escondida em documento longo tende a não aparecer quando importa. Se uma decisão arquitetural é crítica, ela precisa estar visível para o agente e para quem revisa.

O review precisa olhar o diff por responsabilidade

Revisar PR de IA olhando apenas se o teste passou é pouco. O teste mostra parte do comportamento. A arquitetura aparece na distribuição da responsabilidade.

Eu começaria perguntando onde a regra ficou. Regra de domínio dentro de componente visual, controlador ou job de fila costuma cobrar manutenção depois. Também olharia se a mudança duplicou lógica que já existia em outro lugar.

Depois, revisaria o dado. A fonte oficial precisa estar clara, cache não pode virar origem por acidente, log não deve receber informação pessoal sem necessidade e consulta não deveria depender de estado local desconhecido pelo restante do sistema.

Em seguida, olharia permissão e dependência. Alteração em autenticação, autorização, cobrança, plano, assinatura ou integração externa merece revisão mais lenta. Dependência nova precisa ter motivo real; se ela entrou para resolver detalhe pequeno, talvez o agente tenha escolhido conforto de implementação no lugar de coerência do projeto.

Revisão automática comenta, mas não aprova arquitetura

GitHub informa que a revisão do Copilot deixa comentário, não aprovação nem solicitação formal de mudança. Isso é um detalhe importante. Ferramenta de revisão ajuda a encontrar problema, mas não assume responsabilidade pelo merge.

Eu gosto de usar revisão automática como segunda leitura. Ela pode apontar bug, inconsistência, melhoria de teste ou risco simples. O limite aparece quando a análise exige contrato com cliente, prioridade de manutenção, impacto em suporte e decisão arquitetural acumulada.

Também existe limite de referência. A própria documentação do GitHub informa que, para certas revisões, há limite de leitura em arquivo de instrução. Se a regra essencial só aparece depois desse trecho, a revisão pode ignorar justamente o ponto que você queria proteger.

Por isso, a arquitetura precisa aparecer em lugares curtos e próximos do trabalho: issue, PR, checklist, instrução de pasta e documento de decisão quando a mudança for maior.

O que eu bloquearia antes do merge

Eu bloquearia merge quando a IA altera domínio, permissão, banco, cobrança, integração ou log sem explicação no PR. Também bloquearia quando a mudança espalha a mesma regra por pontos diferentes ou adiciona dependência sem justificar o custo de manutenção.

Outro sinal é o PR difícil de ler. Se a pessoa revisora precisa alternar entre muitos arquivos para entender uma tarefa pequena, o escopo provavelmente escapou. Nesse caso, vale pedir divisão antes de discutir detalhe de estilo.

O conteúdo sobre como definir guardrails no Vibe Coding ajuda nesse ponto. Guardrail bom não é trava genérica; é limite verificável. Ele diz o que pode mudar, por quê e como confirmar.

No nosso Co-work da IA Makers, eu prefiro ver um PR menor, com teste simples e decisão clara, do que uma entrega grande que exige confiança demais na ferramenta. nesse cenário, Co-work é o ambiente ao vivo de trabalho acompanhado em que projetos reais são abertos para revisão; ele serve para tirar dúvidas, conferir decisões e ajuda o leitor a transformar a própria dúvida em próximo passo revisável.

Como manter a arquitetura legível entre sessões

Agentes podem trabalhar em sessões paralelas, retomar tarefas e atuar em ambientes diferentes. Esse ganho exige uma memória de projeto melhor. Se cada sessão recebe referência diferente, o repositório começa a acumular escolhas desconectadas.

Eu usaria três peças para preservar continuidade: issue curta, instrução persistente e PR com resumo honesto. A issue declara o problema e o limite. A instrução preserva decisões do projeto. O PR explica o que mudou, o que foi validado e o que ficou fora.

O GitHub ajuda porque deixa diff, discussão, commit e revisão no mesmo fluxo. O post sobre GitHub Issues para governança de SaaS conversa com essa disciplina: issue boa funciona como contrato curto de trabalho.

Quando esse contrato existe, o agente erra menos e a pessoa revisora gasta menos energia decifrando intenção. Quando não existe, cada PR vira uma negociação tardia sobre algo que deveria ter sido decidido antes.

Perguntas comuns sobre controle arquitetural com IA

Toda mudança gerada por IA precisa de revisão arquitetural?

Não. Ajuste pequeno, teste localizado, copy de interface e correção simples podem seguir com review proporcional. A revisão arquitetural fica indispensável quando a mudança toca domínio, dado, permissão, banco, integração, erro, log ou dependência crítica.

Como saber se a IA mudou arquitetura sem perceber?

Leia o diff procurando mudança de responsabilidade. Se uma regra saiu do lugar, se uma dependência nova apareceu, se o mesmo comportamento foi duplicado ou se uma tarefa pequena mexeu em muitas camadas, há sinal de mudança arquitetural.

Custom instructions resolvem o problema?

Elas ajudam parcialmente. Instruções orientam o agente; review humano decide se a mudança respeitou o projeto. Também precisam ser curtas, atualizadas e visíveis para a ferramenta usada no fluxo.

Posso aceitar PR de IA se todos os testes passaram?

Teste verde é evidência importante, mas não prova arquitetura boa. Antes do merge, revise necessidade, camada, dado, permissão, dependência, log e escopo. Teste cobre comportamento; arquitetura cobre manutenção.

O que documentar quando a IA mexe em código crítico?

Registre a decisão, o motivo, o limite da mudança, a validação executada e o que ficou fora. Em área crítica, o PR precisa explicar por que a alteração existe e quais riscos foram revisados.

Qual é o papel da Formação IA Makers nesse tema?

Na Formação IA Makers, esse tema entra no uso real de agentes, Vibe Coding, Git, revisão e arquitetura. O objetivo é usar IA para avançar projetos sem perder clareza sobre regra, dado, permissão e manutenção.

O ganho da IA precisa voltar para revisão

O erro mais comum é usar todo o ganho da IA para pedir mais código. Eu prefiro usar parte desse ganho para revisar melhor. A pessoa que antes gastava tempo digitando pode agora gastar mais tempo lendo diff, ajustando escopo e registrando decisão.

Como manter controle arquitetural com IA no código depende menos de uma ferramenta específica e mais de rotina: issue pequena, instrução visível, PR legível, teste proporcional e aprovação humana.

Se você já usa Claude Code, Codex, Copilot, Antigravity ou outro agente no projeto, vale revisar o fluxo antes de ampliar a delegação. O próximo passo é escolher um PR recente e verificar se a mudança respeitou o desenho do sistema ou apenas funcionou no caminho feliz.

Quando existe sistema real, cliente, dado sensível ou contrato ativo, esse cuidado merece diagnóstico. A Formação IA Makers aprofunda esse tipo de trabalho no desenvolvimento com IA. Para revisar um projeto em andamento, também faz sentido agendar uma consultoria com a Promovaweb e analisar arquitetura, escopo e rotina de PRs antes de aumentar a autonomia dos agentes.