Catálogo de Lecciones Aprendidas
Un catálogo de errores recurrentes en producción con Python extraído de estudios de caso y temas de incidentes, con patrones de prevención para que los equipos dejen de pagar intereses sobre la deuda técnica.
//
Busca en todas las páginas de la documentación
Un catálogo de errores recurrentes en producción con Python extraído de estudios de caso y temas de incidentes, con patrones de prevención para que los equipos dejen de pagar intereses sobre la deuda técnica.
Tarjeta de referencia rápida - lista para copiar y pegar.
## Plantilla de lección
**ID:** LL-014
**Patrón:** Llamadas síncronas a ORM en ruta asíncrona
**Impacto:** Interrupción p95, CPU baja
**Prevención:** Verificación CI de AST + asyncio.to_thread para CPU
**Ver:** Migración de Asíncrono a Síncrono Antes/DespuésCuándo usar esto:
### Web y API
| ID | Lección | Prevención |
| LL-001 | Argumentos por defecto mutables en ruta crítica | Lint de pytest; lista de verificación de revisión de código |
| LL-002 | Falta de filtro tenant_id en la consulta | el repositorio requiere contexto de tenant |
| LL-003 | Webhook sin idempotencia | Tabla de Idempotency-Key |
| LL-004 | sleep síncrono en middleware asíncrono | scripts/check_async_blocking.py |
### Datos y Migraciones
| LL-010 | Migración de índice sin CONCURRENTLY | Linter de migración + puerta de recuento de filas |
| LL-011 | Staging con 1% de recuento de filas oculta bloqueos | script de siembra de tablas grandes |
| LL-012 | ETL de adición no idempotente | MERGE sobre clave natural |
### ML y Procesos por Lotes
| LL-020 | Desviación entre entrenamiento y servicio | paquete de características compartido |
| LL-021 | Sin puerta de evaluación en la promoción | AUC mínimo en el trabajo CI de entrenamiento |
| LL-022 | Credenciales de notebook en git | secretos solo a través del orquestador |
### Operaciones y Entrega
| LL-030 | API revertida, workers no pausados | deploy-order.md obligatorio |
| LL-031 | Etiqueta :latest en producción | etiquetas SHA inmutables |
| LL-032 | Alerta sobre recuento de logs ERROR | Alertas de quema de SLO |"""lessons_registry.py - índice opcional legible 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",
},
}Lo que esto demuestra:
## Acción post-mortem → catálogo
Acción G2 "verificación CI asíncrona" se cierra → añadir LL-004 si no está presente| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| Solo Wiki | Inicio rápido | Desviación del repositorio |
| Solo base de datos de incidentes | Búsqueda rica | Sin narrativa de incorporación |
| Reglas de lint sin catálogo | Equipo pequeño | Necesita contexto humano del porqué |
| Blog externo sin culpa | Marketing | Detalle operativo interno |
El propietario del post-mortem propone; el curador de plataforma aprueba el formato.
Crecer orgánicamente; la lista de las 10 principales se mantiene estable; el catálogo completo puede llegar a 50+.
Sí - ADR hace referencia al ID de LL cuando la decisión es desencadenada por un patrón de incidente.
Añadir medidas de seguridad para desviación de evaluación, inyección de prompts a medida que crece la sección de ML.
Solo interno; resúmenes ejecutivos por separado.
Casilla de verificación en el ticket de incorporación que enlaza al documento de las 10 principales.
Incrementar la nota de ocurrencia; fortalecer la prioridad de la medida de seguridad.
La plantilla de andamiaje impone la prevención por defecto para nuevos servicios.
grep IDs de LL en el repositorio; registro JSON opcional para el portal.
Cada documento de referencia/antes-después contribuye con 2-3 lecciones al publicarse.
Versiones de Stack: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 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+, y uv 0.6+.
Revisado por Chris St. John·Última actualización: 16 jul 2026