Um agente de IA pode entregar uma alteração como arquivo .patch ou .diff. O formato parece controlado porque mostra linhas adicionadas e removidas. Ainda assim, aplicar o arquivo diretamente pode mudar caminhos inesperados, substituir configuração, adicionar dependências, alterar permissões ou introduzir código que só revela o efeito quando é executado.
Este guia propõe uma sequência verificável para revisar a mudança antes de incorporá-la. O processo usa recursos do próprio Git para resumir o patch, testar se ele se aplica, isolar o trabalho e comparar o resultado. A aprovação continua humana. Um patch que passa no comando git apply --check é aplicável ao estado atual, não necessariamente correto, seguro ou adequado ao projeto.
Resultado esperado
Ao final, você terá o patch original preservado, um registro de origem e hash, a lista de arquivos afetados, o resultado da checagem de aplicação, uma área isolada para teste, o diff realmente produzido e uma decisão documentada: aceitar, pedir correção ou rejeitar.
O resultado correto não mistura a revisão com alterações antigas do seu diretório de trabalho. Também não executa scripts recebidos automaticamente. A mudança só avança quando cada arquivo afetado tem relação com o pedido, os testes relevantes foram escolhidos conscientemente e os efeitos observados correspondem ao objetivo descrito.
Pré-requisitos
- Um repositório Git local que você está autorizado a modificar.
- Git disponível no terminal e conhecimento do branch ou commit usado como base.
- O patch salvo como arquivo de texto, por exemplo
mudanca-ia.patch. - Espaço para criar um worktree separado ou outra cópia descartável do repositório.
- Documentação do projeto sobre build, testes, lint e validações obrigatórias.
Se o material inclui novos pacotes ou scripts de instalação, combine este roteiro com Antes de executar código gerado por IA: revise dependências e scripts de instalação. Se o problema ainda não foi reproduzido, volte um passo e use Reprodução mínima de bugs: isole o erro antes de consultar uma IA.
Passo 1: preserve o arquivo recebido sem aplicá-lo
Salve a resposta do agente como um arquivo novo. Não cole o conteúdo diretamente no terminal e não substitua um patch anterior com o mesmo nome. Guarde também a conversa, o pedido original ou o identificador da tarefa que explica por que a mudança existe.
No PowerShell, você pode registrar o hash do arquivo para saber exatamente qual versão foi revisada:
Get-FileHash -LiteralPath .\mudanca-ia.patch -Algorithm SHA256O hash não prova autoria nem segurança. Ele apenas identifica os mesmos bytes. Se o agente gerar outra versão, trate-a como uma nova proposta e repita a revisão, mesmo que a explicação diga que houve apenas uma correção pequena.
Passo 2: confirme o repositório e a base
Antes de interpretar o patch, confirme onde você está e se o diretório contém trabalho não relacionado:
git rev-parse --show-toplevel
git branch --show-current
git status --shortO git status mostra diferenças entre o commit atual, o índice e a árvore de trabalho, além de arquivos não rastreados. Se houver mudanças suas, não prossiga no mesmo diretório. Registrar o branch também evita revisar contra uma base diferente daquela usada para criar o patch.
Passo 3: leia cabeçalhos e caminhos como dados
Abra o patch em um editor de texto. Procure cabeçalhos como diff --git, --- a/, +++ b/, renomeações, criação de arquivos e mudança de modo. Confira cada caminho contra o escopo pedido.
Uma correção de interface não deveria alterar pipeline de implantação, arquivos de segredo, configuração de produção ou scripts de pós-instalação sem justificativa explícita. Caminhos absolutos, segmentos ../ e nomes fora do repositório exigem interrupção e investigação. Não aceite a alegação do agente como substituto da leitura do arquivo.
Passo 4: gere um resumo sem aplicar
O git apply possui modos que apenas descrevem a entrada. Use os três para obter perspectivas diferentes:
git apply --stat .\mudanca-ia.patch
git apply --numstat .\mudanca-ia.patch
git apply --summary .\mudanca-ia.patch--stat resume arquivos e volume de linhas. --numstat expõe contagens em formato mais simples de comparar. --summary mostra informações como criação, renomeação e mudança de modo. Esses comandos desligam a aplicação do patch. Use a saída para montar uma lista de revisão, não para decidir pela quantidade de linhas.
Passo 5: teste se o patch se aplica ao estado atual
Faça a checagem antes de modificar arquivos:
git apply --check --whitespace=error-all .\mudanca-ia.patchA opção --check pergunta ao Git se a mudança pode ser aplicada à árvore de trabalho ou ao índice, conforme as opções usadas. Ela detecta conflitos de contexto e outros erros de aplicação. A opção de whitespace torna problemas de espaços bloqueantes nessa conferência.
Uma saída limpa não valida lógica, testes, licença, dependências ou intenção. Ela só confirma que o formato e o contexto do patch são compatíveis com aquela base. Se a checagem falhar, não force a aplicação com opções permissivas. Primeiro descubra qual commit, branch ou versão o agente assumiu.
Passo 6: procure binários, permissões e arquivos gerados
Examine o resumo e o texto por marcadores de patch binário, alterações de modo e arquivos muito grandes. Um patch pode incluir imagens, artefatos de build, lockfiles, snapshots ou arquivos minificados. Cada um precisa de motivo e método de validação próprios.
Uma mudança de modo pode tornar um arquivo executável. Um lockfile pode trazer uma árvore de dependências bem maior que a linha alterada no manifesto. Um arquivo gerado pode esconder a fonte que deveria ter sido modificada. Trate esses casos como decisões separadas, mesmo quando o patch principal resolve o problema.
Passo 7: crie uma área de revisão isolada
O comando git worktree permite manter mais de uma árvore de trabalho ligada ao mesmo repositório. A partir de uma base limpa, crie um diretório e um branch exclusivos para a revisão:
git worktree add ..\revisao-patch-ia -b revisao/patch-ia
Set-Location ..\revisao-patch-ia
git status --shortEscolha nomes que não existam e um caminho permitido pela sua organização. O objetivo é impedir que a proposta se misture ao seu trabalho corrente. O worktree não cria uma sandbox de segurança: scripts aplicados ali ainda podem acessar rede, credenciais e outros arquivos conforme as permissões do processo.
Passo 8: leve somente o patch para a área isolada
Copie o arquivo de patch para fora da árvore rastreada ou referencie seu caminho original. Não copie caches, arquivos .env, credenciais, sessões do navegador ou resultados de build. Confirme novamente o hash depois da cópia se houver qualquer dúvida sobre qual arquivo chegou ao ambiente de revisão.
Rode outra vez git apply --check dentro do worktree. Esse segundo teste garante que a área isolada parte da base esperada. Se o resultado divergir, pare e compare branch, commit e configuração antes de aplicar.
Passo 9: aplique sem executar scripts
Quando a checagem e o escopo estiverem corretos, aplique o patch como uma alteração ainda não aprovada:
git apply .\mudanca-ia.patch
git status --shortO git apply não cria commit. Isso é útil porque mantém a proposta visível para revisão. Não execute instaladores, migrações, hooks sugeridos, scripts de preparação ou comandos copiados da resposta da IA nesta etapa. Primeiro confira o diff produzido.
Passo 10: compare o resultado real com o patch
Use o Git para revisar o estado que realmente ficou no worktree:
git diff --stat
git diff --name-status
git diff --check
git diffA documentação do git diff distingue alterações na árvore de trabalho, no índice e entre commits. Neste ponto, a visão padrão mostra mudanças ainda não preparadas para commit. Confira se a lista de arquivos coincide com o resumo anterior e se git diff --check não relata erros de whitespace.
Passo 11: revise um arquivo por vez
Para cada arquivo, responda a quatro perguntas: por que ele precisa mudar, qual comportamento anterior foi alterado, como o novo comportamento será observado e como a mudança pode falhar. Leia também linhas de contexto que não foram tocadas. Uma edição localmente plausível pode quebrar uma invariável definida acima, abaixo ou em outro módulo.
A orientação do GitHub para revisão de pull requests recomenda examinar cada arquivo alterado e entender a finalidade da proposta antes da aprovação. Use a mesma disciplina localmente. Marcar um arquivo como revisado significa compreender seu papel, não apenas percorrer o diff.
Passo 12: separe código, configuração e dependências
Classifique as mudanças por efeito. Código altera comportamento. Configuração altera ambiente, permissões ou integração. Dependências trazem código de terceiros e podem acionar scripts. Documentação altera o contrato percebido por quem usa o projeto.
Confira manifestos e lockfiles juntos. Procure URLs novas, endpoints, nomes de variáveis, permissões, tarefas agendadas, telemetria, comandos de shell e tratamento de dados. Uma linha pequena pode ampliar bastante a superfície operacional. Se a mudança foge do pedido, peça um patch menor em vez de aceitar escopo extra por conveniência.
Passo 13: escolha testes a partir do risco
Consulte o README, a documentação de contribuição e a automação do próprio repositório. Execute somente comandos compreendidos e autorizados. Comece por verificações locais de baixo efeito, como parser, lint ou teste unitário específico, e amplie quando o resultado justificar.
Não invente um comando genérico como se todos os projetos usassem a mesma ferramenta. Não desative falhas para obter uma saída verde. Registre o comando, a versão da ferramenta, o código de saída e o trecho relevante do resultado. Se um teste exige rede, serviço pago, segredo ou dado real, declare essa dependência e obtenha o ambiente apropriado.
Passo 14: compare intenção, diff e evidência
Volte ao pedido original. A mudança resolve o problema descrito ou apenas altera o sintoma? Existe teste para o comportamento novo? O patch remove uma validação para fazer o teste passar? Alguma exceção foi engolida, algum limite foi aumentado ou algum controle foi convertido em comentário?
Organize a conclusão em três blocos: fatos observados no diff, resultados de testes e análise humana. Mantenha hipóteses identificadas como hipóteses. Uma explicação convincente gerada por IA não substitui a evidência do repositório.
Passo 15: registre a decisão antes de integrar
Se aceitar, registre o hash do patch, a base, os arquivos revisados, os testes executados e as ressalvas. Depois siga o fluxo normal do projeto, como commit e pull request. Se pedir correção, indique linhas e comportamento esperado. Se rejeitar, preserve o registro suficiente para explicar a decisão e descarte somente a área isolada.
Não use comandos destrutivos para “voltar ao normal” no diretório principal. Um worktree separado torna a contenção mais simples, mas sua remoção também deve apontar para o caminho exato e ocorrer apenas depois de salvar o que precisa ser auditado.
Erros comuns
- Confundir aplicabilidade com qualidade:
git apply --checknão avalia a lógica. - Aplicar no diretório com trabalho pendente: isso mistura autoria e dificulta a reversão.
- Revisar somente o número de linhas: uma pequena configuração pode ter efeito maior que um arquivo longo.
- Ignorar modos e renomeações: o efeito não aparece apenas nas linhas de código.
- Executar o comando sugerido pela IA: o patch e as instruções devem ser revisados separadamente.
- Aceitar um patch maior para economizar tempo: escopo extra aumenta o que precisa ser entendido e testado.
- Descartar a evidência cedo: sem hash, base e resultados, a revisão não é reproduzível.
Solução de problemas
O patch está corrompido ou foi copiado incompleto: peça o arquivo novamente. Não reconstrua linhas ausentes por adivinhação.
O git apply --check relata que o patch não se aplica: confirme o commit de base e se o arquivo foi criado com o mesmo nível de diretório. Não use --reject ou --3way automaticamente, pois ambos mudam a natureza da revisão.
O resumo mostra um arquivo inesperado: interrompa a aplicação e peça uma proposta limitada ao escopo. Se o arquivo for necessário, exija justificativa e teste específicos.
O worktree não pode ser criado: verifique se o branch ou o caminho já existe e se a árvore principal está em um repositório válido. Não reutilize uma pasta com conteúdo desconhecido.
Os testes exigem instalar dependências: revise manifesto, lockfile, origem e scripts antes. Use ambiente descartável e política de rede apropriada. A instalação não faz parte da simples conferência do patch.
O diff após aplicar não corresponde ao resumo: confirme a base, filtros, atributos do Git, conversão de fim de linha e arquivos gerados. Não integre enquanto a diferença não estiver explicada.
Limites deste procedimento
O roteiro cobre patches textuais em projetos controlados por Git. Ele não substitui revisão de segurança, análise de licença, varredura de dependências, testes de integração, validação de migração ou aprovação do responsável pelo sistema. Também não torna seguro executar código desconhecido.
Um worktree isola o estado do repositório, não o sistema operacional. Processos continuam com as permissões do usuário e podem alcançar rede, arquivos e credenciais disponíveis. Para código não confiável, use o ambiente de isolamento aprovado pela organização e limite os recursos antes da execução.
Checklist antes de aceitar
- O patch original foi preservado com origem, data e SHA-256?
- O branch e o commit de base foram confirmados?
- O diretório principal estava limpo ou ficou fora da aplicação?
- Todos os caminhos, renomeações e modos foram revisados?
git apply --checkpassou sem opções permissivas?- A aplicação ocorreu em área isolada e sem executar scripts?
- O diff resultante corresponde ao escopo pedido?
- Dependências, configuração e dados receberam revisão própria?
- Os testes vieram da documentação do projeto e seus resultados foram registrados?
- A decisão humana distingue fatos, testes e hipóteses?