Depuración
El error costoso es corregir la primera causa plausible. Dedica los primeros minutos a acotar, no a parchar.
Método
- Captura el fallo exacto. Texto completo del error, traza de pila, código de salida, marcas de tiempo, IDs de solicitud, el comando que se ejecutó. Ponlo en un bloque de código. Los errores parafraseados pierden el token que importa.
- Reprodúcelo. Encuentra la forma más pequeña y rápida de provocarlo a demanda. Si no puedes reproducirlo, dilo y trabaja a partir de los registros; no adivines en silencio.
- Establece qué cambió.
git log --since, despliegues recientes, cambios de dependencias, cambios de configuración o IAM, actualizaciones de proveedores, un certificado que expira. La mayoría de los incidentes son un cambio. - Formula dos o tres hipótesis y ordénalas por probabilidad y por lo barato que sea verificarlas. Escríbelas antes de probar.
- Prueba una hipótesis a la vez con un cambio que solo importaría si esa hipótesis es cierta. Revierte lo que no ayudó; no acumules ediciones especulativas.
- Corrige la causa. Luego escribe una prueba de regresión que falle sin la corrección (consulta la skill
tdd). - Verifica de la misma manera que lo reprodujiste y ejecuta el conjunto de pruebas más amplio.
Dónde buscar, según el síntoma
| Síntoma | Primeras comprobaciones |
|---|---|
| Funciona local, falla en CI | Variables de entorno, secretos, SO/arquitectura, versión de node/python, dependencias cacheadas, zona horaria, directorio de trabajo |
| Intermitente / inestable | Estado compartido entre pruebas, tiempo, orden, red, reintentos que ocultan fallos reales |
| AWS AccessDenied | Qué principal (aws sts get-caller-identity), política de recurso vs política de identidad, SCPs, límite de permisos, política clave KMS, región |
| Lambda timeout / arranque en frío | Conexión VPC, DNS, inicialización fuera del handler, tamaño de memoria, latencia downstream en X-Ray |
| Error de Terraform | Versión del proveedor, desviación del estado (terraform plan -refresh-only), restos de -target, archivo de bloqueo |
| Pod de Kubernetes no listo | kubectl describe pod, eventos, sondas, límites de recursos, extracción de imagen, montajes de secretos/configmaps |
| 5xx después del despliegue | Comparar imagen/commit anterior, ruta del health check, diferencias de entorno/config, orden de migraciones de BD |
Reglas
- Lee los registros antes de leer el código. Los registros te dicen dónde; el código te dice por qué.
- Añade registro temporal si es necesario, y elimínalo antes de hacer commit.
- Nunca 'corrijas' ampliando permisos, desactivando la verificación TLS, capturando y tragando excepciones, o añadiendo reintentos sin entender qué se está reintentando.
- Cuando lo corrijas, escribe un párrafo con: causa, por qué no se detectó, qué lo evita la próxima vez. Ese párrafo va en el PR o en el cuerpo del commit.