Documentar para operar, runbook, ADR e implementación de referencia

En tres semanas, el equipo de proyecto le pasa el agente de soporte a operaciones. Lo que hay escrito son las notas de las reuniones y el historial del chat del equipo. Nadie de operaciones sabe qué hacer si las respuestas empiezan a salir mal un sábado, ni por qué se eligió ese modelo, ni qué se rompe si se cambia el prompt.

Lo que necesita quien opera

Un traspaso (handoff) sirve si el equipo que recibe puede operar el sistema y cambiarlo con seguridad. Para eso hay dos documentos que valen más que cualquier otro:

El runbook (runbook), para operar:

Sección	Qué contiene
Fallas conocidas	qué puede salir mal y cómo se ve (respuestas cortadas, recuperación vacía, límites de tasa)
Detección	qué alertas y tableros existen y qué significa cada umbral
Vuelta atrás (rollback)	cómo volver a la versión anterior del prompt, del modelo o del índice
Escalamiento	a quién llamar, en qué orden, con qué datos

Los registros de decisión de arquitectura (architecture decision records (ADR)), para cambiar: uno por decisión importante, con el contexto, la decisión, las alternativas descartadas y los supuestos. Los supuestos son la parte más útil: “elegimos este modelo porque el 80% de las consultas son simples” le dice al próximo equipo cuándo reabrir la decisión.

Junto a eso van los prompts versionados y la suite de evaluación: sin ellos, cualquier cambio es a ciegas.

Se escribe durante el proyecto

Un ADR escrito tres meses después reconstruye la decisión de memoria y pierde justamente las alternativas y los supuestos. Un runbook escrito la última semana no incluye las fallas que aparecieron en el piloto. Lo que funciona:

• el ADR se escribe cuando se toma la decisión, en pocas líneas;
• el runbook crece con cada incidente del piloto y se prueba antes del traspaso, con alguien de operaciones siguiendo los pasos;
• el traspaso tiene un período en que los dos equipos operan juntos.

Guiar a muchos equipos

Otro caso: una plataforma compartida de Claude que adoptan diez equipos de producto. Algunos lanzan sin evaluar, otros loguean datos de cuentas. El equipo de plataforma tiene tres personas. Una página de wiki más larga no cambia nada, y revisar cada implementación no escala.

Lo que escala es una implementación de referencia (reference implementation): un servicio de ejemplo y plantillas con los controles obligatorios ya incorporados (evaluación antes de lanzar, logs sin datos personales, vuelta atrás, límites de costo), versionadas y con un dueño. Cada equipo parte de ahí, y un checklist corto da la evidencia que pide el área de riesgos. Lo correcto se vuelve el camino más fácil.

Las trampas típicas

• Exportar el historial del chat y las minutas “para que busquen ahí”.
• Priorizar una presentación para ejecutivos sobre el runbook.
• Entregar la lista de todas las variantes de prompt probadas, sin sus resultados.
• Dejar toda la documentación para la última semana.
• Pedir a cada líder que confirme que leyó la wiki, o dejar que cada equipo elija sus prácticas.

En el examen

Si el escenario es un traspaso con poca documentación y hay que priorizar, buscá el runbook (fallas, alertas, vuelta atrás, escalamiento) y los ADR con el porqué y los supuestos, junto con prompts y evaluaciones versionados. Si son muchos equipos implementando de forma desigual, buscá la implementación de referencia con plantillas y controles obligatorios, versionada y con dueño.