Como limitar o escopo de alterações geradas por IA

Limitar o escopo de alterações com inteligência artificial exige uma fronteira explícita de autorização. É preciso dizer qual comportamento deve mudar, o que deve permanecer igual e que tipo de intervenção pode entrar no diff.

A correção pedida resolve um defeito ou uma pequena mudança verificável. A refatoração oportunista reorganiza o código sem relação direta com esse resultado.

O ponto não é proibir refatoração. É impedir que uma correção simples chegue à revisão misturada com uma reforma que ninguém decidiu fazer.

Quando a IA transforma uma correção em uma reforma

Uma alteração gerada por IA costuma parecer eficiente quando entrega mais do que foi pedido. O assistente encontra uma função mal nomeada, percebe duplicação, sugere extrair um serviço, troca uma convenção e, no fim, abre um pull request maior do que a tarefa original.

À primeira vista, isso pode soar como zelo técnico. Na prática, pode atrapalhar a decisão mais simples da revisão: este diff resolve o problema solicitado com risco aceitável?

O problema não é a IA sugerir melhorias. No caso do GitHub Copilot Agents, a documentação descreve agentes com ambientes e permissões distintos e ressalta supervisão humana e revisão das saídas. O problema aparece quando a equipe não define uma fronteira entre corrigir o que foi pedido e aproveitar para arrumar a casa.

Essa fronteira precisa ser explícita porque a revisão humana não avalia apenas se o código compila. Ela avalia intenção, risco, reversibilidade e aderência à mudança autorizada. Uma refatoração pode ser boa e ainda assim estar no pull request errado.

Essa distinção é especialmente útil para lideranças técnicas que já estão redesenhando práticas de engenharia com IA. Em vez de discutir a adoção inteira de uma vez, vale olhar para um ponto pequeno e recorrente do processo: o tamanho real da mudança que chega para revisão. Esse recorte conversa com uma discussão mais ampla sobre como criar uma estratégia de inteligência artificial conectada ao negócio, mas aqui a decisão é operacional: aceitar, pedir divisão ou recusar uma alteração fora de escopo.

Defina a unidade de trabalho antes do prompt

Escopo não nasce no pull request. Nasce na formulação da tarefa.

Antes de pedir a uma IA que altere código, a equipe deve transformar o pedido em uma unidade de trabalho pequena, independente e testável. O DORA recomenda trabalhar em lotes pequenos para obter retorno sobre mudanças e revisar hipóteses mais cedo. A mesma orientação alerta para a dificuldade de revisar e integrar grandes mudanças geradas com IA.

Aplicado ao uso de IA, isso muda a qualidade da instrução. Um prompt como “corrija o cálculo de desconto” deixa espaço demais. Um pedido mais revisável diria:

qual comportamento está errado;
qual comportamento esperado deve ser preservado;
quais arquivos parecem estar no caminho provável da correção;
quais testes existentes devem continuar passando;
que tipo de alteração está autorizado;
o que deve ser apenas comentado como sugestão, sem entrar no diff principal.

Essa fronteira define o que pode entrar no diff e o que deve virar sugestão separada.

Se a tarefa autoriza apenas corrigir um arredondamento, a IA não deve renomear classes, reorganizar diretórios ou alterar convenções globais. Se durante a execução ela encontrar duplicação relevante, isso pode virar comentário, issue ou proposta separada. Não precisa entrar na mesma alteração.

Esse cuidado também é uma forma prática de engenharia de contexto. A Anthropic define engenharia de contexto como seleção e manutenção das informações disponíveis ao modelo durante a inferência, incluindo instruções, ferramentas, dados externos e histórico, dentro de uma janela limitada. Em uma tarefa de código, contexto não é despejar o repositório inteiro no assistente. É escolher quais informações ajudam a resolver aquela mudança sem ampliar indevidamente a área de atuação.

Separe três tipos de mudança no pull request

Uma revisão de código com IA fica mais objetiva quando a equipe classifica cada parte do diff em três grupos.

O primeiro grupo é a correção funcional. É a mudança que altera diretamente o comportamento solicitado. Se havia um defeito no cálculo, uma validação incompleta ou uma condição de erro mal tratada, esse é o núcleo da tarefa.

O segundo grupo é o ajuste necessário para viabilizar a correção. Às vezes, para corrigir o comportamento, é preciso alterar um teste, adaptar uma função auxiliar, ajustar uma configuração ou tornar explícita uma dependência que já existia de forma implícita. Esse grupo pode ficar no mesmo pull request, desde que a relação com a correção seja clara.

O terceiro grupo é a refatoração não solicitada. Ela pode melhorar nomes, reduzir duplicação, organizar camadas ou simplificar estruturas. Mas, se não for necessária para validar a mudança pedida, ela não pertence automaticamente ao mesmo escopo.

A regra de revisão é: aceite as duas primeiras categorias quando estiverem justificadas. Bloqueie ou separe a terceira quando ela depender de uma decisão que não foi tomada.

Isso evita um erro comum: discutir gosto técnico como se fosse requisito. A pergunta deixa de ser “o código ficou melhor?” e passa a ser “esta alteração era necessária para resolver o pedido com uma revisão proporcional?”.

Refatorar não é erro. Misturar refatoração independente com correção pequena é que cria ruído. Quando tudo entra no mesmo diff, o revisor precisa validar comportamento, arquitetura, nomenclatura e intenção ao mesmo tempo. A revisão deixa de ser uma decisão sobre uma mudança e vira uma negociação sobre várias.

Use o diff para perguntar: isto muda o resultado ou só melhora a forma?

O diff é o melhor lugar para separar solução de preferência. Ele mostra o que realmente mudou, não apenas o que a instrução prometia.

Ao revisar um pull request assistido por IA, algumas perguntas ajudam a manter a fronteira:

Este arquivo participa do caminho provável do defeito ou da funcionalidade?
Esta alteração muda o resultado solicitado ou apenas melhora a forma interna?
Este rename ajuda a testar a hipótese original ou só aumenta a superfície de revisão?
Esta reorganização altera fluxo de execução, contrato público ou dependência entre módulos?
O teste novo falharia antes da correção e passaria depois, ou cobre uma melhoria lateral?
A explicação do assistente ou do desenvolvedor justifica cada mudança estrutural?
Se precisarmos reverter a correção, conseguimos fazer isso sem desfazer uma reforma paralela?

As perguntas deslocam a discussão de preferência técnica para vínculo com a hipótese inicial.

Também ajudam a evitar um tipo específico de sedução: a mudança bonita demais para o problema. A IA pode propor uma solução mais elegante, mais genérica ou mais alinhada a um padrão abstrato. Isso não basta. Em engenharia, elegância fora de hora também é custo.

O critério concreto é a relação com a hipótese inicial. Se a tarefa era corrigir um comportamento observável, o diff deve ajudar a demonstrar que esse comportamento mudou como esperado e que o restante continuou estável. O que não ajuda nessa validação deve ser tratado como sugestão separada.

Para organizações que estão amadurecendo sua governança de IA, esse tipo de pergunta também evita que a ferramenta vire desculpa para decisões implícitas. Maturidade não é deixar a IA mexer mais. É saber quando autorizar, quando restringir e quando dividir. Esse olhar se conecta ao diagnóstico de capacidades discutido em maturidade em IA, mas aqui aparece em uma prática diária: revisar um diff com fronteira clara.

Transforme melhorias encontradas em tarefas separadas

Boas oportunidades não precisam ser perdidas porque ficaram fora do escopo. Elas só não devem contaminar a alteração principal.

Quando a IA encontra uma melhoria real, a equipe pode registrá-la de três formas:

comentário no pull request, indicando que a melhoria foi percebida, mas não incluída;
item no backlog, com vínculo para o trecho afetado;
proposta de refatoração separada, com objetivo, risco e critério de aceite próprios.

Esse hábito protege duas coisas ao mesmo tempo. Protege a correção atual, que continua pequena e verificável. E protege a refatoração futura, que deixa de ser um efeito colateral e passa a ser uma decisão deliberada.

Uma refatoração bem conduzida merece espaço próprio. Ela pode exigir leitura arquitetural, testes adicionais, discussão de convenção, análise de impacto e alinhamento com outras frentes. Colocá-la escondida dentro de uma correção reduz a qualidade da decisão.

Há uma frase que vale usar em revisão: “isso pode ser uma boa mudança, mas não é esta mudança”.

Essa frase separa mérito de oportunidade. Ela reconhece que a sugestão pode ter valor, sem permitir que o pull request mude de natureza no meio do caminho.

Defina o que faz a revisão parar

Nem toda divergência de escopo precisa bloquear uma revisão. Algumas podem ser resolvidas com um comentário, uma explicação adicional ou a remoção de um arquivo. Mas certos sinais devem fazer a equipe parar.

A revisão deve ser interrompida quando:

a construção ou os testes automatizados quebram;
há alteração em contrato público sem autorização explícita;
arquivos sem relação demonstrável com a tarefa foram modificados;
a IA alterou estilo, nomes ou estrutura em várias partes sem vínculo com a correção;
o pull request mistura correção de defeito com reorganização arquitetural;
a explicação não conecta mudanças estruturais ao comportamento solicitado;
a reversão da correção exigiria também reverter uma refatoração independente.

O DORA descreve integração contínua como integração frequente ao código principal, acompanhada de construção e testes automatizados. Também afirma que corrigir uma construção quebrada deve ter prioridade sobre novas mudanças. Em um fluxo assistido por IA, isso reforça uma regra simples: se o pull request aumenta incerteza básica, a prioridade deixa de ser adicionar mais alterações e passa a ser restaurar uma base verificável.

Parar a revisão não é punir a ferramenta nem o desenvolvedor. É preservar a capacidade da equipe de entender o que está mudando.

Quanto mais mudanças independentes entram no mesmo lote, mais difícil fica atribuir causa quando algo falha. A equipe passa a investigar se o problema veio da correção, da refatoração, do rename, do novo teste, da configuração ou da combinação entre eles. Esse é um custo evitável.

Sinais de que o pull request saiu do escopo

Use estes sinais em revisões de código gerado ou alterado com IA. Eles não substituem julgamento técnico, mas ajudam a criar uma linguagem comum para a revisão.

A mudança altera diretamente o comportamento solicitado? Fica no escopo quando corrige o defeito, implementa o requisito pedido ou ajusta código necessário para esse resultado.
A mudança apenas melhora forma, generalidade ou preferência de estilo? Sai do escopo quando não é necessária para validar o comportamento pedido.
O arquivo alterado está no caminho provável do defeito ou da funcionalidade? Fica no escopo quando participa da execução, validação ou configuração da mudança pedida.
O arquivo foi tocado por oportunidade, padronização ampla ou reorganização sem vínculo demonstrável? Sai do escopo.
A alteração torna a correção mais fácil de verificar sem espalhar impacto? Fica no escopo.
A alteração exige revisar arquitetura, nomenclatura, contratos ou fluxo de execução que não eram parte da tarefa? Sai do escopo.
O teste novo ou alterado comprova a hipótese inicial? Fica no escopo quando falha antes da correção e passa depois, ou cobre claramente o comportamento solicitado.
O teste cobre melhorias genéricas, reorganizações internas ou cenários não relacionados? Sai do escopo.
A explicação da IA ou do desenvolvedor conecta cada mudança estrutural à correção pedida? Fica no escopo.
A justificativa é apenas qualidade geral, limpeza futura ou aproveitamento do momento? Sai do escopo.
A mudança pode ser revertida sem desfazer refatorações independentes? Fica no escopo.
Correção e refatoração ficaram misturadas a ponto de impedir uma reversão limpa? Sai do escopo.

A utilidade do checklist está menos em produzir uma resposta mecânica e mais em reduzir ambiguidade. Quando a equipe discorda, ela passa a discutir um critério visível, não uma sensação sobre o tamanho do pull request.

Exemplo fictício: corrigir cálculo de desconto sem redesenhar o módulo

Imagine um caso fictício em uma plataforma de comércio eletrônico. A tarefa é corrigir um arredondamento em descontos progressivos. Em certas combinações de quantidade e percentual, o total exibido difere do total calculado no fechamento do pedido.

A instrução para a IA diz: corrigir o arredondamento, preservar as regras atuais de desconto, alterar apenas os arquivos diretamente ligados ao cálculo e aos testes correspondentes, e registrar sugestões de melhoria sem aplicá-las.

O pull request chega com três tipos de mudança.

Primeiro, altera a função responsável por arredondar valores no cálculo do desconto. Segundo, adiciona um teste que reproduz o cenário em que a diferença aparece. Terceiro, renomeia a classe de política de desconto, extrai um novo serviço de precificação e muda a organização de pastas para separar cálculo, apresentação e persistência.

Pelo critério deste guia, os dois primeiros itens ficam no pull request. Eles se conectam diretamente ao comportamento solicitado e tornam a correção verificável. O terceiro conjunto deve sair. Pode ser uma boa refatoração, mas não é necessário para validar a hipótese inicial.

A revisão poderia registrar algo como: “A extração do serviço de precificação pode melhorar a organização do módulo, mas amplia o escopo desta correção. Remover deste pull request e abrir sugestão separada com objetivo e impacto esperados.”

Nada nesse exemplo afirma que a separação produzirá automaticamente menos retrabalho ou mais qualidade. Esses efeitos seriam hipóteses a medir pela equipe. O que a separação permite imediatamente é uma decisão mais delimitada: corrigir o arredondamento agora, avaliar a refatoração em outro momento.

Essa disciplina também ajuda a liderança a enxergar o uso de IA como parte do desenho do trabalho, não como um atalho isolado. Se a organização está montando um roadmap de IA, vale incluir práticas de revisão, limites de permissão e critérios de escopo entre as capacidades a desenvolver. Não basta escolher ferramentas. É preciso decidir como elas entram no fluxo de decisão.

Antes de aceitar um pull request gerado ou alterado com IA, peça que a equipe classifique o diff em correção funcional, ajuste necessário e refatoração não solicitada. O que não estiver ligado ao comportamento pedido deve sair do pull request principal ou virar sugestão separada.

Se quiser discutir essa decisão no contexto da sua empresa, converse com a dooop.

Leituras para continuar

Fontes

PRÓXIMA DECISÃO

Conversar sobre a aplicação na empresa

Conversa sobre o contexto da empresa de software

Conteúdo de dooop. O cadastro permite relacionar esta pauta à jornada do leitor e acompanhar o interesse pelo tema.