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.

Receta

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és

Cuándo usar esto:

• Incorporación de personal senior a la cultura de la flota
• Revisión trimestral de operaciones
• Consolidación de acciones post-mortem
• Entrada para la lista de verificación de revisión de arquitectura

Ejemplo de Trabajo

### 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:

• Lecciones agrupadas para escaneo durante la revisión de diseño
• Cada fila apunta a una prevención concreta
• IDs estables para referencia cruzada en post-mortem
• Registro opcional que enlaza documentos para bots de incorporación

Inmersión Profunda

Cómo Funciona

• Obtenido de incidentes - Los temas de los post-mortem se convierten en entradas de LL en dos semanas.
• Responsable - Plataforma rota el curador del catálogo trimestralmente.
• Incorporación - Los nuevos empleados reconocen las 10 principales en el primer mes.
• Revisión - Retirar lecciones cuando la medida de seguridad sea universal en la plantilla de andamiaje.
• Enlace cruzado - Estudios de caso y páginas de solución de problemas hacen referencia a los IDs de LL.

Las 10 Principales para Nuevos Empleados

1. LL-004 - bloqueo asíncrono
2. LL-010 - bloqueos de migración
3. LL-030 - orden worker/API
4. LL-003 - idempotencia de webhook
5. LL-020 - desviación de ML
6. LL-002 - fuga de tenant
7. LL-031 - etiquetas de imagen
8. LL-012 - idempotencia de ETL
9. LL-001 - valores por defecto mutables
10. LL-032 - higiene de alertas

Notas de Python

## Acción post-mortem → catálogo
Acción G2 "verificación CI asíncrona" se cierra → añadir LL-004 si no está presente

Trampas

• Catálogo demasiado largo - Nadie lee. Solución: Lista corta de las 10 principales + tabla completa enlazada.
• Lecciones sin medidas de seguridad - Solo filosofía. Solución: Cada entrada tiene una verificación aplicable o un manual de ejecución.
• Lecciones obsoletas - Consejos de la era de Python 2. Solución: Pase trimestral del curador vinculado a los estándares de Python 3.14.
• Redacción culpabilizadora - "El desarrollador olvidó". Solución: Lenguaje de patrones del sistema.
• Texto duplicado de post-mortem - Carga de mantenimiento. Solución: Referencia de ID en lugar de copiar y pegar.

Alternativas

Preguntas Frecuentes

Relacionado

• Convertir Incidentes en Medidas de Seguridad - cerrar el ciclo
• Antes/Después: Migración de Síncrono a Asíncrono - origen de LL-004
• Antes/Después: Monolito Django - lecciones de acoplamiento
• Modos Comunes de Fallo en Producción - detalle de patrones
• Mejores Prácticas de Gobernanza - estándares

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+.