Registros de decisiones de arquitectura (ADR)

Qué es un ADR y qué problema resuelve

Un registro de decisiones de arquitectura (ADR) es un documento de texto breve que recoge una decisión arquitectónicamente significativa: la situación que la impuso, las opciones que se sopesaron, lo que se eligió y lo que se deriva de esa elección. Un conjunto de ellos, guardados en orden, forma la bitácora de decisiones de un sistema. La idea de registrar las decisiones es antigua (la investigación sobre la justificación del diseño se remonta a varias décadas, y Jeff Tyree y Art Akerman publicaron una plantilla de decisión detallada en IEEE Software en 2005), pero la forma ligera que usan hoy la mayoría de los equipos procede de la entrada de blog de Michael Nygard Documenting Architecture Decisions, publicada el 15 de noviembre de 2011.

El punto de partida de Nygard era un problema que reconoce todo equipo que lleva mucho tiempo con un sistema. Un nuevo desarrollador encuentra en el código una decisión que parece extraña: una cola de más, una tabla duplicada, una biblioteca que nadie elegiría hoy. Sin saber por qué se tomó, el recién llegado tiene dos malas opciones. Puede aceptarla a ciegas, conservando algo cuyas razones quizá ya no se apliquen, o cambiarla a ciegas, rompiendo algo cuyas razones siguen vigentes. El remedio de Nygard fue poner por escrito las razones en el momento de tomar la decisión, en un pequeño archivo guardado con el código, para que la motivación viaje con el sistema. Los grandes documentos de arquitectura rara vez lo logran porque nadie los actualiza; un registro breve de una sola decisión, escrito una vez y nunca reescrito, sigue siendo cierto porque solo pretende describir lo que se sabía y se decidió en una fecha concreta.

Esto se basa directamente en la anatomía de una decisión descrita en el Capítulo 1: decisiones y compromisos: contexto, opciones, criterios, decisión con su justificación, consecuencias y estado. Un ADR es simplemente esa anatomía puesta por escrito en un formato predecible. También responde a la pregunta que arquitectura frente a diseño deja abierta en la práctica: si la arquitectura es el conjunto de decisiones significativas, la bitácora de ADR es lo más parecido que tiene un equipo a una lista de su arquitectura.

El formato de Nygard

Nygard propuso cinco partes. La mayoría de los equipos aún las usan, a menudo moviendo el estado al principio para que los lectores vean de inmediato si el registro está en vigor. Sus indicaciones sobre cómo escribir cada parte importan tanto como los encabezados.

Nygard también sugirió que un registro debería caber en una o dos páginas, que los registros se numeren de forma secuencial y que los números nunca se reutilicen, y que vivan en el repositorio del proyecto como texto plano. Cada una de esas pequeñas reglas existe por una razón: los registros breves se leen, los números estables pueden citarse en comentarios de código y mensajes de commit, y el texto plano en el repositorio puede revisarse y versionarse como el código.

Otras plantillas: MADR, declaraciones Y y formas más completas

El formato de Nygard no dice nada explícito sobre las opciones que se rechazaron, y muchos equipos descubrieron que las alternativas son precisamente lo que más quiere saber un lector posterior. Varias plantillas las añaden.

MADR (Markdown Architectural Decision Records, mantenida en adr.github.io) es la plantilla estructurada más usada. Su versión vigente en el momento de escribir esto es la 4.0.0, publicada en septiembre de 2024. La plantilla completa tiene un título y, después, Contexto y planteamiento del problema, Impulsores de decisión (opcional), Opciones consideradas, Resultado de la decisión con las subsecciones opcionales Consecuencias y Confirmación, Pros y contras de las opciones (opcional) y Más información (opcional). Los metadatos, como el estado, la fecha, los responsables de la decisión y a quién se consultó y a quién se informó, pueden ir en una cabecera YAML. Dos ideas de MADR merecen adoptarse aunque uses otro formato. Los impulsores de decisión hacen explícitos los criterios antes de juzgar las opciones, que es la disciplina de la matriz ponderada del Capítulo 1 en forma compacta. La confirmación indica cómo comprobará el equipo que la decisión se implementa realmente y sigue siendo válida, por ejemplo mediante una revisión, una prueba o una comprobación automatizada de la arquitectura.

La declaración Y, propuesta por Olaf Zimmermann y sus colegas y presentada por primera vez en la conferencia SATURN en 2012, comprime una decisión en una sola frase estructurada: en el contexto de (un caso de uso o un componente), ante (una inquietud o un requisito de calidad), optamos por (la opción) y descartamos (las alternativas), para lograr (los beneficios), aceptando que (los inconvenientes). El nombre es un juego de palabras en inglés: la Y suena como why (por qué). Una declaración Y es ideal para el resumen de una bitácora de decisiones, una diapositiva, un comentario de código o la descripción de un pull request; para una puerta de un solo sentido que es objeto de debate suele quedarse demasiado comprimida, y los equipos la amplían hasta un registro completo.

Existen plantillas más pesadas para entornos regulados o muy grandes. La plantilla de Tyree y Akerman de 2005 añade campos como supuestos, restricciones, decisiones relacionadas, requisitos relacionados e implicaciones. Son útiles cuando las decisiones deben poder trazarse hasta los requisitos para un auditor; para la mayoría de los equipos de producto añaden un esfuerzo que nadie lee.

Estado, ciclo de vida y por qué no se editan los registros aceptados

Un ADR pasa por un número reducido de estados. Empieza como propuesto, normalmente como un pull request que añade el archivo, para que el debate tenga lugar en los comentarios de la revisión. Cuando las personas responsables están de acuerdo, se fusiona como aceptado. Una propuesta que no prospera puede conservarse con el estado rechazado, lo cual es valioso: la próxima persona que sugiera la misma idea encontrará el razonamiento anterior. Más adelante, un registro aceptado puede pasar a obsoleto (la decisión ya no se aplica, quizá porque se retiró el componente) o quedar reemplazado por un registro más reciente que lo sustituye, con enlaces en ambas direcciones. MADR enumera el mismo conjunto: propuesto, rechazado, aceptado, obsoleto y reemplazado.

La regla central es que el contenido de un registro aceptado no se reescribe. Si el equipo cambia de opinión, escribe un nuevo ADR que reemplaza al anterior y solo cambia la línea de estado del registro antiguo para que apunte al nuevo. Las razones son prácticas. Primero, el registro es una prueba de lo que se sabía y se decidió en un momento dado; editarlo a posteriori convierte la historia en ficción y destruye la confianza que hace útil la bitácora. Segundo, el registro antiguo explica por qué el sistema era como era durante un periodo, lo que importa al depurar datos antiguos o al leer código antiguo. Tercero, un nuevo registro obliga al equipo a explicar qué cambió en el contexto, que suele ser la idea más importante. Las correcciones pequeñas (una errata, un enlace roto) son inofensivas; cambiar la decisión, las razones o las consecuencias no lo es. La descripción de la práctica que hace Martin Fowler dice lo mismo: una vez aceptado, un registro no se reabre; en su lugar se escribe un registro que lo reemplaza.

Dónde guardar los ADR

Guarda los ADR en el repositorio del código que gobiernan, como archivos de texto plano (normalmente Markdown), una decisión por archivo, con un número de secuencia y un slug breve en el nombre del archivo. Hay dos convenciones de directorio habituales: doc/adr, la predeterminada de la herramienta de línea de comandos adr-tools de Nat Pryce, y docs/decisions, recomendada por MADR con nombres como 0012-publish-order-events-through-broker.md. Thoughtworks colocó los ADR ligeros en el anillo Adopt (adoptar) de su Technology Radar (la última vez en 2018) y recomendó expresamente el control de código fuente en lugar de una wiki, para que los registros vayan al paso del código que describen.

Guardar los registros junto al código tiene ventajas concretas. Se revisan en los mismos pull requests que el código que los implementa, se versionan y se ramifican con él, un desarrollador puede encontrarlos con las mismas herramientas de búsqueda, y el código puede apuntar a ellos: un comentario como ver ADR-0012 encima del retransmisor de la bandeja de salida (outbox relay) le indica al siguiente lector dónde están las razones. Las decisiones que abarcan muchos repositorios, como la elección de un proveedor de identidad para toda la organización, necesitan un lugar propio; un repositorio de arquitectura dedicado con las mismas convenciones funciona bien, con enlaces desde cada base de código afectada.

docs/
  decisions/
    README.md                                  <- the decision log (index)
    0001-record-architecture-decisions.md
    0004-use-hosted-card-fields.md
    0007-use-managed-postgresql-for-orders.md
    0012-publish-order-events-through-broker.md
    template.md
src/
  ordering/
    outbox_relay.py      # comment: see docs/decisions/0012-...

Qué decisiones merecen un ADR

Escribir un ADR para cada elección entierra las importantes; no escribir ninguno pierde las razones. El criterio es que la decisión sea significativa, tal como se definió en el Capítulo 1: una decisión merece un registro cuando es cara de revertir, afecta a un atributo de calidad clave, tiene un alcance amplio, restringe a otros equipos o fue objeto de debate. En la práctica, eso significa elecciones como el almacén de datos principal, el estilo de comunicación entre servicios, el proveedor de identidad, la política de versionado de API, la plataforma de alojamiento, una decisión de construir o comprar, y las convenciones cuyo incumplimiento sale caro (cómo se representa el dinero, cómo se almacenan las zonas horarias). También incluye las decisiones de no hacer algo que la gente sigue proponiendo, como no introducir todavía una caché.

Las elecciones locales, baratas de revertir e invisibles fuera de un módulo no suelen necesitar registro: la elección de una biblioteca de aserciones para pruebas, el nombre de una clase, la organización interna de un componente. Una señal útil es la pregunta que haría alguien recién llegado: si es probable que alguien pregunte ¿por qué demonios hicieron esto? antes de un año, escribe el registro ahora, mientras las razones están frescas.

Un ADR completo como ejemplo práctico

La plataforma de reparto de comida que se usa a lo largo de este capítulo tiene aplicaciones para clientes, restaurantes y repartidores, un servicio de pedidos, pagos a través de un proveedor de pagos externo, el despacho de repartidores y las notificaciones. El registro de abajo sigue la estructura de MADR, ligeramente abreviada. Fíjate en cómo el contexto da cifras y fechas en lugar de adjetivos, en cómo se enuncian los impulsores antes que las opciones, en cómo se trata con justicia a las opciones rechazadas y en cómo las consecuencias incluyen costos reales. La decisión en sí (mensajería asíncrona para los eventos de pedido) se trata a fondo en el Capítulo 6: arquitectura dirigida por eventos; aquí lo que importa es cómo se registra.

# ADR-0012: Publish order events through a managed message broker

- Status: Accepted
- Date: 2026-09-14
- Deciders: ordering team lead, platform lead, principal architect
- Consulted: restaurant, courier and notifications teams; SRE
- Related: ADR-0007 (managed PostgreSQL for the order service)

## Context and problem statement

When a customer's payment succeeds, the ordering service calls the restaurant,
courier-dispatch and notification services synchronously over HTTP before it
confirms the order. On Friday evenings (peak about 40 orders/s) p99 order
confirmation time reaches 4.2 s against our target of 1.5 s (scenario QS-3).
On Friday 21 August a notification-service outage blocked all new orders for
23 minutes. Two new consumers (loyalty points, analytics) want order data.

## Decision drivers

- Order confirmation must not depend on notification or dispatch availability.
- p99 confirmation under 1.5 s at three times today's peak.
- No order event may be lost, even if a service crashes mid-request.
- New consumers should not require changes to the ordering service.
- The platform team has three people; operational load must stay small.

## Considered options

1. Keep synchronous calls; add timeouts, retries and circuit breakers.
2. Publish events to a managed message broker using a transactional outbox.
3. Let consumers poll a shared "order_events" table in the order database.

## Decision outcome

Chosen option: 2. We will publish OrderPlaced, OrderAccepted, OrderPickedUp,
OrderDelivered and OrderCancelled events to our cloud provider's managed
broker. The ordering service writes each event to an outbox table in the
same database transaction as the order; a relay publishes it. Payment
authorisation stays synchronous, because the customer must see the result.

### Consequences

- Good: confirmation no longer waits for downstream services.
- Good: loyalty and analytics can subscribe without ordering-team work.
- Bad: services become eventually consistent; the restaurant tablet may
  show a new order a second or two after the customer's confirmation.
- Bad: a broker to pay for and monitor; consumers must be idempotent
  because delivery is at-least-once.
- Neutral: event schemas become public contracts and need versioning.

### Confirmation

Load test at 120 orders/s in staging before go-live; a build check fails
if the ordering service gains an HTTP client for notification or dispatch.

## Pros and cons of the other options

- Option 1: least new infrastructure, but a slow dependency still delays
  every order, and each new consumer means another call to add.
- Option 3: no new infrastructure, but couples every consumer to our schema
  and adds polling load to the order database (see ADR-0007).

Revisar los ADR

Como un ADR es un archivo del repositorio, el mecanismo natural de revisión es el pull request. Quien lo propone lo abre con el estado propuesto; las personas afectadas comentan; el registro se corrige; cuando las personas responsables están de acuerdo, el estado cambia a aceptado y se fusiona. Así el debate queda unido al registro y visible para cualquiera que lea más tarde el historial.

Quién debe revisar depende de cómo se gobiernen las decisiones. En un modelo centralizado, una junta de arquitectura aprueba los registros significativos. En el proceso de consejo (advice process) descrito por Andrew Harmel-Law (martinfowler.com, 2021), cualquiera puede tomar una decisión arquitectónica, siempre que antes pida consejo a todas las personas afectadas de forma significativa y a quienes tengan la experiencia pertinente, y que registre ese consejo; quien decide no está obligado a seguir el consejo, pero sí a escucharlo. Los ADR son la columna vertebral de ese proceso: el consejo aparece en el registro, y un foro asesor abierto y periódico revisa los registros propuestos. Los modelos de gobernanza se tratan en el Capítulo 11: gobernanza en organizaciones ágiles.

La lista de comprobación ecADR de Olaf Zimmermann (2020) ofrece a los revisores una definición de terminado compacta para una decisión. Evidencia: hay motivos para creer que la opción funcionará, a partir de un spike, una prueba de concepto o una experiencia fiable. Criterios: se compararon al menos dos opciones con las inquietudes de las partes interesadas. Acuerdo: la decisión ha sido cuestionada por los pares y el equipo la acepta. Documentación: está registrada y compartida con los afectados. Realización y revisión: la implementación está planificada y se ha fijado una fecha o un desencadenante para volver a revisarla. Un revisor que comprueba esos cinco puntos, además de la honestidad de las consecuencias, detecta la mayoría de los registros flojos.

Antipatrones

Los ADR fallan de formas reconocibles. Zimmermann catalogó varias en 2023 con nombres fáciles de recordar, y conviene conocer las más dañinas.

La bitácora de decisiones como índice

Los registros individuales son útiles; la bitácora en su conjunto lo es más. Un breve archivo de índice (a menudo el README.md de la carpeta de decisiones) enumera cada registro con su número, título, estado y fecha. Quien llega nuevo lo lee en cinco minutos y obtiene una historia comprimida de la arquitectura: qué se decidió, qué se rechazó, qué se reemplazó y cuándo. Herramientas como adr-tools pueden generar el índice y crear registros de reemplazo que actualizan automáticamente el estado del registro antiguo, y herramientas de documentación como el DSL de Structurizr pueden importar una carpeta de ADR a la documentación publicada.

Trata la bitácora como parte de la descripción de la arquitectura. La plantilla arc42 tiene una sección para las decisiones de arquitectura que puede limitarse a enlazar con ella, y un pipeline de documentación como código puede publicarla junto con el resto de la documentación.

# Decision log

| ADR  | Title                                                | Status                 | Date       |
|------|------------------------------------------------------|------------------------|------------|
| 0001 | Record architecture decisions                        | Accepted               | 2025-03-02 |
| 0004 | Use the payment provider's hosted card fields        | Accepted               | 2025-04-18 |
| 0007 | Use managed PostgreSQL for the order service         | Accepted               | 2025-06-11 |
| 0009 | Send push notifications through a third-party SDK    | Superseded by 0015     | 2025-09-30 |
| 0012 | Publish order events through a managed broker        | Accepted               | 2026-09-14 |
| 0013 | Store courier locations in a time-series database    | Rejected               | 2026-09-20 |
| 0015 | Run our own notification service on the broker       | Accepted               | 2026-10-08 |