Plantilla ADR para decisiones de arquitectura de software

Guarda el razonamiento que no cabe en un diagrama

Una decisión de arquitectura puede ser costosa de cambiar y difícil de reconstruir meses después. Un ADR (Architecture Decision Record) conserva el contexto, las alternativas consideradas y las consecuencias que el equipo acepta. Conviene escribirlo cuando una elección afecta a límites del sistema, datos, despliegue, seguridad o capacidad de evolución, no por cada detalle de implementación.

Plantilla para copiar

# ADR-XXXX: [decisión en una frase]

Estado: Propuesta | Aceptada | Rechazada | Sustituida
Fecha:
Responsable y revisores:

## Contexto
Qué problema u oportunidad motiva esta decisión.

## Restricciones y objetivos
Requisitos de negocio, disponibilidad, seguridad, coste, equipo y plazo.

## Opciones consideradas
Opción A:
Ventajas:
Desventajas:

Opción B:
Ventajas:
Desventajas:

## Decisión y justificación
Qué opción se adopta y por qué satisface mejor los objetivos.

## Consecuencias y riesgos aceptados
Qué se vuelve más fácil o difícil; riesgos que siguen abiertos.

## Seguimiento
Acciones, propietarios, fecha de revisión y ADR relacionados.

Ejemplo — supuesto ilustrativo

Contexto: un portal de cliente necesita incorporar dos funciones nuevas, pero el equipo también debe reducir dependencias entre módulos. Opciones: ampliar el módulo actual, separar una capacidad detrás de una API o sustituir el portal completo. Decisión: no se elige una alternativa por defecto; el ADR debe registrar la opción que el equipo valide con restricciones y datos del proyecto. Consecuencias: anota tanto el beneficio esperado como el coste operativo y las migraciones pendientes.

El ejemplo es deliberadamente incompleto: una decisión real necesita contexto y evidencia del sistema concreto. El formato sigue el patrón de MADR, Architectural Decision Records en Markdown. Conecta el ADR con el desarrollo de software a medida y, cuando afecte a interfaces, con los patrones de arquitectura e integración.