Catálogo de Lições Aprendidas
Um catálogo de frota de armadilhas recorrentes em Rust e correções comprovadas - panics em manipuladores, Mutex entre await, incompatibilidades de ABI FFI, má configuração de pool e descompasso de implantação. Novos contratados leem as dez principais; post-mortems adicionam entradas com links de guardrail.
Receita
Cartão de referência rápida - pronto para copiar e colar.
## Lição LL-0042: erro de digitação no pool sqlx no Helm
**Tags:** deploy, oom, latency
**Sintoma:** Aumento de p95, CPU baixa, timeouts de aquisição
**Causa raiz:** `DATABASE_MAX_CONNECTIONS=2` em valores de produção com erro de digitação
**Correção:** Validação de esquema Helm + alerta de pool_acquire
**Guardrail:** PR #8821, regra Grafana 445
**Refs:** PM-2026-07-09Quando usar isso:
- Lista de leitura da primeira semana de onboarding
- Revisão do checklist pré-lançamento
- Correspondência de padrões durante um incidente
- Guilda de confiabilidade trimestral
Exemplo de Trabalho
| ID | Padrão | Correção rápida |
|---|---|---|
| LL-0001 | unwrap em manipulador Axum | Mapear para AppError; clippy deny |
| LL-0002 | std::fs em rota async | spawn_blocking |
| LL-0003 | API revertida, workers não | Runbook de implantação acoplado |
| LL-0004 | Derivação de struct #[repr(C)] | Teste de layout + cbindgen |
| LL-0005 | format! por requisição em caminho crítico | Reutilização de buffer; Criterion guard |
| LL-0006 | GIT_SHA ausente em logs | Env na inicialização + campo de span |
| LL-0007 | Inchaço de tamanho WASM | wasm-opt CI gate |
| LL-0008 | Flag de recurso ativada por padrão | Política de desativar por padrão |
| LL-0009 | Descompasso cargo.lock API/worker | Liberação de único workspace |
| LL-0010 | Miri pulado em PR unsafe | Trabalho noturno de miri em crates FFI |
Análise Profunda
Mantendo o Catálogo
- Proprietário: guilda de confiabilidade ou equipe de plataforma.
- Fonte: post-mortems SEV2+, temas de suporte repetidos, game days.
- Revisar trimestralmente: mesclar duplicatas, arquivar problemas de classe corrigida.
Usando no Processo
- Modelo de PR: checkbox "Isso afeta a classe LL-0003?".
- Apêndice de revisão de design vincula lições relevantes.
- Painel de entrevista usa o catálogo para perguntas de cenário.
Tags para Pesquisa
panic, async, ffi, oom, deploy, sqlx, tokio, wasm, supply-chain
Armadilhas
- Catálogo apenas na wiki - Desvia do código. Correção:
docs/lessons-learned.mdno repositório principal ou índice gerado. - Entradas de Culpa - Correção: Foco em sistemas, sem nomes.
- Links de guardrail desatualizados - Correção: Verificação de CI de links na auditoria trimestral.
- 1000 entradas - Correção: Top 20 curados + arquivo pesquisável.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Histórico apenas de ADR | Equipe pequena | Necessita de pesquisa baseada em sintomas |
| Apenas tags de ferramenta de incidente | Forte processo de IM | Narrativa de onboarding fraca |
| Runbook por serviço | Isolamento de nível 1 | Padrões de frota se repetem |
FAQs
Quem pode adicionar entradas?
Qualquer engenheiro via PR; o mantenedor da guilda mescla.
Lições específicas do cliente?
Redigir nomes; manter o padrão técnico.
Link de alertas?
URLs de Runbook podem incluir âncora de ID da lição.
Versão por edição?
Marcar lições com edição/toolchain, se relevante.
Sobreposição com post-mortem?
Post-mortem é específico do incidente; lição é padrão generalizado.
Relacionados
- Transformando Incidentes em Guardrails - prevenção
- Modos Comuns de Falha de Produção - sintomas
- Post-Mortems Sem Culpa - material fonte
- Casos Antes/Depois - análises profundas
- Melhores Práticas de Governança - consistência da frota
Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4 e Polars 0.46+.