Lancar

Lançamento

Visão geral

Lance com confiança. O objetivo não é apenas fazer deploy — é fazer deploy com segurança, com monitoramento no lugar, plano de rollback pronto e entendimento claro do que é sucesso. Todo lançamento deve ser reversível, observável e incremental.

Quando usar

• Ao levar uma funcionalidade a produção pela primeira vez
• Ao liberar uma mudança significativa para os usuários
• Ao migrar dados ou infraestrutura
• Ao abrir um programa de beta ou acesso antecipado
• Em qualquer deploy que carregue risco (ou seja, todos)

Quando NÃO usar: para escrever a instrumentação que alimenta o monitoramento, use antes a skill observabilidade; para registrar as decisões da versão, use a skill documentar.

O fluxo

1. Checklist pré-lançamento

Qualidade de código

• Todos os testes passam (unitários, integração, e2e)
• Build sem warnings; lint e checagem de tipos passam
• Código revisado e aprovado
• Nenhum TODO pendente que deveria ser resolvido antes do lançamento
• Nenhum console.log de depuração em código de produção
• Tratamento de erros cobre os modos de falha esperados

Segurança — leia referencias/seguranca.md somente quando chegar nesta etapa. Mínimo: sem segredos no código, npm audit sem vulnerabilidades críticas/altas, validação de entrada em todos os endpoints, autenticação/autorização no lugar, headers de segurança, rate limiting em autenticação, CORS restrito a origens específicas.

Performance — leia referencias/performance.md somente quando chegar nesta etapa. Mínimo: Core Web Vitals na faixa "Boa", sem consultas N+1 em caminhos críticos, imagens otimizadas, bundle dentro do orçamento, índices e cache configurados.

Acessibilidade — leia referencias/acessibilidade.md somente quando chegar nesta etapa. Mínimo: navegação por teclado completa, leitor de tela funcional, contraste WCAG 2.1 AA, gestão de foco em modais, sem alertas no axe-core/Lighthouse.

Infraestrutura

• Variáveis de ambiente configuradas em produção
• Migrações de banco aplicadas (ou prontas para aplicar)
• DNS, SSL e CDN configurados
• Logging e relatório de erros configurados
• Endpoint de health check existe e responde

Documentação

• README, documentação de API e changelog atualizados
• ADRs escritos para as decisões arquiteturais (veja a skill documentar)
• Documentação voltada ao usuário atualizada (se aplicável)

O piso de tudo isso é a Definição de Pronto do projeto — veja referencias/definicao-de-pronto.md.

2. Estratégia de feature flags

Lance atrás de feature flags para desacoplar deploy de release:

const flags = await getFeatureFlags(userId);

if (flags.taskSharing) {
  // Funcionalidade nova: compartilhamento de tarefas
  return <TaskSharingPanel task={task} />;
}
return null; // Padrão: comportamento existente

Ciclo de vida da flag:

1. DEPLOY com flag OFF        → código em produção, mas inativo
2. ATIVAR para time/beta      → teste interno no ambiente de produção
3. ROLLOUT GRADUAL            → 5% → 25% → 50% → 100% dos usuários
4. MONITORAR em cada etapa    → taxa de erro, performance, feedback
5. LIMPAR                     → remover flag e código morto após rollout completo

Regras: toda flag tem dono e data de expiração; limpe flags em até 2 semanas após o rollout completo; não aninhe flags (combinações exponenciais); teste os dois estados (on e off) no CI.

3. Rollout em etapas

1. DEPLOY em staging          → suíte completa + smoke test manual dos fluxos críticos
2. DEPLOY em produção (OFF)   → verificar health check e monitoramento de erros
3. ATIVAR para o time         → uso interno em produção, janela de 24h
4. CANÁRIO (5% dos usuários)  → comparar métricas canário vs. baseline, 24–48h
                              → avance apenas se todos os limiares passarem
5. AUMENTO GRADUAL            → 25% → 50% → 100%, mesmo monitoramento em cada passo
6. ROLLOUT COMPLETO           → monitorar por 1 semana, limpar a feature flag

Limiares de decisão em cada etapa:

Métrica	Avançar (verde)	Segurar e investigar (amarelo)	Rollback (vermelho)
Taxa de erro	Até 10% acima do baseline	10–100% acima	>2x o baseline
Latência p95	Até 20% acima do baseline	20–50% acima	>50% acima
Erros de JS no cliente	Nenhum tipo novo de erro	Erros novos em <0,1% das sessões	Erros novos em >0,1% das sessões
Métricas de negócio	Neutras ou positivas	Queda <5% (pode ser ruído)	Queda >5%

Faça rollback imediatamente se: taxa de erro >2x o baseline, latência p95 >50% acima, pico de reclamações de usuários, problemas de integridade de dados ou vulnerabilidade de segurança descoberta.

4. Monitoramento

Monitore três camadas — a instrumentação vem da skill observabilidade:

• Aplicação: taxa de erro (total e por endpoint), tempo de resposta (p50/p95/p99), volume de requisições, usuários ativos, métricas-chave de negócio
• Infraestrutura: CPU e memória, pool de conexões do banco, disco, latência de rede, profundidade de fila
• Cliente: Core Web Vitals (LCP, INP, CLS), erros de JavaScript, taxa de erro de API vista do cliente, tempo de carregamento

Configure relatório de erros nos dois lados: error boundary no cliente reportando ao serviço de rastreamento, e middleware de erro no servidor que reporta internamente mas devolve ao usuário apenas um erro genérico ({ code: 'INTERNAL_ERROR' }), nunca stack traces ou detalhes internos.

Verificação pós-lançamento (primeira hora):

1. Health check retorna 200
2. Painel de erros sem tipos novos de erro
3. Painel de latência sem regressão
4. Fluxo crítico do usuário testado manualmente
5. Logs fluindo e legíveis
6. Mecanismo de rollback confirmado (dry run se possível)

5. Estratégia de rollback

Todo deploy precisa de um plano de rollback escrito ANTES de acontecer:

## Plano de rollback para [funcionalidade/versão]

### Condições de gatilho
- Taxa de erro > 2x o baseline
- Latência p95 > [X]ms
- Relatos de usuários sobre [problema específico]

### Passos
1. Desativar a feature flag (se aplicável)
   OU
1. Fazer deploy da versão anterior: `git revert <commit> && git push`
2. Verificar o rollback: health check, monitoramento de erros
3. Comunicar: avisar o time sobre o rollback

### Considerações de banco de dados
- A migração [X] tem rollback: `npx prisma migrate rollback`
- Dados inseridos pela funcionalidade nova: [preservados / limpos]

### Tempo estimado
- Feature flag: < 1 minuto | Redeploy da versão anterior: < 5 minutos | Rollback de banco: < 15 minutos

Racionalizações comuns

Racionalização	Realidade
"Funciona em staging, vai funcionar em produção"	Produção tem outros dados, padrões de tráfego e casos de borda. Monitore após o deploy.
"Não precisamos de feature flag para isso"	Toda funcionalidade se beneficia de um botão de desligar. Até mudanças "simples" quebram coisas.
"Monitoramento é sobrecarga"	Sem monitoramento, você descobre problemas por reclamação de usuário em vez de por dashboard.
"Adicionamos monitoramento depois"	Adicione antes do lançamento. Você não depura o que não enxerga.
"Fazer rollback é admitir fracasso"	Rollback é engenharia responsável. Manter uma funcionalidade quebrada no ar é que é o fracasso.

Sinais de alerta

• Deploy sem plano de rollback
• Sem monitoramento nem relatório de erros em produção
• Releases big-bang (tudo de uma vez, sem staging)
• Feature flags sem expiração nem dono
• Ninguém monitorando o deploy na primeira hora
• Configuração do ambiente de produção feita de memória, não como código
• "É sexta-feira à tarde, bora lançar"

Portão de aprovação

Apresente: o checklist pré-lançamento preenchido (com o status de cada seção), o plano de rollout em etapas com os limiares, e o plano de rollback documentado. O humano aprova: a decisão de ir para produção (go/no-go), o cronograma do rollout gradual e as condições de gatilho do rollback. Só execute o deploy após aprovação explícita — e reapresente os números ao humano antes de cada avanço de percentual do rollout.

Verificação

Antes do deploy:

• Checklist pré-lançamento completo (todas as seções verdes)
• Feature flag configurada (se aplicável)
• Plano de rollback documentado
• Dashboards de monitoramento prontos
• Time avisado do deploy

Depois do deploy:

• Health check retorna 200
• Taxa de erro normal e latência normal
• Fluxo crítico do usuário funciona
• Logs fluindo
• Rollback testado ou confirmado como pronto