ADRs (Architecture Decision Records)

Nivel intermedio — documentar decisiones arquitectónicas con su contexto, alternativas y consecuencias, no solo el resultado.

Idea central Un ADR captura no solo QUÉ se decidió, sino POR QUÉ. Sin ese "por qué" documentado, cada decisión pasada se convierte en arqueología — o peor, en un error que alguien "corrige" sin saber que ya tenía una razón.

01 —

El problema

Las decisiones arquitectónicas se toman en reuniones, Slack o llamadas. Meses después, nadie recuerda por qué se eligió PostgreSQL sobre MongoDB, o por qué hay código duplicado "intencional" entre dos servicios.

Situación típica: un nuevo desarrollador pregunta "¿por qué usamos Redis para sesiones en lugar de JWT?". Nadie recuerda. El arquitecto original ya no está. Alguien asume que fue una mala decisión y propone migrar a JWT. Tres meses después descubren que había una razón de seguridad específica (revocación instantánea de sesiones) — y el cambio creó una vulnerabilidad. // "corregir" una decisión sin conocer su porqué puede reintroducir el problema que resolvía

02 —

Estructura de un ADR (formato Michael Nygard)

# ADR-NNN: Título de la Decisión

## Estado
[Propuesto | Aceptado | Deprecado | Reemplazado por ADR-XXX]

## Contexto
¿Cuál es el problema o situación que requiere una decisión?
¿Qué "fuerzas" influyen (técnicas, organizacionales, políticas)?

## Decisión
¿Qué decidimos hacer? Usar voz activa: "Usaremos...", "Implementaremos..."

## Consecuencias
¿Qué resulta de esta decisión? Positivas, negativas, y neutras (trade-offs aceptados)

03 —

Cuándo escribir un ADR

Escribe ADR si...	NO necesitas si...
Decisión afecta múltiples componentes	Decisión es local a una función
Difícil o costoso de cambiar después	Fácilmente reversible
El equipo debatió la decisión	Hay consenso obvio
Un nuevo miembro preguntaría "¿por qué?"	La razón es evidente del código

Ejemplos típicos que merecen ADR: elección de base de datos, arquitectura de comunicación entre servicios, framework principal, estrategia de autenticación, patrón de manejo de errores, estructura de monorepo vs. multirepo.

El estado importa tanto como el contenido

Un ADR no es un documento estático — el ciclo Propuesto → Aceptado → Deprecado → Reemplazado reconoce que las decisiones envejecen. Un ADR "Aceptado" hace 3 años sin revisión no es evidencia de que la decisión siga siendo correcta hoy, solo de que nadie la ha revisitado. El historial de ADRs reemplazados es tan valioso como los vigentes: muestra cómo evolucionó el sistema y por qué.

04 —

Practica: escribe el ADR de Redis vs. JWT

Retoma el caso de la lección: el equipo eligió Redis para sesiones en lugar de JWT, por razones de seguridad (revocación instantánea).

Escribe el ADR completo siguiendo el formato Nygard — contexto (qué fuerzas influían: necesidad de poder revocar sesiones al instante), decisión, y consecuencias (positivas: revocación inmediata; negativas: dependencia de infraestructura adicional; neutras: trade-off aceptado conscientemente).