Architecture Decision Records (ADR)

Qué merece un ADR

Una decisión es arquitectónicamente significativa cuando afecta a la estructura, a atributos de calidad (rendimiento, seguridad, disponibilidad), a dependencias, a interfaces o a la forma de construir, y cuando revertirla cuesta tiempo o dinero. Elegir un nombre de variable no lo es; elegir el broker de eventos sí.

Una prueba rápida: si dentro de un año alguien preguntará «¿por qué se hizo así?», conviene escribirlo hoy.

Estructura mínima

La plantilla original de Nygard tiene cinco partes; MADR añade opciones y criterios explícitos.

Sección	Contenido
Título	Frase nominal corta, numerada: 0007. Usar outbox para publicar eventos
Estado	Propuesto, aceptado, rechazado, obsoleto o reemplazado por ADR-00NN
Contexto	Fuerzas en juego: requisitos, restricciones, supuestos, riesgos
Decisión	Lo que se hará, en voz activa: «Usaremos…»
Consecuencias	Lo que mejora, lo que empeora y lo que queda pendiente
Opciones (MADR)	Alternativas evaluadas con pros y contras

Ejemplo de ADR

# 0007. Publicar eventos de dominio con transactional outbox

- Estado: aceptado
- Fecha: 2026-10-17
- Decisores: equipo Originación, arquitectura
- Consultados: Operaciones, Riesgos

## Contexto

El servicio de solicitudes guarda en PostgreSQL y publica eventos en Kafka.
Hoy hace ambas cosas en secuencia: si Kafka falla tras el commit, el evento
se pierde y Riesgos no evalúa la solicitud.

## Opciones

1. Publicar tras el commit con reintentos en memoria.
2. Transactional outbox + relay con CDC (Debezium).
3. Transacciones distribuidas (XA).

## Decisión

Opción 2. El evento se escribe en la tabla `outbox` en la misma transacción.

## Consecuencias

- (+) No se pierden eventos; entrega al menos una vez.
- (−) Los consumidores deben ser idempotentes.
- (−) Nueva pieza operativa: el conector CDC.
- Pendiente: definir retención de la tabla outbox.

Dónde y cómo guardarlos

Guarda los ADR en el repositorio del sistema afectado (docs/adr/) para que se revisen en el mismo pull request que el cambio. Para decisiones transversales, un repositorio de arquitectura con un índice. Herramientas como adr-tools o log4brains generan numeración e índices, pero un directorio de Markdown basta.

Antipatrones frecuentes

• ADR retroactivo de cortesía: escrito semanas después, sin las alternativas reales. Pierde el razonamiento.
• Novela: diez páginas que nadie lee. Si no cabe en una o dos pantallas, divide la decisión.
• Sin consecuencias negativas: toda decisión tiene costes. Si no aparecen, no se analizaron.
• Editar la historia: modificar un ADR aceptado en lugar de reemplazarlo.

Ciclo de vida

Propuesto ──(revisión y consejo)──► Aceptado ──(nueva decisión)──► Reemplazado por ADR-00NN
    │                                   │
    └──► Rechazado                      └──► Obsoleto (ya no aplica, sin reemplazo)

El ADR propuesto se abre como pull request: la discusión queda en los comentarios y el merge equivale a la aceptación. Los rechazados también se conservan: evitan repetir la misma discusión meses después.

Decisiones típicas que merecen ADR

Ámbito	Ejemplos
Integración	Síncrono vs. eventos con un proveedor; elección de broker
Datos	Base de datos por servicio; estrategia de multitenancy; retención
Seguridad	Proveedor de identidad; cifrado de campos; gestión de secretos
Plataforma	Cloud Run vs. GKE; región principal y de recuperación
Arquitectura	Límites de bounded contexts; monolito modular vs. microservicios
Prácticas	Trunk-based; política de versiones de API; uso de agentes de IA en el código

Variante MADR con criterios de decisión

## Criterios de decisión

- Cumplir el escenario de disponibilidad del 99,9 %
- Coste operativo asumible por un equipo de 6 personas
- Residencia de datos en la región

## Opciones consideradas

| Opción                  | Disponibilidad | Coste operativo | Residencia |
| ----------------------- | -------------- | --------------- | ---------- |
| Kafka gestionado        | ✔              | Medio           | ✔          |
| Pub/Sub                 | ✔              | Bajo            | ✔          |
| RabbitMQ autogestionado | ~              | Alto            | ✔          |

## Decisión

Pub/Sub, porque cumple los criterios con el menor coste operativo; reevaluar si
necesitamos reprocesar eventos con más de 7 días de antigüedad.

Escribir los criterios antes de comparar opciones reduce el sesgo de justificar una preferencia previa.

ADR y agentes de IA

Los agentes de código leen el repositorio: un índice de ADR enlazado desde AGENTS.md evita que propongan revertir decisiones ya tomadas («no uses llamadas síncronas al buró; ver ADR-0007»). También pueden ayudar a redactar el borrador a partir de la discusión de un PR, siempre con revisión de quien decide.

Señales de un proceso sano

• Los ADR nuevos aparecen a un ritmo constante, no solo al inicio del proyecto.
• Las personas nuevas los citan en sus primeras semanas.
• Las revisiones de diseño empiezan por «¿qué ADR aplica?».
• Hay ADR reemplazados: la arquitectura evoluciona y queda registro de por qué.

Criterios de implementación

Empieza registrando las próximas tres decisiones, no el pasado completo. Combínalo con el architecture advice process: el ADR es el artefacto donde queda el consejo recibido. Revisa periódicamente los ADR con estado «propuesto» para que no se queden en limbo, y enlázalos desde los diagramas C4 cuando expliquen una relación.