Por qué documentar antes de codificar

El marco ADS lo publicó el equipo de respuesta a incidentes de Palantir con licencia MIT. Su idea es sencilla: antes de escribir la lógica de una alerta se rellena una ficha con nueve secciones, y solo cuando la ficha se sostiene se escribe la consulta. Aquí lo adaptamos al catálogo de Salinas del Norte, una empresa de sal marina con planta de bombeo y un equipo de detección de dos personas.

Escribir primero la ficha no es burocracia: es la forma más barata de descubrir los errores. Es mucho más fácil corregir una frase («esta alerta necesita un campo que la fuente no trae») que una regla ya desplegada, con alertas que el turno ya ha cerrado sin entenderlas.

SDN-101 vigila tareas programadas nuevas en los servidores. La escribió una persona que salió de la empresa el 14 de agosto y no dejó ficha ni casos de prueba. Abre regla_en_produccion para ver lo único que queda de ella y alertas_sdn101 para ver qué hizo el turno con sus diez alertas desde entonces.

La columna cierre distingue las alertas que el turno investigó de las que cerró sin investigar. Una alerta cerrada sin investigar no es un falso positivo demostrado: es una alerta que nadie supo atender.

Cada alerta tiene los minutos que el turno le dedicó. Las investigadas son las caras: nadie sabía qué buscar, se revisó el servidor entero o se escaló a otro equipo para averiguar si era normal. Y la única que acabó en incidente tardó más que ninguna, porque no había una guía que dijera por dónde empezar.

Suma los minutos de las diez alertas. Es el costo de atender la regla a ciegas durante un mes.

La ficha ADS tiene nueve secciones y cada una responde una pregunta que una persona que hereda la regla se haría tarde o temprano. Si no hay una sección que la responda, esa pregunta se contesta llamando al autor, que es justo lo que ya no se puede hacer.

Mira secciones_de_la_ficha. El turno, cuando una alerta salta un domingo, necesita saber qué hacer.

SDN-101 sigue en producción, sin dueño, y el equipo de detección tiene poco tiempo. Una persona propone reescribir la consulta desde cero para «dejarla limpia». Otra propone apagarla, porque nadie la entiende.

El caso de A-10 dice que la regla sí encontró algo que importaba. Apagarla sería perder la única señal de ese tipo; reescribirla sin saber qué buscaba es repetir el problema con otro autor.