Decisiones con fecha: por qué escribo ADRs aunque seamos dos

Hay una pregunta que aparece en todos los equipos, más o menos al segundo año: “¿por qué esto está hecho así?”. A veces la respuesta es buena y a veces es mala, pero casi siempre es la misma: nadie se acuerda. La persona que decidió se fue, o está, pero decidió bajo restricciones que ya no existen y que tampoco recuerda. El sistema queda, la razón no.

Un Architecture Decision Record es la herramienta más barata que conozco contra ese problema. Es un documento corto, con fecha, que responde tres cosas: qué decidimos, qué alternativas consideramos y por qué las descartamos. Nada más. Lo escribo en el trabajo, donde ya vamos por el ADR 012, y lo escribo en Loxben, donde el equipo técnico somos dos personas y podría, en teoría, decidirlo todo en un mensaje de Slack.

La plantilla que uso

No vale la pena inventar. La estructura es la de Nygard con un par de agregados que me sirvieron:

• Estado y fecha. Propuesto, aceptado, reemplazado por otro. La fecha es lo importante: un ADR es una decisión con fecha, y la fecha es lo que le da contexto.
• Contexto. Qué problema hay, qué restricciones existen. Sin esto la decisión parece arbitraria un año después.
• Decisión. Una o dos frases. Si necesita más, probablemente son dos decisiones.
• Razonamiento y alternativas. Aquí está el valor real. Qué más miramos y por qué perdió.
• Consecuencias. Las positivas y las negativas. Si no hay negativas, no pensamos lo suficiente.
• Estrategia de implementación y métricas de éxito. Cómo sabremos que funcionó.

Lo que dejo fuera: código. Un ADR explica el porqué; la guía de implementación explica el cómo, y son documentos distintos con lectores distintos. Cuando mezclé los dos, el ADR envejeció con el primer refactor y dejó de ser confiable.

Ejemplos de decisiones que valió la pena escribir

Elegir un proveedor de autenticación. Escribimos por qué Auth0 sobre Cognito y Firebase, y también escribimos que los roles viven en nuestra base de datos y no en los metadatos del proveedor. Un año y medio después, cuando el costo se volvió un problema y evaluamos alternativas, esa segunda decisión fue la que hizo que la migración fuera viable. Nadie la recordaba; estaba en el documento.

Migrar de un CRM a otro. La decisión fue un facade que escribe en los dos sistemas durante la transición, con los dos identificadores guardados en nuestra tabla. La alternativa descartada era el corte directo. Cuando alguien preguntó meses después por qué había dos columnas de ID, la respuesta estaba a un enlace de distancia.

Una máquina de estados propia en lugar de XState. Perdió la biblioteca, no porque fuera mala, sino porque la integración con nuestros modelos de Prisma costaba más que escribir la validación de transiciones a mano con hooks. Esa es exactamente la clase de decisión que después parece pereza si no se explica.

Multi-Zone de Next.js en vez de Module Federation. Perdió Module Federation por costo de licencia y porque su soporte para App Router estaba en camino a ser deprecado. Ese dato caduca; la fecha del ADR le dice al lector cuándo era cierto.

Por qué también con dos personas

La objeción razonable es que un ADR sirve para equipos grandes. Mi experiencia es la contraria: un equipo de dos es el que más lo necesita, porque no tiene redundancia. Si yo me enfermo dos semanas, mi socio tiene que poder seguir. Si en tres años alguien quiere comprar uno de los productos, va a preguntar por qué la infraestructura está separada por unidad organizativa en AWS, y la respuesta —para poder vender cada producto sin desarmar el resto— está escrita desde el día en que lo decidimos.

Y está el lector más importante: yo mismo, dentro de un año, con menos contexto del que creo tener.

Cómo encaja con el resto

En el trabajo, una funcionalidad grande sigue este camino: RFC, investigación, ADR, plan de implementación por fases con puntos de aprobación entre fase y fase, y tareas en Linear con criterios de aceptación. El ADR es el eslabón que conecta la investigación con el plan. Sin él, el plan es una lista de pasos sin justificación; con él, cualquiera puede cuestionar el plan en el lugar correcto, que es la decisión y no la tarea.

Lo que no funciona

Un ADR escrito después, para justificar lo que ya se hizo. Se nota y no sirve. Un ADR que nunca se marca como reemplazado, así que dos documentos contradictorios conviven en el repositorio. Y un ADR de veinte páginas: si necesita veinte páginas, es un documento de diseño, y está bien que exista, pero no es esto.

Una decisión con fecha. Eso es todo. La fecha es el punto.