Catálogo de Lições Aprendidas
Um catálogo de erros recorrentes em produção Python extraídos de estudos de caso e temas de incidentes - com padrões de prevenção para que as equipes parem de pagar os mesmos juros sobre débito técnico.
Receita
Cartão de referência rápida - pronto para copiar e colar.
## Modelo de Lição
**ID:** LL-014
**Padrão:** Rota assíncrona chama ORM síncrono
**Impacto:** Interrupção p95, CPU baixa
**Prevenção:** Verificação CI AST + asyncio.to_thread para CPU
**Ver:** Migração de Assíncrono para Síncrono: Antes/DepoisQuando usar isso:
- Onboarding de novos contratados seniores à cultura da frota
- Revisão trimestral de operações
- Consolidação de ações pós-mortem
- Entrada para checklist de revisão de arquitetura
Exemplo de Trabalho
### Web & API
| ID | Lição | Prevenção |
| LL-001 | Argumentos padrão mutáveis em caminho crítico | Linter pytest; checklist de revisão de código |
| LL-002 | Falta de filtro tenant_id na consulta | repositório requer contexto de tenant |
| LL-003 | Webhook sem idempotência | Tabela de Idempotência |
| LL-004 | sleep síncrono em middleware assíncrono | scripts/check_async_blocking.py |
### Dados & Migrações
| LL-010 | Migração de índice sem CONCURRENTLY | Linter de migração + portão de contagem de linhas |
| LL-011 | Staging 1% de contagem de linhas esconde locks | script de seed de tabela grande |
| LL-012 | ETL não idempotente de append | MERGE na chave natural |
### ML & Batch
| LL-020 | Desvio treino-serviço | pacote de features compartilhado |
| LL-021 | Sem portão de avaliação para promover | job CI de treino com AUC min |
| LL-022 | Credenciais de notebook no git | segredos apenas via orquestrador |
### Ops & Entrega
| LL-030 | API revertida, workers não pausados | deploy-order.md obrigatório |
| LL-031 | Tag :latest em produção | tags SHA imutáveis |
| LL-032 | Alerta na contagem de logs ERROR | alertas de queima de SLO |"""lessons_registry.py - índice opcional legível por máquina."""
LESSONS = {
"LL-004": {
"title": "Sync sleep in async middleware",
"guardrail": "scripts/check_async_blocking.py",
"doc": "./before-after-sync-to-async-migration/before-after-sync-to-async-migration.md",
},
}O que isso demonstra:
- Lições agrupadas para escaneamento durante a revisão de design
- Cada linha aponta para uma prevenção concreta
- IDs estáveis para referência cruzada em pós-mortem
- Registro opcional vincula documentos para bots de onboarding
Mergulho Profundo
Como Funciona
- Originado de incidentes - Temas de pós-mortem se tornam entradas de LL em até duas semanas.
- Responsável - A plataforma rotaciona o curador do catálogo trimestralmente.
- Onboarding - Novos contratados reconhecem as 10 principais no primeiro mês.
- Revisão - Aposentar lições quando o mecanismo de proteção for universal no template de scaffold.
- Link Cruzado - Estudos de caso e páginas de solução de problemas referenciam IDs de LL.
Top 10 para Novos Contratados
- LL-004 - bloqueio assíncrono
- LL-010 - locks de migração
- LL-030 - ordem worker/API
- LL-003 - idempotência de webhook
- LL-020 - desvio de ML
- LL-002 - vazamento de tenant
- LL-031 - tags de imagem
- LL-012 - idempotência de ETL
- LL-001 - padrões mutáveis
- LL-032 - higiene de alertas
Notas Python
## Ação pós-mortem → catálogo
Ação G2 "verificação CI assíncrona" fecha → adicionar LL-004 se não presenteArmadilhas
- Catálogo muito longo - Ninguém lê. Correção: Lista curta Top 10 + tabela completa vinculada.
- Lições sem mecanismos de proteção - Apenas filosofia. Correção: Cada entrada tem uma verificação aplicável ou runbook.
- Lições desatualizadas - Conselhos da era Python 2. Correção: Passagem trimestral do curador ligada aos padrões Python 3.14.
- Linguagem de culpa - "Dev esqueceu." Correção: Linguagem de padrão de sistema.
- Texto duplicado de pós-mortem - Carga de manutenção. Correção: Referência de ID em vez de copiar e colar.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Apenas Wiki | Início rápido | Desvio do repositório |
| Apenas banco de dados de incidentes | Pesquisa rica | Nenhuma narrativa de onboarding |
| Regras de linter sem catálogo | Equipe pequena | Necessidade de contexto humano do porquê |
| Blog externo sem culpa | Marketing | Detalhe operacional interno |
FAQs
Quem adiciona entradas?
O proprietário do pós-mortem propõe; o curador da plataforma aprova o formato.
Quantas lições?
Cresce organicamente; a lista Top 10 permanece estável; o catálogo completo pode chegar a 50+.
Link para ADRs?
Sim - ADRs referenciam o ID da LL quando a decisão é acionada por um padrão de incidente.
Lições específicas de LLM?
Adicionar mecanismos de proteção contra desvio de avaliação e injeção de prompt à medida que a seção de ML cresce.
Voltado para o cliente?
Apenas interno; resumos executivos separados.
Reconhecimento de onboarding automatizado?
Checkbox no ticket de onboarding vinculando ao documento Top 10.
Incidentes duplicados?
Incrementar a nota de ocorrência; fortalecer a prioridade do mecanismo de proteção.
Aposentar quando?
O template de scaffold impõe a prevenção por padrão para novos serviços.
Pesquisa?
grep IDs de LL no repositório; registro JSON opcional para portal.
Estudos de caso relacionados?
Cada documento de referência/antes-depois contribui com 2-3 lições na publicação.
Relacionados
- Transformando Incidentes em Mecanismos de Proteção - feche o ciclo
- Antes/Depois: Migração de Síncrono para Assíncrono - origem de LL-004
- Antes/Depois: Monolito Django - lições de acoplamento
- Modos Comuns de Falha em Produção - detalhe do padrão
- Melhores Práticas de Governança - padrões
Versões de Stack: Esta página foi escrita para Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.