El procedimiento para llevar a un agente desde el error registrado hasta la causa raíz y el arreglo con test de regresión, sin que se lance a cambiar código antes de entender qué pasa.
Cuándo usarlo: Investigar un fallo de producción con un agente siguiendo reproducir, entender, arreglar y verificar, con test de regresión y prevención
Herramienta recomendada: Claude Code
Actúa como ingeniero de guardia con experiencia en incidencias de producción. Tengo un fallo en producción y quiero un procedimiento disciplinado, no parches a ciegas. ## Lo que te voy a dar 1. Mensaje de error y traza completa. 2. Contexto: cuándo empezó, con qué frecuencia ocurre, a cuántos usuarios afecta, qué se desplegó cerca de esa fecha. 3. Acceso a los ficheros implicados. 4. Registros relevantes, si los tengo. ## Regla número uno **No propongas ningún cambio de código hasta poder explicar el fallo.** La secuencia es: reproducir, entender, arreglar, verificar. Si te falta información para reproducir, pídela; no rellenes el hueco con una hipótesis cómoda. ## Paso 1 — Delimitar Responde con lo que se sabe y lo que no: - Qué operación exacta falla y cuál es el camino desde la entrada del usuario hasta la línea de la traza. - ¿Falla siempre o de forma intermitente? La intermitencia apunta a estado compartido, concurrencia, caché, orden de datos o dependencia externa. - ¿Qué cambió? Despliegue, migración de datos, configuración, versión de dependencia, volumen de tráfico. - ¿Afecta a todos los usuarios o a un subconjunto? El subconjunto suele describir el dato que rompe. ## Paso 2 — Reproducir Escribe la reproducción mínima: un test que falla, un comando o una petición concreta. Si no se puede reproducir aún, propón la instrumentación exacta que hace falta (qué registrar, dónde y durante cuánto) en lugar de adivinar. ## Paso 3 — Causa raíz Formula la causa raíz en una frase que empiece por «el fallo ocurre porque…» y que se pueda comprobar leyendo el código. Distingue entre: - **Causa inmediata**: la línea que revienta. - **Causa raíz**: la decisión o el hueco que permitió llegar a ese estado. - **Por qué no se detectó antes**: el test que falta, la validación ausente, la alerta que no existe. ## Paso 4 — Arreglo Propón dos opciones cuando existan: | Opción | Qué hace | Riesgo | Cuándo elegirla | |---|---|---|---| | Mitigación | Detiene el daño ya (revertir, desactivar, límite) | Bajo | Incidencia activa con impacto | | Corrección | Elimina la causa raíz | Mayor | Cuando el fuego está apagado | Para la corrección: diff mínimo, sin refactorizar de paso, y el test de regresión que falla antes del arreglo y pasa después. ## Paso 5 — Cierre - Confirmación de que el test de regresión captura exactamente este fallo. - Qué otros puntos del código tienen el mismo patrón y podrían fallar igual. - Alerta o validación que habría avisado antes, con la configuración concreta. - Dos líneas para el archivo de instrucciones del proyecto, si esto es una trampa que se puede repetir. ## Entregables 1. Cronología y delimitación del fallo. 2. Reproducción mínima. 3. Causa raíz, causa inmediata y por qué no se detectó. 4. Mitigación y corrección, con el diff y el test de regresión. 5. Prevención: mismos patrones en el código, alerta propuesta y nota para la documentación.