sop-writing

O que sop-writing faz?

Filosofia Central

Um Procedimento Operacional Padrão (SOP) não é um ensaio teórico ou um documento de política aspiracional. Um SOP é um runbook algorítmico executável para operadores humanos ou agentes. Um bom SOP é projetado para que um operador qualificado, sob estresse extremo às 3:00 da manhã, possa executar o processo com zero ambiguidade, zero suposições e zero erros catastróficos. Cada etapa deve ter entradas determinísticas, ações físicas numeradas, critérios de aceitação observáveis e caminhos de escalonamento explícitos.

---

Arquitetura de Procedimento Operacional Padrão (SOP) em 4 Etapas

Etapa 1: Escopo, Governança e Pré-requisitos de Pré-voo

1. Cabeçalho de Metadados e Propriedade:
   • ID do SOP, Versão (SemVer), Data de Vigência, Cadência de Revisão (Anual/Semestral), Proprietário do Processo Responsável.
2. Limites Estritos de Propósito e Escopo:
   • Exatamente o que este procedimento cobre e o que não cobre.
3. Pré-requisitos e Permissões de Acesso:
   • Liste as credenciais necessárias, acesso VPN, pacotes de software e variáveis de ambiente antes da primeira etapa de execução.

Etapa 2: A Sequência de Etapas Numeradas Determinísticas

1. Verbos de Ação Imperativos e Inequívocos:
   • Comece cada etapa com um verbo ativo: Clique, Execute, Verifique, Copie, Exporte, Confira.
   • Nunca escreva diretrizes passivas: "Garanta que os logs sejam verificados."
   • Escreva: "1. Abra o dashboard do Datadog Prod-Ingestion. 2. Inspecione o gráfico p99 Latency. 3. Verifique se o valor está abaixo de 200ms."
2. Higiene de Comandos Copiáveis:
   • Forneça comandos CLI exatos ou trechos de código em blocos de código. Nunca faça operadores adivinharem nomes de flags ou parâmetros.

Etapa 3: Verificação Observável e Portões de Aceitação

1. A Verificação "Como Sei Que Funcionou?":
   • Cada etapa importante deve especificar sua saída esperada:
     • "Saída Esperada: O terminal exibe Deploy Completo: 12/12 pods saudáveis."
2. Árvores de Decisão e Lógica de Ramificação:
   • Formate a lógica condicional claramente:
     • Se status == 200: Prossiga para a Etapa 4.
     • Se status == 500: Vá para a Seção de Solução de Problemas 5.1.

Etapa 4: Tratamento de Falhas, Reversão e Caminhos de Escalonamento

1. O Runbook de Reversão:
   • Se o procedimento falhar no meio do caminho, forneça comandos de reversão exatos para restaurar o sistema a um estado de base seguro.
2. SLA de Escalonamento e Matriz de Contato:
   • Quem acionar, em qual canal, com qual gravidade, se o procedimento não puder ser concluído em 15 minutos.

---

Formato de Entrega: Procedimento Operacional Padrão de Produção (SOP-TEMPLATE.md)

# Procedimento Operacional Padrão: Implantação de Hotfix em Produção
*ID do SOP: SOP-ENG-042 | Versão: v2.1.0 | Proprietário: Líder de Engenharia de Plataforma*
*Data de Vigência: [AAAA-MM-DD] | Cadência de Revisão: Trimestral*

## 1. Propósito e Escopo
Este procedimento rege a implantação de hotfixes de emergência em clusters de produção fora do ciclo de lançamento CI/CD semanal padrão.

## 2. Pré-requisitos e Requisitos de Acesso
- Função IAM de Produção AWS `arn:aws:iam::123456789012:role/implantadorDeEmergencia`
- CLI do GitHub (`gh`) autenticada com acesso de gravação ao repositório
- AWS CLI v2 e `kubectl` configurados localmente

## 3. Sequência de Execução Passo a Passo

### Passo 1: Isolamento e Verificação de Branch
1. Faça checkout do branch de hotfix a partir de `main`:
   ```bash
   git checkout main && git pull origin main
   git checkout -b hotfix/SEC-[NumeroDoProblema]

2. Execute o conjunto de testes completo localmente:

   npm run test:ci
   

   • Verificação de Aceitação: Código de saída 0; todos os conjuntos de teste passam.

Passo 2: Construir e Marcar Imagem de Contêiner

1. Acione o pipeline de construção de hotfix automatizado:

   gh workflow run hotfix-build.yml -f branch=hotfix/SEC-[NumeroDoProblema]
   

   • Saída Esperada: GitHub Actions emite digest da imagem sha256:....

Passo 3: Implantação em Produção e Verificação Canário

1. Aplique a implantação no pool de pods canário (10% do tráfego):

   kubectl set image deployment/api-gateway api=ecr.internal/api:[Digest] -n production
   

2. Monitore as taxas de erro por 5 minutos:
   • Verifique o dashboard do Grafana https://grafana.internal/d/canary-health.
   • Portão de Aceitação: A taxa de erros 5xx deve permanecer < 0,01%.

4. Plano de Reversão e Contingência

Se a taxa de erro do Canário exceder 0,05%:

1. Reverta a implantação imediatamente:

   kubectl rollout undo deployment/api-gateway -n production
   

2. Notifique o Comandante de Incidente no Slack #incident-war-room.

5. Contatos de Escalonamento

• Plantão SRE Primário: Escala do PagerDuty sre-nivel-1
• VP de Engenharia: Telefone: [Número] (Acionar se a interrupção exceder 15 minutos)

---

## Exemplo Prático: SOP de Restauração de Banco de Dados

- **Contexto**: Runbook de recuperação para restauração de snapshot de banco de dados PostgreSQL criptografado.
- **Impacto**: O SOP passo a passo permitiu que um engenheiro júnior no plantão noturno restaurasse uma tabela de cliente acidentalmente excluída em 11 minutos com zero corrupção de dados.

---

## Lista de Verificação

- [ ] Cada etapa do procedimento começa com um verbo imperativo ativo.
- [ ] Comandos e trechos de código são 100% copiáveis com sintaxe exata.
- [ ] A saída observável esperada é especificada para cada etapa crítica.
- [ ] Procedimentos de reversão explícitos estão documentados para execuções com falha.
- [ ] A matriz de contato de escalonamento inclui funções nomeadas e canais de paginação.

---

## Anti-padrões

- **Instruções Ambíguas**: Escrever "Configure a rede corretamente" em vez de fornecer as tabelas IP ou configuração YAML exatas.
- **Runbook de Reversão Ausente**: Explicar como aplicar uma alteração sem explicar como revertê-la se quebrar.
- **Runbooks Não Testados**: Escrever um SOP de recuperação de desastre de emergência que nunca foi executado em um ambiente de staging.