Release Agent com Claude Code: do diff ao deploy com gates verificáveis · andersonlimadev

English summary: A release agent should turn a release candidate into an evidence-backed decision, not an unattended path to production. This guide shows how to use Claude Code to assemble changelogs, CI evidence, migration and rollback checks, approvals, and environment gates while keeping production off by default.

TL;DR

Um release agent prepara uma decisão; não publica sozinho.
Colete CI, migrações, rollback, aprovação e contexto de ambiente.
Mantenha produção bloqueada por padrão.

Exemplo concreto: CI verde libera a próxima avaliação, mas não substitui a aprovação do ambiente de produção.

O diff parece pequeno. A CI está verde. Alguém já escreveu “pode subir?” no canal.

É exatamente nesse momento que uma release vira uma decisão ruim: o time trata a ausência de um erro visível como evidência de que nada importante falta. Não viu a migration incompatível, o flag que ainda não existe no ambiente, a mudança de permissão no workflow, o rollback que depende de um artefato não preservado ou a aprovação dada por quem também preparou a mudança.

Um agent pode reduzir o trabalho repetitivo desse ritual, mas não deve transformar “CI verde” em autorização implícita para produção. Minha tese é: um release agent útil coleta, organiza e testa a evidência para uma decisão humana; ele não recebe o poder de fazer deploy por padrão.

Neste guia, Claude Code é o harness que lê o repositório, consulta os sistemas permitidos e produz um pacote de prontidão. A pipeline continua sendo a autoridade que entrega. O ambiente continua sendo a fronteira de credenciais. E uma pessoa nomeada continua sendo responsável por aprovar a transição irreversível ou de alto impacto.

O que é — e o que não é — um release agent

Um release agent recebe uma referência de release — tag candidata, PR, intervalo de commits ou versão — e responde uma pergunta operacional: temos evidência suficiente para promover este artefato para o próximo ambiente? Para isso, ele correlaciona diff, mudanças de configuração, testes, status da CI, changelog, migrations, artefato, plano de rollback e aprovações necessárias. O resultado desejado não é uma frase tranquilizadora; é um relatório rastreável que separa fatos, lacunas e decisões pendentes.

Ele não é:

um botão com LLM para publicar em produção;
um substituto para branch protection, IAM, secrets de ambiente ou CI;
uma garantia de que uma migration é segura, porque o modelo leu SQL;
um agente de incidentes com liberdade para “consertar” produção;
uma aprovação humana decorativa depois que as credenciais já foram liberadas.

Há casos em que um workflow comum é melhor. Se toda release é uma imagem imutável promovida por um pipeline determinístico e os checks já são estruturados, um job de CI pode montar o manifesto sem agent. Use um agent quando a evidência está espalhada entre diff, tickets, documentação de migration, logs de CI e contratos de serviço, e alguém ainda precisa interpretar o conjunto. Não use um loop agentic para executar uma lista fixa de comandos.

No GitHub Actions, um job que referencia um environment só começa após as regras de proteção passarem; seus secrets de environment ficam indisponíveis antes disso.[^github-environments] Essa é a ordem correta: o agent prepara a decisão sem precisar de segredo de produção; o gate independente libera o job apenas depois da decisão humana e das políticas do ambiente.

Quatro falhas que se escondem atrás de uma CI verde

1. Changelog automático que inventa significado

Gerar notas a partir de títulos de PR ajuda, mas não explica impacto. Um PR chamado “fix checkout” pode alterar schema, contrato de webhook, política de cache e experiência do usuário. Um agente que só resume commits produz uma narrativa elegante e perigosa.

Peça ao agent para classificar cada mudança por superfície: API pública, dados, credencial, feature flag, infraestrutura, dependência, observabilidade e reversibilidade. Ele deve citar o arquivo, PR ou ticket que sustenta cada item e marcar explicitamente o que não conseguiu confirmar. Changelog é comunicação; não é prova de prontidão.

2. O check passou, mas a evidência não pertence ao candidato

É comum ver um link verde para uma execução antiga, para outro SHA ou para uma matriz que pulou justamente a plataforma afetada. Também é comum a CI mostrar “success” depois de um job opcional falhar.

O contrato do release agent precisa ligar cada evidência a uma identidade imutável: commit SHA, versão do artefato, workflow run, timestamp, ambiente e política avaliada. “Os testes passaram ontem” não é uma evidência; “o workflow X passou no SHA Y, produziu a imagem com digest Z e executou a migration check W” é. O agent pode coletar esses vínculos; a CI e o registry continuam sendo as fontes de verdade.

3. Migration tratada como arquivo, não como mudança de estado

Uma migration não é segura por ter review. A pergunta é o que acontece quando versões antiga e nova convivem, quando o deploy falha no meio, quando o backfill demora e quando o rollback encontra dados que o binário anterior não entende.

O padrão mais seguro costuma ser expandir, compatibilizar e só depois contrair: adicionar campos/índices de forma compatível, publicar código que lê os dois formatos, migrar dados e observar, então remover o caminho antigo numa release posterior. Nem todo banco, índice ou ORM permite a mesma estratégia; o agent deve exigir o runbook específico, não inventar uma resposta genérica. Se a mudança não tem plano de reversão, janela, owner e evidência em staging, ela não está pronta para promoção automática.

4. “Rollback existe” sem artefato, gatilho ou autoridade

Um README dizendo “basta voltar a versão anterior” é insuficiente. Talvez a imagem não esteja preservada, o deploy não aceite pin de digest, a migration tenha destruído compatibilidade ou ninguém saiba quem pode interromper o rollout.

O pacote de release deve identificar: artefato anterior e candidato, comando ou workflow de reversão, condição que dispara rollback, métrica a observar, dono de plantão e quem aprova uma ação excepcional. Rollback não é o final da história; às vezes é feature flag off, pausa de tráfego, restauração de backup ou roll-forward. O importante é que o mecanismo e o limite estejam declarados antes do deploy.

O harness Claude Code: análise com fronteiras reais

Claude Code pode organizar o trabalho de investigação porque opera com contexto do repositório, tools e permissões. Isso não elimina as fronteiras que o modelo não controla. Um release harness maduro separa as camadas:

Camada	Responsabilidade	Não deve fazer
`CLAUDE.md` e skill	contrato, comandos permitidos, formato do relatório	conceder credencial ou autorizar produção
Agent especializado	ler diff, correlacionar evidência, detectar lacunas	fazer deploy ou mudar estado remoto por padrão
CLI/MCP de leitura	consultar CI, PRs, registry e observabilidade aprovados	receber tokens amplos ou dados desnecessários
CI/CD	construir, testar, assinar/publicar artefato	aceitar texto do agent como check conclusivo
Environment/IAM	restringir secrets, branches, approvals e deploy	depender de uma instrução em linguagem natural
Dono humano	aceitar risco, aprovar promoção, liderar rollback	delegar responsabilidade sem examinar evidência

A documentação do Claude Code descreve permissões e hooks como controles do uso de tools; use-os para reduzir a superfície local, não como substitutos de autorização do provedor.[^claude-permissions][^claude-hooks] Um hook pode bloquear kubectl ou terraform apply no caminho observado, mas não protege uma credencial que também funciona fora do Claude Code. A proteção real vem de identidade com menor privilégio, jobs separados por ambiente e regras aplicadas pelo provedor.

Um contrato de release que força o agent a parar

Coloque o contrato no projeto, versão-controlado e revisável. Este artefato é copiável, mas deliberadamente não contém credenciais nem comando de produção:

# Release readiness contract

## Default posture
- O agent é somente leitura. Nunca inicia deploy, publica tag, altera flag ou executa migration.
- Produção exige um workflow de CI separado, environment `production` protegido e aprovação humana externa ao agent.

## Entrada
- Candidate: SHA, tag ou imagem por digest.
- Scope: intervalo de commits e serviços afetados.

## Evidência mínima
1. SHA e digest do artefato candidato, mais o artefato anterior conhecido.
2. Workflows obrigatórios, cada um com URL, conclusão, SHA e horário.
3. Changelog por impacto, com links para PRs/issues e incertezas explícitas.
4. Migrations: compatibilidade, backfill, validação em staging, janela e owner.
5. Rollback: gatilho, procedimento, artefato, métrica e responsável de plantão.
6. Environments: alvo, branch permitida, proteção e aprovações ainda pendentes.

## Saída
- `READY`, `NOT_READY` ou `NEEDS_DECISION`; nunca "aprovado".
- Cada conclusão aponta para evidência; ausência de evidência é bloqueador.

O vocabulário importa. READY significa que o pacote está completo para avaliação do responsável, não que o agent concedeu permissão. NEEDS_DECISION é melhor que uma suposição quando produto, risco ou janela são ambíguos.

A escada incremental: do trabalho à autonomia delimitada

Não conecte produção no primeiro dia. Suba uma escada em que cada degrau produz evidência para o próximo.

Trabalho — comece com “montar prontidão de release para o SHA X, somente leitura”. Defina uma pessoa de release e um horário de corte.
Contrato — declare fontes permitidas, checks obrigatórios, ambientes, política para falta de evidência e formato de saída. Isso cabe em CLAUDE.md e numa skill de release.
Skill — encapsule a sequência repetida: ler diff, classificar impacto, consultar CI, procurar migrations e elaborar checklist. A skill não recebe ferramenta de escrita.
Agent — isole o contexto em um subagent de release-readiness com Read, Glob, Grep e, se aprovado, CLI de leitura para GitHub/observabilidade. Ele devolve referências, não comandos destrutivos.
Hooks/MCP — use hooks para negar shells de deploy local; use MCP apenas para fontes externas que melhoram a decisão e cujo owner, scopes e retenção são conhecidos. Uma integração a mais é uma superfície a mais de falha e prompt injection.
Autonomia limitada — permita ao agent abrir um comentário de draft ou atualizar um artefato interno apenas depois de medir qualidade e com permissão específica. Mantenha tag, release, deploy e migration fora desse escopo.
Evals — congele cenários de release limpa, CI em SHA errado, migration incompatível, artefato ausente, aprovação própria e rollback não testado. O resultado esperado é uma decisão e evidência, não uma prosa convincente.

Uma configuração de subagent pode deixar o limite explícito:

---
name: release-readiness
description: Monta evidência de release sem executar mudanças remotas.
tools: Read, Glob, Grep, Bash
permissionMode: default
---

Você analisa candidatos de release em modo somente leitura.

- Pode executar apenas comandos locais de leitura e consultas autorizadas de status.
- Nunca execute deploy, publish, tag, push, migration, alteração de flag ou escrita remota.
- Para cada check, registre URL/ID, SHA, horário e resultado.
- Se migration, rollback, aprovação ou artefato não tiver evidência, responda `NOT_READY` ou `NEEDS_DECISION`.

Bash ainda é poderoso; as restrições no prompt não bastam. Combine o escopo mínimo com permissions e um PreToolUse que bloqueie padrões de escrita remota. Teste o hook com comandos compostos e falhas; não anuncie cobertura total de shell. A referência oficial de hooks detalha que a decisão pré-tool pode bloquear uma chamada antes do efeito, enquanto uma ação pós-tool já observa algo que ocorreu.[^claude-hooks]

Artefato executável: uma coleta de evidência que não faz deploy

O script abaixo aceita SHA, lista comandos de verificação locais e escreve um manifesto. Ele não chama deploy, não usa secrets e falha se não receber um candidato. Ajuste os comandos ao repositório e execute em um clone seguro. Ele não substitui a CI nem prova que serviços externos estão saudáveis.

#!/usr/bin/env bash
set -euo pipefail

candidate="${1:?usage: scripts/release-evidence.sh <candidate-sha>}"
output="release-evidence-${candidate:0:12}.md"

git rev-parse --verify "${candidate}^{commit}" >/dev/null

{
  printf '# Release evidence for `%s`\n\n' "$candidate"
  printf 'Generated (UTC): %s\n\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
  printf '## Changed files\n\n```text\n'
  git diff --name-status "${candidate}^" "$candidate"
  printf '```\n\n## Local checks\n\n'

  for check in 'pnpm lint' 'pnpm test' 'pnpm build'; do
    printf -- '- `%s`: ' "$check"
    if eval "$check" >/tmp/release-check.log 2>&1; then
      printf 'passed\n'
    else
      printf 'failed (inspect CI/local log; no promotion)\n'
      exit 1
    fi
  done

  printf '\n## Required human decisions\n\n'
  printf -- '- [ ] CI runs are tied to this SHA and the candidate artifact digest.\n'
  printf -- '- [ ] Migration compatibility and staging evidence are attached.\n'
  printf -- '- [ ] Rollback trigger, owner and previous artifact are confirmed.\n'
  printf -- '- [ ] Protected environment approval is pending from an authorized reviewer.\n'
} >"$output"

printf 'Wrote %s\n' "$output"

Há duas lições deliberadas nesse exemplo. Primeiro, ele trata falha de check como parada, não como texto para contornar. Segundo, ele não tenta consultar ou acionar produção. Se precisar enriquecer o manifesto com CI, use uma conta de leitura e registre URLs e IDs; não copie tokens, logs sensíveis ou output de comandos para o arquivo.

Migrations, rollback e environments: onde a decisão precisa ficar firme

Uma matriz simples evita que “deploy” esconda estados com riscos muito diferentes:

Decisão	Padrão conservador	Quem decide	Evidência exigida
Promover para dev/preview	pipeline automático, artefato identificado	time do serviço	CI e smoke test
Promover para staging	workflow controlado, sem credencial de produção	owner técnico	integração, migration check, observabilidade
Migration com backfill	execução separada, limitada e monitorada	owner de dados + serviço	plano expand/contract, janela, métricas e stop condition
Promover para produção	nunca pelo agent por padrão	aprovador de environment/release manager	pacote completo, gates, aprovação e rollback
Rollback/pausa	caminho pré-definido e auditável	on-call/release manager	trigger, artefato anterior, comunicação e métricas

GitHub environments permitem restrições de branch/tag, reviewers obrigatórios, timer e regras de proteção; quando um environment exige aprovação, o job não recebe seus secrets até as regras passarem.[^github-environments] Configure “prevent self-review” quando a sua política exigir separação de funções e considere impedir bypass administrativo para ambientes críticos, conforme o modelo de governança da organização.[^github-review]

Isso não significa que todo deploy precisa de uma cerimônia manual idêntica. Um ambiente de preview pode ser automático; produção pode exigir uma mudança de classe de confiança. A regra é proporcionalidade: quanto maior o raio de impacto e menor a reversibilidade, mais independente deve ser a autorização e mais concreta deve ser a evidência.

Segurança, ownership e verificação

Não dê ao release agent um token capaz de fazer tudo “para simplificar”. Separe identidades: uma para leitura de CI e metadata, outra para publicar artefatos, outra — protegida pelo environment — para deploy. Limite a primeira ao que ela realmente consulta. Em runners self-hosted, environments não tornam automaticamente a máquina isolada; trate secrets e código não confiável com as precauções do próprio GitHub.[^github-runner-security]

Nomeie donos antes de operar:

owner do harness mantém skill, prompt, evals, hooks e seus limites;
owner do serviço confirma impacto funcional, migration e compatibilidade;
owner da plataforma mantém CI, environment, registry e credenciais;
release manager/on-call toma a decisão de promoção, pausa ou rollback;
security define acesso, retenção de evidência e exceções.

Verifique o loop inteiro, não só o texto final. Escolha um candidato de baixo risco e simule: uma CI de SHA errado, uma migration sem rollback, um artefato ausente, uma aprovação que tenta revisar a própria execução e um deploy bloqueado pelo environment. Em cada caso, o agent deve produzir NOT_READY ou NEEDS_DECISION, a política deve impedir a ação e o responsável deve conseguir localizar a evidência. Meça também falsos positivos: um gate ignorado de forma rotineira é um controle que perdeu legitimidade.

Checklist operacional de release

O candidato é identificado por SHA e digest, não só por nome de branch.
O diff e o changelog classificam impacto, incertezas e mudanças de contrato.
Cada check obrigatório contém URL/ID, SHA, horário e conclusão verificável.
O agent opera em leitura por padrão e não possui credencial de produção.
Migrations têm compatibilidade, staging evidence, janela, owner e condição de parada.
O artefato anterior e o procedimento de rollback foram confirmados antes da promoção.
Environments separam preview, staging e produção com policies explícitas.
Aprovação de produção é independente; autoaprovação e bypass seguem política documentada.
Logs e manifestos não expõem secrets, prompts ou dados de clientes sem necessidade.
Evals cobrem evidência ausente, CI divergente, migration arriscada e rollback inviável.
A decisão final, o aprovador e os links de evidência ficam registrados no sistema de release.

Conclusão: automatize a preparação, não a responsabilidade

Um release agent bem desenhado torna uma reunião de “parece pronto” em uma decisão examinável. Ele reduz caça manual a links, revela as perguntas que ninguém respondeu e mantém o pacote de evidência perto do código. Esse é um ganho real.

Mas ele não torna produção segura por escrever um resumo melhor. Segurança vem de artefatos identificados, CI vinculada ao candidato, migrations tratadas como estado, rollback praticável, credenciais separadas, environments protegidos e pessoas que aceitam explicitamente a responsabilidade. Quando o custo de coordenação cai sem remover esses limites, o agent está trabalhando a favor do time. Quando ele transforma gates em passos que podem ser “inferidos”, virou uma nova fonte de risco.

Fontes primárias

Anthropic — Claude Code permissions (verificado em 12 de agosto de 2026)
Anthropic — Claude Code hooks (verificado em 12 de agosto de 2026)
Anthropic — Claude Code subagents (verificado em 12 de agosto de 2026)
GitHub Docs — Deployments and environments (verificado em 12 de agosto de 2026)
GitHub Docs — Reviewing deployments (verificado em 12 de agosto de 2026)
GitHub Docs — Secure use reference (verificado em 12 de agosto de 2026)