Runbooks: cómo responder a incidencias sin depender de la memoria del equipo

Una incidencia rara vez llega en un momento cómodo. Puede aparecer durante un despliegue, cuando una persona clave no está disponible o con información incompleta: una alerta ambigua, una cola que crece, una integración externa que responde lentamente o una funcionalidad que ha dejado de completar su recorrido. En ese momento, el problema no es solo técnico. También es cognitivo: hay que interpretar señales, decidir qué acción es segura y coordinarse sin añadir más riesgo.

Un runbook sirve para recuperar capacidad de actuar. No es un documento que intenta explicar todo el sistema ni una lista de comandos para ejecutar sin pensar. Es una guía breve y contextual que ayuda al equipo a responder a una situación conocida: qué señal la confirma, qué impacto puede tener, qué comprobar primero, qué acciones son seguras y cuándo hay que parar o escalar.

La palabra importante es equipo. Los runbooks no deberían ser el territorio exclusivo de operaciones, backend o infraestructura. Una incidencia puede afectar a una interfaz, a una API, a datos, a una integración o a la experiencia de soporte. Cada especialidad aporta conocimiento, pero el objetivo compartido es restaurar el servicio y entender qué debe mejorar después.

Un runbook no es una guía de arquitectura

La arquitectura explica cómo está construido el sistema y por qué se tomaron determinadas decisiones. Un runbook parte de una pregunta más inmediata: «¿qué hacemos ahora?». Puede enlazar a diagramas, dashboards, contratos o ADRs, pero no debe obligar a leerlos todos para empezar.

Esta diferencia evita dos extremos. Un documento demasiado general no ayuda durante una incidencia porque obliga a reconstruir el contexto. Uno demasiado detallado puede convertirse en una receta larga que nadie consulta, o peor, en una secuencia que alguien ejecuta sin evaluar si sigue siendo apropiada.

Un buen runbook reduce la incertidumbre inicial. Por ejemplo, ante informes atascados no necesita explicar toda la arquitectura de generación de documentos. Debe permitir confirmar si realmente hay trabajos bloqueados, identificar el alcance, revisar las últimas ejecuciones y decidir si es seguro reintentar, esperar o escalar el problema.

Cuándo merece la pena crear uno

No todo error necesita un runbook. Una excepción aislada, bien entendida y sin acción manual probablemente se resuelva con una alerta o una corrección de producto. Merece la pena documentar un procedimiento cuando se cumple al menos una de estas condiciones:

• La situación puede repetirse.
• El diagnóstico exige conocer más de una herramienta o capa del producto.
• Una acción incorrecta puede agravar el impacto.
• La respuesta depende hoy de que alguien recuerde pasos no evidentes.
• El equipo necesita coordinarse con soporte, producto o una dependencia externa.

La repetición no tiene que ser frecuente. Un incidente poco habitual pero con impacto alto —por ejemplo, una reversión de datos o una integración crítica degradada— puede justificar un runbook aunque se use pocas veces. La señal más clara es escuchar frases como «esto lo sabe hacer solo una persona» o «la última vez tardamos en recordar dónde mirar».

La estructura mínima que ayuda a decidir

Un runbook funciona mejor si su orden sigue el razonamiento de quien lo consulta bajo presión. Esta plantilla es suficiente para muchas situaciones:

# [Síntoma o situación reconocible]

## Objetivo

Qué servicio se intenta recuperar y qué significa una recuperación correcta.

## Señales para confirmar el problema

- Alertas, métricas o comportamiento observable.
- Cómo distinguirlo de síntomas parecidos.

## Impacto y alcance

- Personas, flujos o datos afectados.
- Qué información recoger antes de intervenir.

## Comprobaciones iniciales

1. Acción de solo lectura y resultado esperado.
2. Acción de solo lectura y cómo interpretarla.

## Acciones seguras

1. Acción reversible, con precondiciones y resultado esperado.
2. Cómo verificar que ha funcionado.

## No hacer sin escalado

- Acciones destructivas, irreversibles o que exigen aprobación.

## Escalado y comunicación

Cuándo pedir ayuda, a quién y qué contexto aportar.

## Cierre y seguimiento

Cómo confirmar la recuperación y qué registrar después.

No hay que rellenar secciones por obligación. Si el diagnóstico solo tiene una comprobación relevante, es preferible decirlo con claridad. La estructura aporta valor cuando evita que falte una pregunta crítica, no cuando convierte una operación sencilla en burocracia.

Empieza por señales observables

Los títulos vagos producen runbooks vagos. «Problemas con la API» obliga a interpretar demasiado. «Aumentan los errores 5xx en la creación de solicitudes» o «hay trabajos en processing más allá del umbral esperado» da un punto de partida comprobable.

Las señales deben ser observables por alguien con los permisos correctos. Pueden ser una alerta, una consulta en un panel, una métrica, un log correlacionado o un comportamiento visible. También conviene indicar qué no confirma el problema: una alerta de latencia no implica por sí sola que haya pérdida de datos; una cola con pendientes puede ser normal dentro de un periodo determinado.

Este matiz reduce respuestas precipitadas. La primera fase de un runbook no busca arreglar el sistema, busca saber qué está ocurriendo y con qué alcance.

Separa observar, intervenir y verificar

Me resulta útil ordenar los pasos en tres grupos. Primero, observación: consultas de solo lectura, métricas, trazas y comprobaciones que no cambian nada. Después, intervención: acciones deliberadas y, siempre que sea posible, reversibles. Por último, verificación: señales que demuestran que el sistema se ha recuperado y que la acción no ha ocultado el problema.

Esta separación hace visibles los riesgos. Si una “comprobación” modifica datos, reintenta cientos de trabajos o elimina una cola, no debería esconderse entre los pasos iniciales. Debe aparecer como una intervención con sus precondiciones, permisos y consecuencias.

También evita dar por resuelta una incidencia demasiado pronto. Que una alerta deje de dispararse puede significar que el servicio está sano, pero también que se ha silenciado la señal. La verificación debe conectarse con el objetivo real: solicitudes que vuelven a completarse, personas usuarias que recuperan una funcionalidad o una tasa de error que retorna a un nivel esperado.

Las acciones peligrosas deben ser explícitamente incómodas

Hay operaciones que requieren una barrera adicional: borrar datos, cambiar configuración de producción, ejecutar migraciones manuales, reintentar efectos no idempotentes o revertir un despliegue. Un runbook responsable no las presenta como un siguiente paso inocente.

Para estas acciones conviene indicar qué condiciones deben cumplirse, quién puede aprobarlas, cuál es el impacto esperado y cómo se recupera la situación si algo sale mal. En algunos casos, la instrucción correcta es sencillamente «no ejecutar esta acción sin escalar». Es mucho más útil que dejar una orden peligrosa escondida en un historial de chat o confiar en que quien esté de guardia recuerde una excepción.

La claridad no reduce la autonomía. Da al equipo un marco para decidir cuándo puede actuar con seguridad y cuándo necesita sumar más contexto.

Un runbook también es una herramienta de comunicación

Durante una incidencia suelen participar personas con necesidades distintas. Quien investiga necesita señales técnicas; soporte necesita saber qué explicar; producto necesita comprender el impacto; quien coordina necesita un estado claro. No hace falta duplicar el runbook para cada audiencia, pero sí recoger un mínimo de información que permita comunicar sin especular.

Por ejemplo: hora de detección, alcance conocido, comportamiento afectado, acción en curso, siguiente actualización y persona que coordina. Registrar estos datos reduce mensajes contradictorios y evita que el trabajo se convierta en una conversación paralela difícil de reconstruir.

El runbook tampoco debe prometer certezas que no existen. «Investigando una degradación en la creación de solicitudes; el impacto todavía se está acotando» es mejor que declarar una causa antes de haberla confirmado.

Se escribe a partir de problemas reales y se prueba antes de necesitarlo

Los mejores runbooks suelen nacer después de una incidencia, cuando todavía están presentes las preguntas, las dudas y los pasos que costó encontrar. La revisión posterior debería identificar no solo la causa técnica, sino las fricciones de respuesta: qué señal faltaba, qué decisión dependía de memoria, qué acceso fue difícil de conseguir o qué verificación no era evidente.

Después hay que probar el documento. No siempre hará falta simular una caída completa. Puede revisarse en pareja, recorrer las consultas en un entorno seguro o usar un ejercicio corto para comprobar que una persona que no vivió el incidente entiende los pasos. Si el procedimiento no se puede probar porque requiere permisos, herramientas o datos inaccesibles, eso también es una señal operativa que merece resolverse.

Actualizar el runbook tras usarlo es esencial. Un enlace roto, una métrica que ha cambiado de nombre o una acción que ya no es segura convierten un documento útil en una fuente de riesgo. La documentación viva de un equipo incluye estas correcciones pequeñas y continuas, como explico en el artículo sobre documentación viva con Astro y Starlight.

No sustituye el diseño para fallar bien

Un runbook reduce el coste de responder a un problema; no debería convertirse en la compensación permanente de un sistema frágil. Si el mismo procedimiento se usa cada semana, quizá haya que automatizar una recuperación, mejorar una alerta, rediseñar una transición de estados o resolver una causa de fondo.

Tampoco sustituye pruebas, observabilidad o buenas decisiones de producto. Su papel es conectar esas piezas en una situación concreta. Un sistema preparado para fallar bien puede tener reintentos seguros, estados recuperables y métricas claras; el runbook ayuda a interpretar esas capacidades y usarlas de forma responsable cuando las cosas no siguen el camino esperado.

Conclusión

Un runbook no es una colección de comandos ni un documento reservado para situaciones dramáticas. Es una forma de distribuir conocimiento operativo y de convertir la experiencia de una incidencia en una respuesta más segura la próxima vez.

El objetivo no es que nadie piense durante un incidente. Es que el equipo no tenga que empezar de cero, dependa de la memoria de una sola persona o tome decisiones de alto riesgo sin una guía clara. Cuando un runbook combina señales observables, acciones seguras, límites explícitos y verificación, pasa a ser una pieza práctica de la fiabilidad del producto.