Modos dry-run para ações de agentes: mostrar o plano antes da alteração

Objetivo

Permitir que um agente, e a pessoa que o supervisiona, vejam exatamente o que uma ação que altera estado faria antes de ela ser executada, usando o mesmo caminho de código que mais tarde aplicará a alteração.

Pré-requisitos

Ferramentas que separam o planejamento da aplicação, ou que podem ser encapsuladas para fazê-lo. Ferramentas consolidadas mostram os formatos possíveis: rsync --dry-run faz uma execução de teste sem alterar nada; terraform plan sem -out cria o que a documentação chama de plano especulativo (speculative plan), uma descrição do efeito sem intenção de aplicá-lo, enquanto -out=FILE salva um plano que o apply pode executar depois; kubectl apply --dry-run=client apenas imprime o objeto que seria enviado, e --dry-run=server envia a requisição sem persistir o recurso; a documentação da API do Kubernetes descreve o modo dry-run como a avaliação de uma requisição pelas etapas habituais (cadeia de admissão, validação, conflitos de merge) até o ponto de persistir objetos no armazenamento, com a garantia de que não há nenhum outro efeito colateral.

Passos

1. Adicione um parâmetro dry_run a toda ferramenta que grava, apaga, envia ou publica, e torne-o o padrão documentado para a primeira chamada de uma sessão. A descrição da ferramenta deve declarar que o resultado de um dry run é um plano, não um efeito.
2. Devolva o plano na mesma estrutura do resultado real, mais um marcador ("applied": false), com objetos concretos: os caminhos de arquivo e os hunks, os IDs dos registros e os campos que mudariam, os destinatários, as contagens. "Atualizaria algumas linhas" não é um plano.
3. Prefira dry runs no servidor quando o sistema de destino os oferecer; um plano calculado no cliente não enxerga permissões, cotas, regras de validação nem alterações concorrentes.
4. Exija o plano antes da alteração: o host recusa uma chamada real cujos argumentos não tenham sido antes enviados como dry run na mesma sessão, ou encaminha o plano a uma aprovação humana para ações acima de um limite.
5. Aplique com os mesmos argumentos, depois compare (diff) o resultado real com o plano e exponha as diferenças ao agente e ao log; uma divergência significa que o estado mudou entre o plano e a aplicação, ou que a lógica do plano está errada.
6. Registre plano e resultado juntos, para que uma revisão possa ver o que foi previsto e o que aconteceu.

Resultado esperado

Toda ação irreversível é precedida por uma declaração concreta e revisável do seu efeito, e a divergência entre as duas é detectada em vez de descoberta mais tarde.

Limites e base de verificação

Um dry run comprova o que a ferramenta faria, não o que outros sistemas farão em resposta (webhooks, gatilhos, jobs downstream). Ele não protege contra um plano que está correto, mas é indesejado; para isso existem os pontos de aprovação e as ações reversíveis. A ordem dos passos é uma proposta; não se afirma nenhuma redução da taxa de falhas.

Pré-condições na aplicação, planos por limite

Plano e aplicação são duas chamadas com um intervalo entre elas, no qual o estado pode mudar; por isso, um dry run obrigatório antes de toda gravação não prova nada sobre o momento da aplicação e dobra o número de chamadas em gravações de baixo risco. Quando o destino permitir, exija uma pré-condição na própria aplicação: If-Match com um ETag, o resourceVersion do Kubernetes, um número de versão do documento ou um plano salvo do Terraform que o apply rejeita quando o estado mudou. Assim, a gravação falha de forma atômica quando o mundo mudou, e o diff posterior passa a ser uma verificação da ferramenta, em vez de a única defesa. Reserve o plano obrigatório para ações sem volta (enviar, publicar, apagar sem cópia) e para ações em massa acima de um limite de tamanho; para todo o resto, o dry run continua disponível sob demanda.