Plantilla de Architecture Decision Record (ADR)

Descripción General

Cada decisión arquitectónica mayor crea contexto que se desvanece en meses. Por que elegimos PostgreSQL sobre MongoDB? Por que el service mesh es Envoy y no Linkerd? Por que shard por tenant ID? Sin registros escritos, nuevos ingenieros re-litigan viejas decisiones, equipos repiten enfoques rechazados, y managers hacen planes que entran en conflicto con restricciones técnicas. Un Architecture Decision Record (ADR) es un documento único que captura el contexto, opciones, trade-offs, y consecuencias de una elección técnica mayor. Documentos relacionados: Diseñar un API Gateway Escalable para Microservicios, Construir Sistemás Resilientes con el Circuit Breaker y Inyección de Dependencias.

Cuándo Usar

Usa esta plantilla cuando:

• Una decisión afecta a más de un equipo o servicio
• La decisión es difícil de deshacer o sera costosa de revertir
• Evaluaste múltiples opciones y necesitas explicar por que una ganó
• Esperas que la decisión sea cuestionada o revisitada en el futuro
• Integras nuevos ingenieros que necesitan entender “por qué el sistema funciona así”
• Para documentación de procesos en lugar de decisiones, consulta la plantilla de handbook de ingeniería

Prerrequisitos

Antes de escribir un ADR:

• Confirma que la decisión es lo suficientemente mayor para documentar (no cada PR necesita un ADR)
• Reúne input de stakeholders que serán afectados por la decision
• Documenta opciones que consideraste seríamente, no solo la ganadora
• Identifica quién tiene autoridad para aprobar o revocar la decision
• Elige dónde viven los ADRs (repo Git /docs/adr/, wiki, o docs site dedicado)

Solución

# ADR-XXX: `<Titulo de la Decision>`

| Campo | Valor |
|-------|-------|
| Estado | Propuesto / Aceptado / Deprecado / Reemplazado por ADR-YYY |
| Fecha | AAAA-MM-DD |
| Autor | ______ |
| Decisores | ______ |
| Tags | ______ |

## 1. Contexto y Planteamiento del Problema

[Cual es el problema u oportunidad que disparo esta decision? Que fuerzas estan en juego, incluyendo técnicas, de negocio, y de equipo? Que pasa si no hacemos nada?]

## 2. Motivadores de la Decision

- [Motivador 1: ej., debe soportar 10x crecimiento de trafico en 2 anos]
- [Motivador 2: ej., el equipo tiene expertise profundo en X pero no en Y]
- [Motivador 3: ej., requerimiento de compliance para residencia de datos]
- [Motivador 4: ej., debe integrarse con sistemás existentes sin breaking changes]

## 3. Opciones Consideradas

### Opción 1: [Nombre]
- **Descripción:** [Que es?]
- **Pros:** [Por que es atractiva]
- **Contras:** [Por que es riesgosa o problematica]
- **Esfuerzo:** [Estimacion aproximada: pequeño / mediano / grande]

### Opción 2: [Nombre]
- **Descripción:**
- **Pros:**
- **Contras:**
- **Esfuerzo:**

### Opción 3: [Nombre]
- **Descripción:**
- **Pros:**
- **Contras:**
- **Esfuerzo:**

## 4. Decision

**Opción elegida:** [Opción X]

**Razonamiento:** [Por que esta opción gana. Referencia los motivadores de la decisión — cuales satisface mejor?]

**Trade-offs aceptados:** [Que estamos sacrificando al elegir esta opción?]

## 5. Consecuencias

### Positivas
- ______
- ______

### Negativas
- ______
- ______

### Riesgos
- ______

### Mitigaciones
- ______

## 6. Notas de Implementación

- [Paso 1: ______]
- [Paso 2: ______]
- [Paso 3: ______]

## 7. Decisiones Relaciónadas

| ADR | Relación |
|-----|----------|
| ADR-___ | Reemplaza / Depende de / Conflicta con / Complementa |

## 8. Registro de Cambios

| Fecha | Cambio | Autor |
|-------|--------|-------|
| AAAA-MM-DD | Propuesto | ______ |
| AAAA-MM-DD | Aceptado | ______ |

Explicación

El formato ADR es intencionalmente ligero. No requiere diagramás UML ni pruebas formales — solo suficiente estructura para que alguien que lo lea en dos anos entienda por que se tomo la decisión y que se sacrifico. El campo de estado es critico: indica a los lectores si la decisión esta activa, obsoleta, o reemplazada. La sección de consecuencias previene el error comun de documentar solo el camino feliz; toda elección arquitectónica tiene desventajas, y ocultarlas crea sorpresas después.

Ejemplo Completo de ADR

# ADR-015: Migración a PostgreSQL para almacenamiento de datos principal

## Estado
Aceptado (2026-07-11)

## Contexto
La aplicación utiliza MySQL 5.7 desde 2023. Con el crecimiento del equipo y los datos, hemos encontrado limitaciones:
- Falta de soporte para JSONB y consultas JSON nativas
- Replicacion lógica limitada comparada con PostgreSQL
- Sin soporte para particionamiento declarativo
- Costos de licencia para MySQL Enterprise

El equipo de plataforma necesita particionamiento a nivel de tabla para manejar el crecimiento de la tabla de eventos (actualmente 2TB, creciendo 50% anual).

## Decision
Migrar a PostgreSQL 16 como base de datos principal.

## Alternativas Consideradas

### 1. Permanecer en MySQL 8.0
- Ventajas: Migración más simple, equipo familiarizado
- Desventajas: JSONB menos potente, particionamiento más limitado
- Rechazada: No resuelve el requisito de particionamiento

### 2. Migrar a Amazon Aurora PostgreSQL
- Ventajas: Compatible con PostgreSQL, gestionado, replicación global
- Desventajas: Costo más alto, vendor lock-in
- Aplazada: Evaluar después de migrar a PostgreSQL auto-gestionado

### 3. Migrar a CockroachDB
- Ventajas: Distribuido, SQL compatible con PostgreSQL
- Desventajas: Costo, complejidad, equipo sin experiencia
- Rechazada: Sobre-ingenieria para necesidades actuales

## Consecuencias

### Positivas
- Particionamiento declarativo nativo
- JSONB para datos semi-estructurados
- Replicacion lógica robusta
- Comunidad activa y herramientas maduras (pgAdmin, pgBackRest)

### Negativas
- Curva de aprendizaje para el equipo (2-4 semanas)
- Necesidad de migrar queries específicas de MySQL
- Herramientas de monitoreo diferentes (pg_stat_statements vs slow query log)

### Mitigaciones
- Capacitacion del equipo en PostgreSQL antes de la migración
- Usar pgloader para migración automática de esquemás y datos
- Mantener MySQL en paralelo durante 30 dias como fallback

## Notas de Implementación
1. Fase 1: Configurar PostgreSQL en staging, migrar esquema con pgloader
2. Fase 2: Migrar datos en staging, ejecutar tests de aplicación
3. Fase 3: Migrar produccion con downtime planificado (ventana de mantenimiento)
4. Fase 4: Monitorear por 30 dias, decomisionar MySQL

## Decisiones Relaciónadas

| ADR | Relación |
|-----|----------|
| ADR-008 | Depende de (monitoreo de base de datos) |
| ADR-012 | Complementa (estrategia de backup) |

## Registro de Cambios

| Fecha | Cambio | Autor |
|-------|--------|-------|
| 2026-07-04 | Propuesto | alice@example.com |
| 2026-07-11 | Aceptado | platform-team |

El Ciclo de Vida del ADR

Estado	Significado	Acción
Propuesto	Redactado, en revisión	Circular, recoger feedback
Aceptado	Aprobado y activo	Implementar, enlazar desde docs
Deprecado	Ya no activo, no reemplazado	Marcar con fecha y razón
Reemplazado	Sustituido por un ADR nuevo	Agregar link al sucesor, conservar el original

La mayoría de ADRs vive dos vidas: unos días en Propuesto, luego años en Aceptado. Los estados finales importan más de lo que se espera — un ADR deprecado que nadie marcó es peor que no tener ADR, porque los lectores le creen. Nunca borres un ADR: el rastro es el valor.

Cuándo NO Escribir un ADR

No toda decisión merece registro. Sáltalo cuando:

• La elección es reversible en una tarde — cambiar una regla de lint, renombrar un paquete
• La decisión es personal, no arquitectónica — qué editor, cómo nombrar una variable
• Un ticket ya la captura — tareas puntuales sin lector futuro
• Documentas el cómo, no el por qué — eso va en un runbook

La prueba: ¿alguien en dos años preguntará “por qué lo hicieron así?” Si sí, escribe el ADR.

Adoptando ADRs en un Equipo

Introducir ADRs en un equipo que nunca los usó falla predeciblemente: alguien escribe una página de wiki, dos personas la adoptan, seis meses después hay cuatro ADRs y nadie recuerda la convención. Lo que funciona:

1. Siembra con historia — elige las cinco decisiones que todos discuten y escribe ADRs retroactivos. Índice instantáneo, valor instantáneo.
2. Conecta al flujo existente — la plantilla de PR pregunta “¿necesita ADR?”; un checkbox, no una reunión.
3. Baja la barrera — los primeros ADRs son feos y está bien; un registro corto que existe gana a una plantilla perfecta que nadie llena.
4. Revisa visiblemente — lee un ADR viejo en voz alta en una reunión; el día que alguien dice “ya no hacemos eso” es el día que la práctica se paga sola.

Pasados los cincuenta ADRs la práctica cambia de forma: la carpeta necesita un índice por subsistema, los títulos cargan el peso de la búsqueda, y los registros deprecados van a un archive/ para que el set activo siga escaneable.

El Registro de Decisiones como Activo

Una carpeta de treinta ADRs vale más que la suma de sus páginas. Consúltala antes de las revisiones de arquitectura: “¿qué decidimos sobre el orden de mensajes?” se convierte en una respuesta buscable en vez de un rumor. Úsala en el onboarding — los ingenieros nuevos leen el registro de decisiones antes que el código, porque el código muestra qué existe y el registro explica por qué existe. Y úsala en las revisiones de incidentes: cuando el postmortem pregunta “¿cómo terminamos con este diseño?”, el rastro de ADRs responde o revela que una decisión crítica nunca se registró — lo cual es en sí un hallazgo que merece un ADR.

El registro también disciplina propuestas futuras. Un equipo que puede enlazar ADR-023 para mostrar “ya rechazamos esto y aquí está el porqué” deja de re-litigar preguntas resueltas; el rechazo queda archivado con su razonamiento, así que la conversación pasa a qué cambió desde entonces, no a empezar de cero. Ese es el retorno compuesto de la práctica: las decisiones dejan de re-hacerse y empiezan a construirse unas sobre otras.

Lo que la Plantilla Omite Deliberadamente

El formato ADR no tiene resumen ejecutivo, ni diagrama de Gantt, ni matriz de sign-off de stakeholders — y es intencional. Los documentos que exigen ceremonia se escriben una vez y se abandonan; el ADR sobrevive porque su costo es una hora honesta de escritura, no una semana de formato. Si tu organización necesita el aparato más pesado (estimaciones de costo, revisión legal, cronogramas de rollout), agrégalo como variante a nivel organización — la tabla de Variantes tiene el patrón — pero resiste ponerlo en la plantilla base. El trabajo de la plantilla base es la estructura mínima que preserva el por qué; todo lo demás es política local.

Una omisión que vale defender explícitamente: no hay “puntaje de recomendación” ni matriz de decisión ponderada. Las matrices de puntaje parecen objetivas pero codifican las preferencias del autor en los pesos — el ADR pide el razonamiento en prosa, porque la prosa no puede esconder un mal argumento detrás de aritmética.

Manteniendo los ADRs Encontrables

Un ADR que nadie encuentra es un ADR que nadie sigue. Tres hábitos mantienen el registro navegable: numeración secuencial que nunca se recicla (ADR-042 queda ADR-042 aunque sea reemplazado — el número es la cita), un README.md índice en la carpeta de ADRs agrupado por subsistema en vez de por fecha, y enlaces desde donde la gente realmente busca — el README del servicio, la doc de onboarding, el runbook que opera el sistema afectado. Cuando un ADR es reemplazado, el archivo viejo conserva su lugar en el índice con el estado tachado; el lector que llega desde un link viejo debería ver, de un vistazo, “esto es historia — ve a ADR-051”.

Una Nota sobre el Momento

Escribe el ADR mientras el razonamiento sigue tibio — idealmente la misma semana en que la decisión madura, nunca trimestres después. Los ADRs tardíos no son inútiles (un registro retroactivo gana a una leyenda oral), pero reconstruyen mucho mejor el caso de la opción ganadora que el de las perdedoras, porque los argumentos perdedores mueren indocumentados. Si estás rellenando retroactivamente, dilo en el registro: “escrito en retrospectiva” es metadata honesta que le dice al lector que descuente la confianza de la sección de alternativas en consecuencia.

Y un momento más que vale registrar: cuando la decisión deja de re-preguntarse. El ADR que cierra un debate recurrente de tres años es el que pagó toda la práctica — nótalo en el changelog, enlaza el debate resuelto, y deja que el registro cierre el ciclo para el que se escribió.

Cómo Revisar un ADR

Revisar un registro de decisión no es corrección de estilo. Las preguntas que responde un revisor:

• ¿El contexto es falsificable? “Necesitamos escala” es ruido; “llegamos a 4k pedidos/minuto y la llamada sync suma 300ms” es una restricción que alguien puede desafiar.
• ¿Las alternativas son reales? Cada opción rechazada necesita una razón que siga teniendo sentido el año que viene.
• ¿La decisión se sigue del contexto? Si un extraño puede leer el contexto y elegir otra opción, falta algo en el contexto.
• ¿Las consecuencias son honestas? Un ADR con solo consecuencias positivas se escribió para ganar una discusión, no para documentar una decisión.

Variantes

Contexto	Ajustes	Notas
ADR a nivel de equipo	Mas corto; enfocado en alcance local y trade-offs inmediatos	No toda decisión necesita buy-in a nivel organización
ADR a nivel de organización	Agregar sección de aprobacion, estimaciones de costo, y timeline de migración	Decisiones cross-team necesitan sign-off explicito
ADR de infraestructura	Agregar capacity planning, impacto en runbooks, y carga operacional	Las elecciones de infraestructura son difíciles de deshacer
ADR de seguridad	Agregar modelo de amenazas, mapeo de compliance, y sign-off de revision de seguridad	Las decisiones de seguridad necesitan aprobacion explicita
ADR de deprecacion	Documentar por que una vieja decisión se revierte y que la reemplaza	La deprecacion merece su propio ADR

Lo que funciona

1. Numera ADRs secuencialmente — ADR-001, ADR-002 — para que las referencias sean inequívocas
2. Almacena ADRs en control de versiones — deberían revisarse, aprobarse, y rastrearse como codigo
3. Mantenlos cortos — si toma más de 10 minutos leerlo, es demasíado largo
4. Link ADRs relacionados — las decisiones no existen en aislamiento; muestra la cadena de razonamiento
5. Acepta la deprecacion — marca ADRs como reemplazados cuando surgen mejores opciones; no los borres

Errores Comunes

1. Escribir ADRs para todo — no cada PR o upgrade de libreria necesita un ADR; reservalos para elecciones mayores e irreversibles
2. Documentar solo la ganadora — futuros lectores necesitan saber que fue rechazado y por que, o lo propondran de nuevo
3. Ocultar consecuencias negativas — toda decisión tiene trade-offs; documentarlos genera confianza y previene sorpresas
4. Dejar que los ADRs se vuelvan obsoletos — actualiza el estado a “Deprecado” o “Reemplazado” cuando cambien las decisiones
5. Hacerlos difíciles de encontrar — los ADRs deberían estar linkeados desde READMEs, docs de onboarding, y overviews de arquitectura

Lectura Adicional

• Michael Nygard — Documenting Architecture Decisions — el post de 2011 que definió el formato
• ADR Organization — plantillas, tooling e índice de la práctica ADR
• adr-tools — CLI para crear y vincular ADRs