addyosmani/agent-skills

Envio e Lançamento

Visão Geral

Envie com confiança. O objetivo não é apenas implantar — é implantar com segurança, com monitoramento em vigor, um plano de rollback pronto e uma compreensão clara do que significa sucesso. Cada lançamento deve ser reversível, observável e incremental.

Quando Usar

• Implantar um recurso em produção pela primeira vez
• Liberar uma mudança significativa para os usuários
• Migrar dados ou infraestrutura
• Abrir um beta ou programa de acesso antecipado
• Qualquer implantação que envolva risco (todas elas)

A Lista de Verificação Pré-Lançamento

Qualidade do Código

• Todos os testes passam (unitários, integração, e2e)
• Build bem-sucedido sem avisos
• Lint e verificação de tipos passam
• Código revisado e aprovado
• Nenhum comentário TODO que deva ser resolvido antes do lançamento
• Nenhuma instrução console.log de depuração no código de produção
• Tratamento de erros cobre modos de falha esperados

Segurança

• Nenhum segredo no código ou controle de versão
• A auditoria de dependências do ecossistema (npm audit, pip-audit, cargo audit, ...) não mostra vulnerabilidades críticas ou altas
• Validação de entrada em todos os endpoints voltados para o usuário
• Verificações de autenticação e autorização em vigor
• Cabeçalhos de segurança configurados (CSP, HSTS, etc.)
• Limitação de taxa em endpoints de autenticação
• CORS configurado para origens específicas (não curinga)

Desempenho

• Core Web Vitals dentro dos limites "Bom"
• Nenhuma consulta N+1 em caminhos críticos
• Imagens otimizadas (compressão, tamanhos responsivos, carregamento preguiçoso)
• Tamanho do bundle dentro do orçamento
• Consultas de banco de dados têm índices apropriados
• Cache configurado para ativos estáticos e consultas repetidas

Acessibilidade

• Navegação por teclado funciona para todos os elementos interativos
• Leitor de tela pode transmitir conteúdo e estrutura da página
• Contraste de cores atende WCAG 2.1 AA (4.5:1 para texto)
• Gerenciamento de foco correto para modais e conteúdo dinâmico
• Mensagens de erro são descritivas e associadas aos campos do formulário
• Nenhum aviso de acessibilidade no axe-core ou Lighthouse

Infraestrutura

• Variáveis de ambiente definidas em produção
• Migrações de banco de dados aplicadas (ou prontas para aplicar)
• DNS e SSL configurados
• CDN configurado para ativos estáticos
• Logging e relatórios de erro configurados
• Endpoint de verificação de integridade existe e responde

Documentação

• README atualizado com quaisquer novos requisitos de configuração
• Documentação da API atualizada
• ADRs escritos para quaisquer decisões arquiteturais
• Changelog atualizado
• Documentação voltada para o usuário atualizada (se aplicável)

Estratégia de Feature Flag

Envie atrás de feature flags para desacoplar implantação de liberação:

// Verificação de feature flag
const flags = await getFeatureFlags(userId);

if (flags.taskSharing) {
  // Novo recurso: compartilhamento de tarefas
  return <TaskSharingPanel task={task} />;
}

// Padrão: comportamento existente
return null;

Ciclo de vida da feature flag:

1. IMPLANTAR com flag DESLIGADA     → Código está em produção, mas inativo
2. ATIVAR para equipe/beta          → Teste interno no ambiente de produção
3. IMPLANTAÇÃO GRADUAL              → 5% → 25% → 50% → 100% dos usuários
4. MONITORAR em cada etapa          → Observar taxas de erro, desempenho, feedback dos usuários
5. LIMPAR                           → Remover flag e caminho de código morto após implantação completa

Regras:

• Cada feature flag tem um proprietário e uma data de expiração
• Limpe as flags dentro de 2 semanas após a implantação completa
• Não aninhe feature flags (cria combinações exponenciais)
• Teste ambos os estados da flag (ligado e desligado) no CI

Implantação em Etapas

A Sequência de Implantação

1. IMPLANTAR no staging
   └── Suíte de testes completa no ambiente de staging
   └── Teste smoke manual dos fluxos críticos

2. IMPLANTAR em produção (feature flag DESLIGADA)
   └── Verificar se a implantação foi bem-sucedida (health check)
   └── Verificar monitoramento de erros (nenhum novo erro)

3. ATIVAR para a equipe (flag LIGADA para usuários internos)
   └── Equipe usa o recurso em produção
   └── Janela de monitoramento de 24 horas

4. IMPLANTAÇÃO CANÁRIO (flag LIGADA para 5% dos usuários)
   └── Monitorar taxas de erro, latência, comportamento do usuário
   └── Comparar métricas: canário vs. linha de base
   └── Janela de monitoramento de 24-48 horas
   └── Avançar apenas se todos os limites forem aprovados (ver tabela abaixo)

5. AUMENTO GRADUAL (25% -> 50% -> 100%)
   └── Mesmo monitoramento em cada etapa
   └── Capacidade de reverter para a porcentagem anterior a qualquer momento

6. IMPLANTAÇÃO COMPLETA (flag LIGADA para todos os usuários)
   └── Monitorar por 1 semana
   └── Limpar a feature flag

Limites de Decisão da Implantação

Use estes limites para decidir se deve avançar, pausar ou reverter em cada etapa:

Métrica	Avançar (verde)	Pausar e investigar (amarelo)	Reverter (vermelho)
Taxa de erro	Dentro de 10% da linha de base	10-100% acima da linha de base	>2x linha de base
Latência P95	Dentro de 20% da linha de base	20-50% acima da linha de base	>50% acima da linha de base
Erros JS do cliente	Nenhum novo tipo de erro	Novos erros em <0.1% das sessões	Novos erros em >0.1% das sessões
Métricas de negócio	Neutro ou positivo	Declínio <5% (pode ser ruído)	Declínio >5%

Quando Reverter

Reverta imediatamente se:

• A taxa de erro aumentar mais de 2x a linha de base
• A latência P95 aumentar mais de 50%
• Problemas relatados por usuários dispararem
• Problemas de integridade de dados forem detectados
• Vulnerabilidade de segurança descoberta

Monitoramento e Observabilidade

O que Monitorar

Métricas da aplicação:
├── Taxa de erro (total e por endpoint)
├── Tempo de resposta (p50, p95, p99)
├── Volume de requisições
├── Usuários ativos
└── Principais métricas de negócio (conversão, engajamento)

Métricas de infraestrutura:
├── Utilização de CPU e memória
├── Uso do pool de conexões do banco de dados
├── Espaço em disco
├── Latência de rede
└── Profundidade da fila (se aplicável)

Métricas do cliente:
├── Core Web Vitals (LCP, INP, CLS)
├── Erros JavaScript
├── Taxas de erro de API da perspectiva do cliente
└── Tempo de carregamento da página

Relatórios de Erro

// Configurar boundary de erro com relatório
class ErrorBoundary extends React.Component {
  componentDidCatch(error: Error, info: React.ErrorInfo) {
    // Reportar ao serviço de rastreamento de erros
    reportError(error, {
      componentStack: info.componentStack,
      userId: getCurrentUser()?.id,
      page: window.location.pathname,
    });
  }

  render() {
    if (this.state.hasError) {
      return <ErrorFallback onRetry={() => this.setState({ hasError: false })} />;
    }
    return this.props.children;
  }
}

// Relatório de erro no servidor
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  reportError(err, {
    method: req.method,
    url: req.url,
    userId: req.user?.id,
  });

  // Não expor detalhes internos aos usuários
  res.status(500).json({
    error: { code: 'INTERNAL_ERROR', message: 'Algo deu errado' },
  });
});

Verificação Pós-Lançamento

Na primeira hora após o lançamento:

1. Verificar se o endpoint de integridade retorna 200
2. Verificar o painel de monitoramento de erros (nenhum novo tipo de erro)
3. Verificar o painel de latência (nenhuma regressão)
4. Testar o fluxo crítico do usuário manualmente
5. Verificar se os logs estão fluindo e são legíveis
6. Confirmar que o mecanismo de rollback funciona (teste a seco, se possível)

Portão de Liberação do Orçamento de Erros

O orçamento de erros do seu serviço — a fração de requisições ou tempo que seu SLO permite falhar — determina se é seguro enviar. Use-o como um portão objetivo — não uma negociação:

Orçamento restante > 20%  →  Enviar normalmente; monitorar de perto
Orçamento restante 0–20%  →  Apenas implantações lentas; nenhuma mudança de alto risco
Orçamento esgotado        →  Congelar trabalho de recursos; focar inteiramente em confiabilidade
Orçamento reiniciado      →  Retomar ritmo normal; incorporar a correção que o recuperou

Uma alta taxa de consumo durante um canário (consumindo orçamento mais rápido que o ritmo da linha de base) é um sinal de pausa na tabela de limites de implantação acima — trate-o da mesma forma que uma taxa de erro elevada.

Estratégia de Rollback

Toda implantação precisa de um plano de rollback antes de acontecer:

## Plano de Rollback para [Recurso/Lançamento]

### Condições de Acionamento
- Taxa de erro > 2x linha de base
- Latência P95 > [X]ms
- Relatos de usuários sobre [problema específico]

### Passos do Rollback
1. Desabilitar a feature flag (se aplicável)
   OU
1. Implantar versão anterior: `git revert <commit> && git push`
2. Verificar rollback: health check, monitoramento de erros
3. Comunicar: notificar a equipe sobre o rollback

### Considerações sobre o Banco de Dados
- A migração [X] tem um rollback: `npx prisma migrate rollback`
- Dados inseridos pelo novo recurso: [preservados / limpos]

### Tempo para Rollback
- Feature flag: < 1 minuto
- Reimplantar versão anterior: < 5 minutos
- Rollback de banco de dados: < 15 minutos

Veja Também

• Para a Definição de Pronto (Definition of Done) do projeto que toda mudança deve atender antes desta lista de verificação, veja ../../references/definition-of-done.md
• Para verificações de segurança pré-lançamento, veja ../../references/security-checklist.md
• Para a lista de verificação de desempenho pré-lançamento, veja ../../references/performance-checklist.md
• Para verificação de acessibilidade antes do lançamento, veja ../../references/accessibility-checklist.md
• Para as regras de alerta e limites vinculados ao SLO, veja observability-and-instrumentation

Racionalizações Comuns

Racionalização	Realidade
"Funciona no staging, funcionará em produção"	Produção tem dados, padrões de tráfego e casos de borda diferentes. Monitore após a implantação.
"Não precisamos de feature flags para isso"	Todo recurso se beneficia de um interruptor de desligamento. Mesmo mudanças "simples" podem quebrar coisas.
"Monitoramento é sobrecarga"	Não ter monitoramento significa descobrir problemas através de reclamações de usuários em vez de painéis.
"Adicionaremos monitoramento depois"	Adicione antes do lançamento. Você não pode depurar o que não pode ver.
"Reverter é admitir falha"	Reverter é engenharia responsável. Enviar um recurso quebrado é a falha.
"A taxa de erro parece boa, vamos continuar enviando"	Verifique a taxa de consumo, não apenas a taxa de erro atual. Consumir orçamento mais rápido que a linha de base é um sinal de pausa mesmo quando os limites individuais estão verdes.

Bandeiras Vermelhas

• Implantar sem um plano de rollback
• Nenhum monitoramento ou relatório de erro em produção
• Lançamentos big-bang (tudo de uma vez, sem staging)
• Feature flags sem expiração ou proprietário
• Ninguém monitorando a implantação na primeira hora
• Configuração do ambiente de produção feita de memória, não por código
• "É sexta-feira à tarde, vamos enviar"
• Orçamento de erros esgotado, mas trabalho de recurso continua inalterado

Verificação

Antes de implantar:

• Lista de verificação pré-lançamento concluída (todas as seções verdes)
• Feature flag configurada (se aplicável)
• Plano de rollback documentado
• Painéis de monitoramento configurados
• Equipe notificada sobre a implantação

Após implantar:

• Health check retorna 200
• Taxa de erro está normal
• Latência está normal
• Fluxo crítico do usuário funciona
• Logs estão fluindo
• Rollback testado ou verificado como pronto

Para cada serviço enviado:

• Política de orçamento de erros em vigor: saber qual ação tomar quando o orçamento cair abaixo de 20% e quando estiver esgotado