Architecture Decision Records (ADR): La guía completa

Todo sistema de software está moldeado por cientos de decisiones. PostgreSQL en lugar de MongoDB. REST en lugar de GraphQL. Monolito en lugar de microservicios. Event-driven en lugar de request-response. Cada elección restringe las futuras, y juntas definen la arquitectura.

El problema es que las decisiones son invisibles. El código muestra qué se construyó, no por qué se construyó de esa manera. Seis meses después de elegir PostgreSQL, nadie recuerda si el equipo consideró DynamoDB, cuáles eran los requisitos de rendimiento o por qué la consistencia eventual era inaceptable. La decisión está integrada en el código, pero el razonamiento se perdió.

Los Architecture Decision Records (ADRs) resuelven esto capturando cada decisión significativa en un documento corto y estructurado. Son una de las prácticas de documentación con mayor apalancamiento en ingeniería de software -- simples de adoptar, económicas de mantener e invaluables cuando las necesitas.

Esta guía cubre todo, desde lo básico hasta prácticas avanzadas: qué son los ADRs, cómo escribirlos, plantillas que puedes adoptar hoy, errores comunes y cómo integrar los ADRs en tu flujo de trabajo con herramientas modernas.

¿Qué es un Architecture Decision Record?

Un Architecture Decision Record es un documento corto que captura una sola decisión arquitectural. El énfasis está en una sola y corto:

• Una sola: Un ADR, una decisión. "Usar PostgreSQL para el servicio de pedidos" es un ADR. "Configurar toda la estrategia de base de datos" es un documento de diseño, no un ADR.
• Corto: Un ADR debería caber en una página. Si es más largo, probablemente estás documentando múltiples decisiones o incluyendo demasiado detalle de implementación.

El concepto fue popularizado por Michael Nygard en un artículo de blog de 2011. Desde entonces, los ADRs han sido adoptados por organizaciones que van desde startups hasta gobiernos. El UK Government Digital Service, Spotify y muchos equipos de ingeniería usan ADRs como práctica estándar.

Qué capturan los ADRs

Cada ADR responde cuatro preguntas fundamentales:

1. ¿Cuál era el contexto? ¿Qué situación o problema motivó esta decisión?
2. ¿Qué decidimos? ¿Cuál es la elección arquitectural específica que hicimos?
3. ¿Qué alternativas consideramos? ¿Qué otras opciones estaban sobre la mesa?
4. ¿Cuáles son las consecuencias? ¿Qué trade-offs, riesgos e implicaciones vienen con esta decisión?

Eso es todo. Cuatro preguntas. Un ADR bien escrito puede responder las cuatro en menos de una página.

Qué no son los ADRs

• No son documentos de diseño. Los ADRs no describen cómo algo está implementado. Describen por qué se eligió un enfoque particular.
• No son RFCs. Los RFCs (Request for Comments) son propuestas para discusión. Los ADRs documentan decisiones concluidas (aunque un ADR puede empezar como propuesta y transicionar a aceptado).
• No son notas de reunión. Los ADRs capturan el resultado, no la discusión que llevó a él.
• No son documentación exhaustiva. Los ADRs complementan diagramas de arquitectura, especificaciones de API y runbooks. No los reemplazan.

La plantilla estándar de ADR

Existen múltiples plantillas de ADR, pero la mayoría son variaciones de la misma estructura central. Aquí tienes una plantilla práctica que equilibra completitud con brevedad:

# ADR-NNNN: [Título corto describiendo la decisión]

## Estado

[Propuesto | Aceptado | Deprecado | Reemplazado por ADR-XXXX]

## Fecha

[AAAA-MM-DD]

## Contexto

[Describe la situación. ¿Qué problema estamos resolviendo? ¿Qué restricciones
existen? ¿Qué fuerzas están en juego? Sé específico -- incluye números,
fechas límite, capacidades del equipo y requisitos técnicos donde sea relevante.]

## Decisión

[Declara la decisión clara y concisamente. Usa voz activa:
"Usaremos X" no "Se debería considerar X."]

## Alternativas consideradas

### [Alternativa 1]
- Pros: ...
- Contras: ...
- Por qué se rechazó: ...

### [Alternativa 2]
- Pros: ...
- Contras: ...
- Por qué se rechazó: ...

## Consecuencias

### Positivas
- [Qué se vuelve más fácil o mejor]

### Negativas
- [Qué se vuelve más difícil o peor]

### Riesgos
- [Qué podría salir mal]

## Decisiones relacionadas

- [Enlaces a ADRs relacionados]

Desglose de cada sección

Estado rastrea el ciclo de vida de una decisión. El flujo típico es: Propuesto -> Aceptado. Si las circunstancias cambian, un ADR se vuelve Deprecado o Reemplazado por un ADR más nuevo. Importante: nunca debes eliminar ADRs -- incluso las decisiones rechazadas son valiosas porque evitan que futuros equipos reconsideren opciones que ya fueron evaluadas.

Fecha establece cuándo se tomó la decisión. Esto proporciona contexto temporal: "Elegimos esta tecnología en 2024 cuando nuestra escala era X. Ahora que nuestra escala es 10X, deberíamos revisitarla."

Contexto es la sección más importante. Una sección de contexto bien escrita da a los futuros lectores suficiente información para entender por qué esta decisión tenía sentido en su momento, incluso si las circunstancias han cambiado desde entonces. Incluye números específicos ("procesamos 50K pedidos por día"), restricciones ("debe cumplir con PCI-DSS") y factores del equipo ("tres ingenieros tienen experiencia con PostgreSQL, ninguno con MongoDB").

Decisión debe ser inequívoca. "Usaremos PostgreSQL 16 como el almacén de datos principal para el servicio de pedidos" es bueno. "Probablemente deberíamos considerar una base de datos relacional" no es un ADR -- es una sugerencia.

Alternativas consideradas es la sección que ahorra más tiempo a largo plazo. Cuando un nuevo ingeniero pregunta "¿por qué no usamos MongoDB?", la respuesta está justo aquí. Cuando el equipo revisita la decisión un año después, pueden ver qué se evaluó y por qué se rechazó. Sin esta sección, los equipos relitigan los mismos debates interminablemente.

Consecuencias trata sobre honestidad intelectual. Toda decisión tiene trade-offs. Reconocer las desventajas genera confianza y ayuda a futuros equipos a entender cuándo las circunstancias podrían justificar revisitar la decisión.

Un ejemplo completo de ADR

Aquí tienes un ADR realista que demuestra la plantilla en la práctica:

# ADR-0023: Usar Apache Kafka para comunicación inter-servicios

## Estado

Aceptado

## Fecha

2025-11-15

## Contexto

Nuestra plataforma ha crecido de 3 microservicios a 12 en el último año.
Los servicios actualmente se comunican sincrónicamente mediante llamadas
HTTP REST. Esto crea varios problemas:

- Fallas en cascada: cuando el servicio de inventario está caído, el
  servicio de pedidos no puede procesar pedidos, aunque las verificaciones
  de inventario podrían ser eventuales.
- Acoplamiento fuerte: los servicios necesitan conocer los contratos de
  API y endpoints de los demás.
- Cuellos de botella de rendimiento: algunas operaciones desencadenan
  cadenas de 4-5 llamadas sincrónicas, agregando latencia.

Procesamos aproximadamente 100K eventos por día. Esperamos que esto
crezca a 500K en 12 meses. El equipo tiene 8 ingenieros backend,
2 de los cuales tienen experiencia previa con Kafka.

## Decisión

Adoptaremos Apache Kafka como mecanismo principal para la comunicación
asincrónica inter-servicios. HTTP sincrónico permanecerá para patrones
de request/response donde el llamador necesita un resultado inmediato
(ej., verificaciones de autenticación).

Usaremos Confluent Cloud como proveedor gestionado de Kafka para
minimizar la sobrecarga operativa.

## Alternativas consideradas

### RabbitMQ
- Pros: Más simple de operar, menor curva de aprendizaje, soporta
  múltiples patrones de mensajería (pub/sub, punto a punto, routing).
- Contras: Menos adecuado para patrones de event sourcing que
  planeamos adoptar. Capacidades de replay/rewind más débiles.
  El impulso de la comunidad se ha movido hacia Kafka para
  arquitecturas event-driven.
- Por qué se rechazó: Anticipamos la necesidad de event replay
  para auditoría y debugging. La arquitectura basada en log de
  Kafka es más adecuada.

### AWS SQS + SNS
- Pros: Completamente gestionado, sin infraestructura que mantener,
  integración estrecha con AWS.
- Contras: Vendor lock-in con AWS. Garantías limitadas de ordenamiento
  de mensajes. Sin procesamiento de streams integrado (necesitaríamos
  Kinesis o Lambda). Mayor costo por mensaje en nuestro volumen
  proyectado.
- Por qué se rechazó: Queremos evitar profundizar el lock-in con
  AWS, y necesitamos entrega ordenada de mensajes para eventos
  financieros.

### Mantener HTTP sincrónico (con circuit breakers)
- Pros: Sin nueva infraestructura. El equipo ya lo conoce. Los
  circuit breakers abordan las fallas en cascada.
- Contras: No resuelve el acoplamiento fuerte. La latencia sigue
  acumulándose en las cadenas de llamadas. Los circuit breakers
  son un parche, no una solución al problema fundamental de
  acoplamiento.
- Por qué se rechazó: Aborda síntomas, no la causa raíz.

## Consecuencias

### Positivas
- Los servicios se desacoplan: los productores no necesitan
  conocer a los consumidores.
- Fallas en cascada eliminadas para flujos asíncronos.
- Event replay habilita capacidades poderosas de debugging
  y auditoría.
- Base para patrones de event sourcing en futuros servicios.

### Negativas
- La complejidad operativa aumenta (cluster Kafka, schema
  registry, gestión de consumer groups). Mitigado usando
  Confluent Cloud.
- El equipo necesita capacitación en conceptos y patrones
  de Kafka.
- La consistencia eventual reemplaza la consistencia fuerte
  para flujos asíncronos. Algunos flujos necesitan rediseño.
- Debuggear flujos asíncronos distribuidos es más difícil que
  tracear llamadas HTTP sincrónicas. Necesitaremos tracing
  distribuido (ver ADR-0024).

### Riesgos
- Si el volumen de mensajes excede los niveles de precios de
  Confluent Cloud, los costos podrían aumentar significativamente.
  Monitorear y establecer alertas.
- La evolución de schemas entre servicios requiere disciplina.
  Planear adoptar Avro con schema registry.

## Decisiones relacionadas

- ADR-0024: Adoptar OpenTelemetry para tracing distribuido
- ADR-0018: Contratos de comunicación de servicios
  (reemplazado por este ADR)

Este ADR tiene unas 400 palabras. Tomó quizás 20 minutos escribirlo. Ahorrará horas de reuniones en los próximos años.

Cuándo escribir un ADR

No toda elección técnica necesita un ADR. Elegir entre dos bibliotecas de JSON no lo amerita. Pero algunas decisiones absolutamente sí.

Escribe un ADR cuando:

• La decisión afecta la estructura del sistema. Cualquier cosa que cambie cómo se comunican los servicios, dónde viven los datos o cómo se organizan los componentes.
• La decisión es costosa de revertir. Elegir una base de datos, un sistema de mensajería o una plataforma de despliegue. Si deshacer esta decisión toma más de un sprint, documenta por qué la tomaste.
• Existen múltiples opciones viables. Si la elección es obvia, no se necesita ADR. Si debatiste entre tres opciones, captura el razonamiento.
• La decisión cruza límites de equipos. Cualquier elección arquitectural que afecte a otros equipos debería documentarse para que entiendan la justificación.
• Tu yo futuro podría cuestionar la elección. Si hay alguna posibilidad de que alguien (incluyendo tu yo futuro) pregunte "¿por qué hicimos esto?", escríbelo ahora.

Omite el ADR cuando:

• La elección sigue un estándar establecido del equipo (ej., "siempre usamos Go para servicios backend" no necesita un nuevo ADR para cada servicio)
• La decisión es trivialmente reversible (renombrar una variable, elegir un formateador de código)
• La decisión es puramente cosmética (estilo de código, convenciones de nombrado -- estas pertenecen a una guía de estilo)

Ciclo de vida y gobernanza de ADRs

El ciclo de vida

Los ADRs tienen un ciclo de vida natural:

1. Borrador/Propuesto: Alguien identifica una decisión que necesita tomarse y escribe un borrador de ADR. El equipo discute.
2. Aceptado: El equipo acuerda la decisión. El estado del ADR cambia a Aceptado.
3. Activo: La decisión está vigente. El ADR sirve como documentación de referencia.
4. Reemplazado: Una nueva decisión reemplaza esta. El ADR antiguo obtiene un estado "Reemplazado por ADR-XXXX". El nuevo ADR referencia al antiguo.
5. Deprecado: La decisión ya no es relevante (quizás el sistema al que aplicaba fue dado de baja).

Importante: nunca elimines ADRs. Incluso los deprecados o reemplazados son valiosos. Forman una línea de tiempo de la evolución arquitectural.

Numeración

Usa números secuenciales: ADR-0001, ADR-0002, etc. El número proporciona ordenamiento cronológico y hace que los ADRs sean fáciles de referenciar en conversaciones: "como se decidió en ADR-42."

Algunos equipos usan numeración basada en fechas (ADR-2026-03-27-kafka) pero los números secuenciales son más simples y más ampliamente usados.

Cadencia de revisión

Establece un recordatorio trimestral para revisar tus ADRs:

• ¿Hay decisiones aceptadas que ya no son válidas?
• ¿Han cambiado restricciones que invaliden suposiciones?
• ¿Hay decisiones que el equipo tomó informalmente que deberían capturarse?

Esta revisión previene la obsolescencia de los ADRs y mantiene la colección actualizada.

Dónde almacenar ADRs

Los enfoques más comunes, en orden de recomendación:

En el repositorio de código

Almacena los ADRs en docs/adr/ o docs/decisions/ dentro de tu repositorio. Este es el enfoque más popular y con buena razón:

• Los ADRs están versionados junto al código que describen
• Aparecen en pull requests y code reviews
• No pueden quedar huérfanos en un wiki que nadie visita
• Son descubribles vía grep o búsqueda

Convención: un archivo markdown por ADR, nombrado con el número y un slug:

docs/adr/
  0001-use-postgresql-for-orders.md
  0002-adopt-event-driven-architecture.md
  0003-monorepo-for-frontend.md

En una herramienta dedicada de arquitectura

Herramientas como Archyl proporcionan gestión integrada de ADRs con capacidades adicionales:

• Vincular ADRs directamente a elementos del modelo C4 (containers, componentes, relaciones)
• Buscar y filtrar ADRs a través de todos los proyectos
• Rastrear el estado y ciclo de vida de los ADRs
• Conectar ADRs a reglas de conformidad que apliquen la decisión

La ventaja clave de una herramienta de arquitectura es el contexto. Cuando un desarrollador mira el container de PostgreSQL en un diagrama C4, puede hacer clic para ver el ADR que explica por qué se eligió PostgreSQL. La decisión y la arquitectura están conectadas, no aisladas.

En un wiki (no recomendado)

Los wikis (Confluence, Notion, etc.) son donde los ADRs van a ser olvidados. Están desconectados del código, son difíciles de descubrir y raramente se mantienen. Si debes usar un wiki, al menos haz referencia cruzada de los ADRs desde el repositorio de código.

Integrar ADRs en tu flujo de trabajo

Haz que los ADRs sean parte de los pull requests

Para cambios arquitecturales significativos, requiere un ADR como parte del pull request. Agrega una sección a tu plantilla de PR:

## Impacto arquitectural

- [ ] Sin cambios arquitecturales
- [ ] ADR creado/actualizado: [enlace]

Esto normaliza la creación de ADRs y asegura que las decisiones se documenten cuando se toman, no semanas después cuando el contexto se ha desvanecido.

Usa ADRs en revisiones de arquitectura

Durante revisiones de arquitectura o discusiones de diseño, referencia los ADRs existentes. "Antes de rediseñar esto, veamos qué dice ADR-15 sobre por qué elegimos este enfoque." Esto da visibilidad a los ADRs y refuerza el hábito de documentar decisiones.

Conecta ADRs a diagramas de arquitectura

Aquí es donde los ADRs se vuelven verdaderamente poderosos. Cuando un ADR está vinculado a un elemento específico en tu modelo C4, crea un grafo de conocimiento navegable:

• Haz clic en el container de Kafka en tu diagrama de Containers -> ve ADR-0023 explicando por qué se eligió Kafka
• Haz clic en la base de datos PostgreSQL -> ve ADR-0001 explicando la selección de base de datos
• Haz clic en el API Gateway -> ve ADR-0012 explicando por qué se eligió Kong sobre routing personalizado

En Archyl, puedes vincular ADRs a cualquier elemento C4 -- sistemas, containers, componentes o relaciones. Esta conexión significa que las decisiones arquitecturales no son documentos flotantes; están ancladas a las partes específicas de la arquitectura que afectan.

Automatiza lo que puedas

Varias herramientas pueden reducir la fricción de la gestión de ADRs:

• adr-tools (de Nat Pryce): Una herramienta de línea de comandos para crear y gestionar ADRs en un repositorio. Ejecuta adr new "Use Kafka for messaging" para generar un nuevo ADR desde una plantilla.
• Log4brains: Genera un sitio web buscable y navegable desde tus archivos markdown de ADR.
• Archyl: Gestiona ADRs con vinculación a elementos C4, rastreo de estado y búsqueda entre proyectos.

Prácticas avanzadas de ADR

ADRs ligeros (LADRs)

Algunos equipos encuentran que incluso la plantilla estándar es demasiado pesada. Un ADR ligero son solo tres frases:

En el contexto de [situación],
decidimos [decisión],
para lograr [objetivo],
aceptando [trade-off].

Ejemplo:

En el contexto de necesitar comunicación inter-servicios que tolere
tiempos de inactividad, decidimos usar Apache Kafka via Confluent Cloud,
para lograr desacoplamiento de servicios y capacidad de event replay,
aceptando mayor complejidad operativa y consistencia eventual.

Este formato funciona bien para decisiones lo suficientemente importantes como para documentar pero que no ameritan un ADR completo.

Decision logs

Un decision log es un documento único que lista todos los ADRs en orden cronológico con resúmenes de una línea. Sirve como índice:

Esto da una vista rápida de todas las decisiones sin abrir archivos individuales de ADR.

ADRs para decisiones no técnicas

Los ADRs no se limitan a elecciones de tecnología. Los equipos los usan para:

• Decisiones de proceso: "Haremos pair programming para código crítico de seguridad"
• Decisiones organizacionales: "El equipo de plataforma es dueño de todos los containers de infraestructura"
• Decisiones de proveedor: "Usaremos Datadog para monitoreo en lugar de construir internamente"

Si la decisión es significativa y reversible-pero-costosa, un ADR es apropiado independientemente de si es estrictamente "arquitectural."

Errores comunes

Escribir ADRs después del hecho

El mejor momento para escribir un ADR es durante el proceso de toma de decisiones. Escribir uno semanas después significa que has olvidado los matices, las alternativas que consideraste y las restricciones que existían. Haz que escribir ADRs sea parte del proceso de decisión, no una tarea pendiente.

Hacerlos demasiado largos

Si tu ADR excede una página, probablemente estás documentando múltiples decisiones (divídelas) o incluyendo detalles de implementación (guárdalos para un documento de diseño). La disciplina de la brevedad obliga a la claridad.

No documentar alternativas rechazadas

La sección de "Alternativas consideradas" es la parte más valiosa de un ADR a largo plazo. Sin ella, futuros ingenieros propondrán las mismas alternativas, sin saber que ya fueron evaluadas y rechazadas. Siempre explica lo que no elegiste y por qué.

Abandonar la práctica

Uno o dos ADRs no proporcionan mucho valor. Cincuenta ADRs acumulados durante dos años se convierten en una base de conocimiento invaluable. La tentación de dejar de escribir ADRs cuando las cosas se ponen intensas es fuerte. Resístela. Los 15 minutos que pasas escribiendo un ADR ahorrarán horas de reuniones después.

No revisar ni actualizar el estado

Una colección de ADRs donde la mitad de las decisiones están desactualizadas es engañosa. Programa revisiones trimestrales. Marca las decisiones reemplazadas. Mantén la colección confiable.

Por qué los ADRs importan más en la era de la IA

A medida que los agentes de IA se convierten en participantes activos del desarrollo de software, los ADRs adquieren nueva importancia. Un agente de IA escribiendo código puede leer tus ADRs y entender:

• Por qué se eligieron ciertas tecnologías (y deberían seguir usándose)
• Qué alternativas fueron rechazadas (y no deberían re-proponerse)
• Qué restricciones existen (requisitos de cumplimiento, umbrales de rendimiento)
• Qué trade-offs se aceptaron (consistencia eventual, dependencias de proveedores)

A través del servidor MCP de Archyl, agentes de IA como Claude Code pueden acceder a tus ADRs antes de hacer sugerencias arquitecturales. En lugar de proponer MongoDB para un servicio donde ya documentaste por qué se eligió PostgreSQL, el agente respeta la decisión existente -- o señala explícitamente cuándo piensa que la decisión debería revisitarse.

Esto convierte a los ADRs no solo en documentación para humanos, sino en guardarraíles para la IA.

Empezar hoy

Si tu equipo aún no usa ADRs, empieza con estos tres pasos:

1. Elige una decisión reciente. Piensa en una elección arquitectural que tu equipo debatió en el último mes. Escribe un ADR usando la plantilla anterior. Debería tomar 15-20 minutos.

2. Almacénalo en tu repo. Crea un directorio docs/adr/ y agrega el archivo. Inclúyelo en tu próximo pull request para que el equipo lo vea.

3. Hazlo un hábito. Agrega un checkbox de "Impacto arquitectural" a tu plantilla de PR. Discute los ADRs en tu próxima reunión de arquitectura. La práctica cobra impulso una vez que el equipo ve el valor.

La próxima vez que alguien pregunte "¿por qué lo hicimos de esa manera?" -- y lo harán -- tendrás la respuesta.

Explora más sobre documentación de arquitectura: ¿Qué es el modelo C4? | ADR Best Practices | Descubrimiento de arquitectura asistido por IA. O prueba Archyl gratis para gestionar ADRs vinculados directamente a tu modelo C4.