Registro de Decisión de Arquitectura
Un ADR existe para que dentro de dieciocho meses nadie reabra una cuestión resuelta sin saber por qué se resolvió, y para que cuando el contexto cambie, la decisión pueda ser revisada deliberadamente.
Dónde
docs/adr/NNNN-titulo-corto.md, numerados secuencialmente. Consulta el directorio para el siguiente número y la plantilla base; síguela si existe una.
Plantilla
# NNNN. <Título en forma de decisión: "Usar Aurora PostgreSQL para el servicio de pedidos">
Fecha: YYYY-MM-DD
Estado: Propuesta | Aceptada | Reemplazada por NNNN | Deprecada
Decisores: <nombres o equipo>
## Contexto
<Qué fuerzas están en juego: requisitos, restricciones, dolor actual, plazos, cumplimiento normativo,
habilidades del equipo, límite de costos. De dos a cuatro párrafos. Hechos, no opiniones.>
## Decisión
<Una o dos oraciones, en tiempo presente: "Usaremos …">
## Opciones consideradas
### Opción A: <nombre>
Pros / Contras / Costo aproximado / Carga operativa
### Opción B: <nombre>
…
## Consecuencias
<Qué se vuelve más fácil, qué se vuelve más difícil, qué tenemos que hacer ahora (migraciones,
capacitación, nuevos runbooks), qué estamos aceptando explícitamente como riesgo.>
## Seguimientos
- [ ] <tareas concretas con responsables si se conocen>
Guía de redacción
- Redacta el contexto para que un recién llegado esté de acuerdo en que el problema es real antes de leer la decisión.
- Compara opciones en los mismos ejes: costo, carga operativa, dependencia, familiaridad del equipo, tiempo de entrega, seguridad/cumplimiento normativo. Pon números donde los tengas (estimación de costo mensual, RTO/RPO, rendimiento).
- Sé honesto sobre las fortalezas de las opciones descartadas. Un ADR que presenta alternativas de forma sesgada generará desconfianza.
- Las consecuencias incluyen las negativas. "Ahora tenemos dos bases de datos que respaldar" pertenece ahí.
- Mantenlo en menos de dos páginas. Enlaza a spikes, benchmarks y tickets en lugar de incluirlos directamente.
- Cuando se reemplace, actualiza el estado del ADR anterior y enlaza en ambos sentidos.
Cuando se proporciona $ARGUMENTS
Úsalo como título; deriva el nombre del archivo a partir de él.