Leia o Diff Antes de Clicar em Aceitar

Leia o Diff Antes de Clicar em Aceitar — aula do módulo O Método em Qualquer Agente, na trilha Começando com Antigravity: do Zero ao Primeiro Resultado da…

Leitura de aproximadamente 4 minutos.

Módulo: O Método em Qualquer Agente · Curso: Começando com Antigravity: do Zero ao Primeiro Resultado · Formação: Formação Nível Zero: Ferramentas Essenciais e Gratuitas de IA e Código

Leia o Diff Antes de Clicar em Aceitar

O que você vai aprender

O que é um diff e por que ele é a última barreira antes do estrago.
Como revisar sem saber programar: três palavras para caçar.
Um caso completo, com as quatro paradas obrigatórias da revisão.
Como provar na prática que a mudança faz o que diz.

1. O botão mais perigoso da tela

Quando o agente propõe uma mudança, ela aparece num painel de alterações — o diff: linhas que saem, linhas que entram. Do lado, um botão de aceitar.

O risco não é o agente ser burro. É que o script em questão move arquivos seus. Uma linha errada e seus arquivos foram parar em outro lugar, com outro nome. Você descobre depois, quando já não sabe qual era o estado anterior.

A boa notícia: revisar não exige saber programar. Exige saber onde olhar.

2. O caso: dar um botão de arrependimento ao script

O script de faxina da primeira aula funciona. O que falta nele é o desfazer. O pedido:

Altere o organizar-pasta.ps1 para aceitar um parâmetro -Desfazer. Toda execução com

-Aplicar passa a gravar um log JSON na própria pasta, com o caminho de origem e o de

destino de cada arquivo movido. Com -Desfazer, o script lê esse log e devolve cada

arquivo ao nome e ao lugar original, apaga as subpastas de categoria que ficaram vazias e

remove o log. O desfazer também simula por padrão: só executa com -Desfazer -Aplicar.

Não mude nada do comportamento atual de organizar.

A última frase — "não mude nada do comportamento atual" — é o freio de mão. Sem ela, é comum o agente aproveitar a visita e "melhorar" coisas que você não pediu, e aí a revisão vira leitura de duzentas linhas em vez de vinte.

3. As quatro paradas da revisão

Percorra o diff devagar. Em cada trecho, a pergunta é sempre a mesma: isso apaga alguma coisa que é minha?

Parada 1 — a linha nova no param(). Barata, sem risco nenhum. Serve para aquecer o olho e entender o formato do diff.

Parada 2 — o filtro que exclui o próprio log do lote. Sem ele, na segunda execução o script organizaria o próprio arquivo de log para dentro de uma pasta "Outros". Defeito pequeno, mas é o tipo de coisa que só aparece na terceira vez que você usa.

Parada 3 — o Remove-Item das pastas vazias. Aqui você para. Existe um comando de apagar dentro do seu script agora. Leia a condição em volta: ele só apaga se a contagem de itens da pasta for zero. Ou seja, pasta com arquivo dentro não é tocada. Isso é aceitável.

Se estivesse escrito Remove-Item -Recurse -Force, a resposta seria recusar na hora e pedir outra abordagem. -Recurse -Force apaga tudo o que estiver embaixo, sem perguntar e sem lixeira.

Parada 4 — o Move-Item do desfazer. Ele devolve Destino para Origem. Se os dois estivessem invertidos, o desfazer bagunçaria de novo em vez de arrumar — e o nome da função não te avisaria disso.

4. A regra que cabe na cabeça

Você não precisa entender PowerShell. Precisa caçar três palavras em qualquer diff:

apaga (Remove-Item, del, rm, Clear-)
move (Move-Item, mv, Rename-Item)
sobrescreve (-Force, Out-File sobre arquivo existente, Set-Content)

Achou uma delas, pare e leia a condição em volta. Não achou nenhuma, o diff pode passar com uma leitura de resumo.

E a regra de decisão: mudança que mexe em arquivo seu, você lê inteira. Mudança que só gera coisa nova, você lê o resumo.

5. Provar na prática

Ler o diff é metade. A outra metade é ver o ciclo completo funcionando:


powershell -NoProfile -ExecutionPolicy Bypass -File .\organizar-pasta-v2.ps1 -Pasta .\downloads-bagunca
powershell -NoProfile -ExecutionPolicy Bypass -File .\organizar-pasta-v2.ps1 -Pasta .\downloads-bagunca -Aplicar
powershell -NoProfile -ExecutionPolicy Bypass -File .\organizar-pasta-v2.ps1 -Pasta .\downloads-bagunca -Desfazer
powershell -NoProfile -ExecutionPolicy Bypass -File .\organizar-pasta-v2.ps1 -Pasta .\downloads-bagunca -Desfazer -Aplicar

Saídas medidas, na ordem: 15 arquivo(s) em 7 categoria(s) → 15 arquivo(s) organizado(s) → 15 arquivo(s) a devolver | 0 fora do lugar → 15 arquivo(s) devolvido(s). Pasta como estava.

| Etapa | Tempo medido | |---|---| | Simular organização | 1,45 s | | Aplicar | 1,66 s | | Simular desfazer | 1,05 s | | Desfazer de verdade | 1,29 s |

Ao fim, a pasta tem 15 arquivos e 0 subpastas, com os nomes feios originais de volta: Contrato Final (2).pdf, Sem título.txt, orçamento cliente NOVO.docx. Não é "quase igual". É igual.

6. A regra que fica

Script que mexe em arquivo nasce com dois botões: simulação e desfazer. Se o agente não colocar, você pede depois — e o pedido é de uma frase.

Resumo

Diff é a última barreira antes do estrago; aceitar sem ler é a aposta mais cara.
Cace três palavras: apaga, move, sobrescreve. O resto do diff pode passar.
-Recurse -Force é motivo para recusar e pedir outra abordagem.
Confirme o comportamento rodando o ciclo completo, incluindo o desfazer.

Leia o Diff Antes de Clicar em Aceitar