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.
//
Busque em todas as páginas da documentação
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.
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:
### 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:
## Ação pós-mortem → catálogo
Ação G2 "verificação CI assíncrona" fecha → adicionar LL-004 se não presente| 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 |
O proprietário do pós-mortem propõe; o curador da plataforma aprova o formato.
Cresce organicamente; a lista Top 10 permanece estável; o catálogo completo pode chegar a 50+.
Sim - ADRs referenciam o ID da LL quando a decisão é acionada por um padrão de incidente.
Adicionar mecanismos de proteção contra desvio de avaliação e injeção de prompt à medida que a seção de ML cresce.
Apenas interno; resumos executivos separados.
Checkbox no ticket de onboarding vinculando ao documento Top 10.
Incrementar a nota de ocorrência; fortalecer a prioridade do mecanismo de proteção.
O template de scaffold impõe a prevenção por padrão para novos serviços.
grep IDs de LL no repositório; registro JSON opcional para portal.
Cada documento de referência/antes-depois contribui com 2-3 lições na publicação.
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+.
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026