Checklist de "deploy em seco" antes de deixar o Claude Code subir produção

Numa sexta-feira de tarde, pedi ao Claude Code: “publica essa correção do artigo em produção, por favor”. A resposta veio numa linha só: “publicado”, com um check verde do lado. Fui embora tranquilo. Na manhã seguinte, a home do site estava completamente em branco.

A causa era boba. Ninguém tinha aberto o preview. O Claude Code olhou só o log do build, viu que passou e decidiu que era “sucesso”. Mas a página de verdade estava carregando o template de outro artigo e o conteúdo veio vazio. Como o HTTP devolvia 200, do ponto de vista da máquina parecia uma “publicação bem-sucedida”.

Ali eu entendi na pele que velocidade e segurança são coisas diferentes. Quando você joga o deploy inteiro para a IA, parece que terminou num piscar de olhos. Só que, se não fica registrado o que foi conferido, na hora que cai você não sabe o que precisa reverter. Hoje vou mostrar a defesa que adotei: como juntar evidências num “deploy em seco” (dry run) antes de entregar o acesso de produção.

Pontos principais

A maioria dos acidentes ao deixar o Claude Code fazer deploy acontece porque alguém pulou a conferência antes de tocar em produção.
Antes de entregar o acesso de produção, confira em seco cinco coisas: build, diff, URL de preview, quem reverte e qual área você não mexeu.
Separar “o que a máquina consegue julgar” de “o que a pessoa precisa ver com os próprios olhos” reduz os acidentes de madrugada.
Deixo um modelo de prompt pronto para colar e um código que valida o resultado da conferência de forma automática.
Você não precisa de um regulamento perfeito desde o começo. Teste com uma correção pequena e vá somando à checklist os lugares onde tropeçou.

Acidente de deploy não vem de falta de inteligência, vem de falta de conferência

O Claude Code é esperto. Mas ser esperto e conseguir operar com segurança em produção são histórias diferentes.

É como aquele aluno que tira nota máxima na prova e, no primeiro dia de trabalho, quebra o caixa do mercado. Não é questão de capacidade, é questão de andaime. No deploy, o andaime é justamente “o que você confere antes de tocar em produção”.

Em deploy de site estático isso é ainda mais traiçoeiro, porque a falha avança em silêncio. O build passa, o HTTP devolve 200, e na aparência tudo deu certo. Mesmo com o conteúdo vazio, mesmo com a página trocada por outra, se você só olha o código de status nunca percebe. Por isso a pergunta não é “o código rodou?”, e sim “a página certa está aparecendo do jeito certo?” — e isso precisa de um olho humano pelo menos uma vez.

Os 5 passos do deploy em seco antes de tocar em produção

O procedimento que uso hoje é só isto. A ordem importa, então listei de cima para baixo.

Primeiro, faça o build passar localmente. Se cai aqui, nem adianta falar de produção. Você separa “problema de código” de “problema de ambiente” antes de tocar no que está no ar.
Leia o diff. Confira com os olhos se não entrou nada sensível (chave de API, token) nem mudança ligada a cobrança.
Abra a URL de preview. Veja na tela de verdade se o título (h1), a URL canônica (canonical) e o destino do botão de inscrição estão como você esperava.
Defina quem reverte e como reverte. Se falhar, quem volta ao estado anterior e com qual comando. Se você não decide isso antes, na hora do acidente você congela.
Só peça o acesso de produção depois que as evidências estiverem prontas. Quando os resultados de 1 a 4 estão na mesa, aí sim você pede o deploy de produção ao Claude Code.

Só de respeitar essa ordem, o acidente da “home em branco” do começo praticamente não acontece, porque no passo 3 você sempre abre o preview.

O que delegar à IA e o que a pessoa decide

Não é jogar tudo para a IA nem voltar tudo para o trabalho manual. A gente divide os papéis. A tabela abaixo é o meu corte na prática.

Situação	O que delegar ao Claude Code	Evidência que a pessoa vê
Publicar artigo	Rodar antes a verificação automática do build do dist e da URL publicada	Resultado do build, diff, URL
Trocar botão de inscrição	Casar o destino do link e o fluxo de contato no preview	Resultado do build, diff, URL
Corrigir o Workers	Sem tocar em variável de ambiente, só gerar o log do dry run	Resultado do build, diff, URL

A sacada é esta divisão: ler, organizar e checar por máquina vai para a IA; qualquer operação que faça uma mudança irreversível em produção precisa de aprovação humana. Apagar, escrever no banco de produção, cobrar, force push — no começo, deixe tudo em “pergunta para a pessoa”. Depois, só promova para automático as operações que você já sabe que são seguras.

Quem quer definir o corte de permissões com mais detalhe vai gostar do guia de configuração de permissões do Claude Code e da auditoria de permissões antes do deploy.

Modelo de prompt pronto para colar

O truque é não largar o pedido no ar, e deixar explícito: “ainda NÃO suba para produção”. Você pode colar o modelo abaixo do jeito que está.

Converta esta mudança em uma "checklist de deploy em seco" antes de subir para produção.
Devolva os seguintes itens em forma de tabela:
- Resultado do build (sucesso / falha com os pontos principais do log)
- Risco do diff (se contém dado sensível, cobrança ou exclusão)
- URL de preview
- Quem reverte e qual o comando de rollback
- Áreas que NÃO foram tocadas
- Condições para uma nova tentativa
Não execute o deploy de produção ainda. Espere até eu confirmar a checklist.

As duas últimas linhas fazem diferença. Quando você escreve “ainda não execute” e “espere até eu confirmar”, evita o acidente em que o Claude Code resolve “ajudar” e publica sozinho. Esse jeito de escrever inclinando o prompt para o lado seguro também está reunido no design de prompts para usuários avançados.

Script de verificação pronto para rodar

Quando você julga o resultado da conferência por máquina, em vez de “pelo feeling”, os escapes diminuem. O script abaixo recebe o objeto com o resultado do dry run e devolve um booleano dizendo se está num estado em que dá para pedir o acesso de produção. Tendo Node.js, ele roda direto.

// Resultado do dry run. Coloque aqui o conteúdo real da conferência
const deployCheck = {
  build: "passed",              // o build local passou?
  diffReviewed: true,           // você revisou o diff com os olhos?
  previewUrl: "https://example.pages.dev", // URL de preview
  rollbackOwner: "Masa",        // quem reverte
  changedAreas: ["content", "cta-copy"],   // áreas tocadas
};

// Porteiro que decide se já dá para pedir o acesso de produção
function canRequestProductionAccess(check) {
  return (
    check.build === "passed" &&          // o build passou
    check.diffReviewed &&                // você viu o diff
    /^https:\/\//.test(check.previewUrl) && // existe URL de preview em https
    check.rollbackOwner.length > 0 &&    // tem alguém para reverter
    !check.changedAreas.includes("secrets") // não tocou em área sensível
  );
}

const ready = canRequestProductionAccess(deployCheck);
console.log({ ready });
// Enquanto houver item false, não peça o deploy de produção

O valor desse código está em devolver false no instante em que "secrets" entra em changedAreas. Com algo sensível tocado por descuido, ele nunca deixa você avançar até o pedido de acesso de produção. Mesmo que a pessoa esteja atarefada e deixe passar, o porteiro segura.

Três situações em que isso funcionou de verdade

A primeira é publicar artigo. Se você só diz “publica o blog”, ele já corre até a publicação no momento em que o build passa. Encaixando o dry run, você abre a URL publicada e confere antes se o título bate com o conteúdo, e o acidente da tela branca do começo para de acontecer.

A segunda é trocar o botão de inscrição. Basta errar uma letra no destino do link e todo o fluxo cai num 404. Depois que passei a abrir o preview e literalmente clicar no botão para conferir o destino, os links quebrados foram a zero.

A terceira é corrigir o Cloudflare Workers. Aqui, apagar uma única variável de ambiente já derruba produção. Por isso, no dry run eu não deixo tocar em variável de ambiente, só gerar o log. Os cuidados específicos do Workers também estão reunidos no artigo sobre integração com Cloudflare Workers.

Armadilhas comuns e como corrigir

Três erros que eu mesmo cometi de verdade, e como consertei cada um.

Armadilha 1: rodar o comando de produção antes do build. Se você dispara wrangler deploy de cara, quando falha não dá para separar se a culpa é do código ou do ambiente. A correção é simples: sempre passe o build local primeiro. Mudar uma única posição na ordem deixa a investigação de causa muito mais rápida.

Armadilha 2: não definir quem reverte. Se você só começa a discutir “quem volta isso?” depois da falha, esses minutos de conversa batem direto nos acessos. A correção é deixar por escrito, já na etapa do dry run, quem reverte e qual o comando de rollback. Só de anotar o previousDeployId, a recuperação já fica mais calma.

Armadilha 3: confiar só no código de status, sem abrir o preview. HTTP 200 significa apenas “o servidor devolveu alguma coisa”, não “a página certa apareceu”. A correção é abrir a URL de preview no navegador pelo menos uma vez e ver com os olhos o título, a URL canônica e a imagem de capa. Foi o único jeito que tive de pegar a tela branca do começo.

Guarde a evidência como “anotação que serve da próxima vez”

O que você conferiu no dry run, não apague na hora: reúna numa anotação curta e o próximo trabalho fica bem mais rápido.

Guardar isto já basta: o texto do pedido inicial, o que o Claude Code leu, a área que ele não tocou, os comandos de verificação executados, a URL publicada ou um print, e os pontos em que você ficou na dúvida. Ata de reunião comprida não precisa. Se depois der para entender “por que essa decisão foi tomada”, o objetivo está cumprido.

O que mais ajuda é escrever em uma linha o “ponto de bifurcação da decisão”. Por exemplo: “a URL de preview está certa, mas como ninguém ficou de reverter, produção ainda não”. Da próxima vez que fizer o mesmo trabalho, você ou outra pessoa conseguem reproduzir a mesma conferência. Essa mesma ideia serve para outras automações além de deploy, então ler junto com a introdução ao Claude Code para quem não é da área técnica ajuda a pegar o jeito de delegar.

Perguntas frequentes

P. No fim das contas, o dry run não é só mais trabalho? No começo dá essa sensação. Mas, quando acontece um acidente, a recuperação e a investigação da causa consomem horas. O dry run leva alguns minutos. Eu continuo fazendo porque é um seguro que compensa.

P. Se o build local passa, posso deixar de ver o preview? Não pode. Mesmo com o build passando, acontece template trocado e página vazia. HTTP 200 e “página certa” são coisas diferentes, então o olho humano não dá para pular.

P. Faz sentido definir quem reverte mesmo trabalhando sozinho? Faz. Mesmo sozinho, deixar por escrito antes “se falhar, reverto com este comando” tira a hesitação na hora do acidente. Decidir isso já vira parte do procedimento.

P. Se o Claude Code disser “publicado”, posso confiar? Mais do que na resposta em si, olhe as evidências do dry run. Você decide pela presença de build, diff, preview e responsável pela reversão. Palavra é clima; evidência é fato.

P. Preciso de tudo isso mesmo em um site pequeno? Pense menos no tamanho e mais no “dá para reverter?”. Pequeno ou não, se produção cai, dá problema. Comece colocando só o único passo de abrir o preview e você já sente o efeito.

O que eu confirmei na prática

Depois do acidente da tela branca do começo, encaixei esse procedimento de dry run na operação do meu próprio blog.

Confirmei três coisas. Primeira: ao virar regra sempre abrir a URL de preview, as páginas vazias por troca de template foram a zero. Segunda: passando a rodar o script de verificação acima antes de publicar, mudanças que tocavam área sensível paravam em ready: false e não avançavam até o pedido de acesso de produção. Terceira: anotando todas as vezes quem reverte e o comando de rollback, mesmo nos sustos eu conseguia voltar ao estado anterior em poucos minutos.

Em vez de jogar tudo para uma IA esperta e rezar, construa antes um andaime em que, se você cair, não se machuca. Parece volta, mas no fim é o caminho mais rápido — é o que sinto hoje. Comece pelo único passo de abrir o preview e vá somando um porteiro ao seu deploy.

Se você quer organizar, em time, o corte do deploy de produção e até o esquema de revisão, dá para transformar isso em procedimento junto no treinamento e consultoria. Para o critério oficial de operação, consulte também a documentação oficial do Claude Code da Anthropic.