Introducción a ADR (Architecture Decision Record) — El método mínimo para dejar constancia de «por qué se eligió este diseño» en desarrollos de pequeña escala

«¿Por qué aquí se usa un intercambio de archivos? ¿No sería más normal consultar la base de datos directamente?» — Casi cualquier desarrollador que abre el código de un sistema heredado termina topándose con este tipo de duda. Y en la mayoría de los casos, la persona que conocía la respuesta ya no está en el proyecto.

Seguramente hubo una razón. Quizá no se concedió permiso para conectarse directamente a la base de datos del sistema externo, o quizá, dado el plazo de entrega de aquel momento, esa fue la única forma segura de hacerlo. Pero si esa razón no queda registrada, quien releva el proyecto se queda paralizado ante «código que no sabe si puede tocar», o peor aún, termina rompiendo la razón junto con el código.

En este blog ya hemos explicado cómo abordar el desarrollo por encargo en «Lo que conviene organizar antes de encargar el desarrollo externo de una aplicación Windows», y el marco contractual en «Cómo distinguir entre cuasi-mandato y contrato de obra según el “Contrato Modelo” del IPA». Este artículo va un paso más allá: trata de «cómo hacer que lo construido dure varios años» una vez terminado. Explicamos ADR (Architecture Decision Record), un mecanismo para dejar constancia de las razones de las decisiones de diseño con el mínimo esfuerzo, pensado para desarrollo por encargo y desarrollo interno de pequeña escala.

1. La conclusión primero

• Antes que un documento de diseño exhaustivo, hay que dejar constancia de las decisiones. Lo que realmente complica el mantenimiento no es no saber «qué hace» el sistema, sino no saber «por qué se hizo así».
• Un ADR es un formato ligero en el que cada decisión se registra en un único archivo con la estructura fija «título/estado/contexto/decisión/resultado». Lo propuso Michael Nygard en 2011, y la regla es limitarse a una o dos páginas por decisión.¹
• Se guarda en el mismo repositorio que el código (por ejemplo, docs/adr/0001-title.md). En lugar de un wiki o una carpeta compartida, se versiona junto con el código y se revisa junto con el código.¹²
• Las decisiones no se sobrescriben. Cuando cambia el rumbo, se añade un ADR nuevo y el ADR antiguo pasa a estado Superseded (reemplazado), con una referencia cruzada entre ambos. Un ADR es un registro de solo añadido (append-only).²
• No se escribe de todo: solo las decisiones «difíciles de cambiar después», «con varias opciones válidas posibles» o «en las que una restricción fue determinante». Las convenciones de nombres o la configuración del formateador quedan fuera.²
• Por experiencia propia, la condición para mantener el hábito es limitar cada ADR a entre 15 y 30 minutos de redacción. Una plantilla demasiado elaborada se abandona a los tres primeros casos.
• En el desarrollo por encargo, el ADR se convierte en un entregable que se puede compartir con el cliente. Sirve tal cual como material de explicación en la aceptación del trabajo y como documento de traspaso cuando cambia el responsable o el proveedor.

Las notas al pie de este artículo remiten a tres fuentes primarias: el texto original de Michael Nygard que presentó el formato de ADR¹; la guía del Well-Architected Framework de Microsoft Learn, que sistematiza los principios de uso (registro de solo añadido, acotar el alcance, mantenerlo bajo control de versiones)²; y adr.github.io³, el sitio comunitario que recopila plantillas y herramientas. De aquí en adelante, cada número de nota al pie remite a una de estas tres.

2. El problema de «no saber por qué es así»

2.1 El código dice el qué, pero no el porqué

Leyendo el código se puede entender «qué hace» (si se le dedica tiempo). Lo que no se entiende son los «porqués» como los siguientes:

• Por qué la base de datos es SQLite y no SQL Server
• Por qué la integración con otros sistemas se hace mediante archivos CSV y no una API web
• Por qué solo este informe se imprime abriendo Excel
• Por qué se sigue usando .NET Framework y no se ha migrado al .NET actual

Detrás de estas decisiones siempre hay razones que están fuera del código: el presupuesto y el plazo de entrega de la época, restricciones del cliente, la compatibilidad con activos ya existentes. Son demasiado extensas para un comentario y «el proceso que llevó a la decisión» no encaja bien en un documento de diseño. Como resultado, la razón no queda registrada en ninguna parte.

2.2 Los lugares donde se guardan las decisiones desaparecen en pocos años

Entonces, ¿dónde está hoy la razón de cada decisión de diseño? Comparemos los lugares habituales.

La guía de arquitectura de Microsoft también señala con claridad que las decisiones no registradas se olvidan, lo que provoca que se repitan los mismos debates y que se introduzcan cambios contrarios a la intención original.²

2.3 En el desarrollo por encargo, el fin del contrato es el fin de la memoria

En el desarrollo interno, «preguntarle a esa persona» sigue funcionando durante un tiempo, pero en el desarrollo por encargo, además de traslados y bajas del personal, existe el cambio de proveedor. En el momento en que el proveedor que desarrolló el sistema y el que lo mantiene son distintos, el «porqué» que solo existía de forma verbal o en el chat se pierde por completo.

Desde el punto de vista contractual, también es habitual que el desarrollo y el mantenimiento sean contratos y fases distintas (tratamos esta estructura en el «artículo sobre el “Contrato Modelo” del IPA»). Y como explicamos en «La forma correcta de trabajar bajo un contrato de cuasi-mandato», precisamente porque en el cuasi-mandato el proveedor avanza el trabajo de forma autónoma, poder mostrar al cliente qué se decidió y cómo es lo que respalda la confianza. El ADR resulta útil en ambos frentes.

3. Qué es un ADR

3.1 La propuesta de Nygard: cinco elementos y un límite de dos páginas

El ADR es un formato que Michael Nygard propuso en 2011 en su artículo de blog «Documenting Architecture Decisions».¹ Sus puntos clave son los siguientes:

• Un archivo por decisión. Se numera de forma correlativa y los números nunca se reutilizan
• El archivo usa un formato ligero como Markdown y se guarda dentro del repositorio del proyecto
• Se compone de cinco elementos: título / estado / contexto / decisión / resultado (Consequences)
• El estado avanza de propuesto (proposed) a aprobado (accepted); si se revierte, pasa a obsoleto (deprecated) o reemplazado (superseded). El registro antiguo nunca se borra
• Como máximo, una o dos páginas en total. Se redacta en un texto autocontenido que un futuro desarrollador pueda leer como si fuera una conversación

Si se dibuja solo el movimiento de los estados, se ve con claridad que un ADR es «un registro de solo añadido».

stateDiagram-v2
    [*] --> proposed: Se redacta el ADR
    proposed --> accepted: Se aprueba en la revisión
    accepted --> deprecated: La decisión deja de ser necesaria
    accepted --> superseded: Un nuevo ADR la reemplaza
    deprecated --> [*]
    superseded --> [*]

En cualquiera de las flechas, lo único que se reescribe es la línea de estado. El texto de contexto y de decisión no se toca. Al pasar de accepted a superseded, lo único que se añade al ADR antiguo es una línea de referencia al ADR nuevo. Como el estado anterior no se sobrescribe y queda conservado, después se puede rastrear «cuándo y por qué cambió el rumbo».

Aunque lleva la palabra «arquitectura», no es una técnica exclusiva de sistemas de gran escala. Al contrario: es precisamente en el desarrollo de pequeña escala sin arquitecto dedicado ni responsable de documentación donde mejor funciona este «mínimo formato fijo». Cabe señalar que las plantillas y herramientas de ADR están sistematizadas en un sitio comunitario (adr.github.io), al que se puede recurrir como punto de partida para la idea de «registrar las decisiones arquitectónicamente relevantes junto con su fundamento y sus trade-offs».³

3.2 Plantilla en Markdown

Esta es la plantilla mínima que uso en proyectos pequeños, calcada del formato de Nygard.

# ADR-NNNN: (la decisión, en una frase breve)

## Estado

Propuesto | Aprobado | Obsoleto | Reemplazado (→ ADR-MMMM)

## Contexto

Por qué se necesitó esta decisión. Se describen las premisas técnicas
y de negocio, las restricciones (presupuesto, plazo, activos existentes,
entorno del cliente) y las opciones consideradas, de forma que lo entienda
también un lector que no conoció la situación de aquel momento.

## Decisión

Se afirma en voz activa, con «se hará tal cosa». De una a tres frases.

## Resultado

Se anotan tanto lo que mejora como lo que empeora con esta decisión
(el trade-off). Si existe alguna condición que en el futuro deba motivar
revisar esta decisión, se anota también.

En el campo de estado basta con anotar el estado, pero se recomienda añadir la fecha en que cambió, como en Aprobado (2026-07-17). Los ejemplos reales del capítulo 7 también usan este formato. Puesto que se trata de un registro de solo añadido, «cuándo se aprobó» y «cuándo se reemplazó» son datos tan importantes como el propio texto. Al marcar un ADR como reemplazado, se anota en una sola línea la fecha y el reemplazo, como en Reemplazado (2026-08-20) — lo reemplaza ADR-0007. Elija uno de los dos formatos y manténgalo uniforme dentro del proyecto.

El punto clave es anotar también los aspectos negativos en «Resultado». Una decisión sin trade-offs apenas vale la pena registrarla. La guía de Microsoft también insiste en no ocultar las consecuencias de una decisión, ni de forma deliberada ni accidental, y en que un registro sin fundamento pierde valor con el tiempo.²

4. Qué escribir en un ADR y qué no

La causa principal de que un ADR no se mantenga en el tiempo es «intentar escribirlo todo». La guía de Microsoft indica que solo deben registrarse las decisiones que afectan a la estructura del sistema o a atributos de calidad importantes, y que son difíciles de revertir.² Si se traduce esto a decisiones del día a día, se obtiene la siguiente tabla.

Cuando haya duda, el criterio es uno solo: «¿la persona que vea este código dentro de un año (incluido usted mismo) va a querer preguntar “por qué”?». Si la respuesta es sí, se escribe; si es evidente con solo mirar el código o la configuración, no.

Otra trampa habitual es pensar el nivel de detalle en función del «tipo de documento». Definir de antemano el reparto de roles como en la siguiente tabla evita dudas.

5. Uso en desarrollo por encargo a pequeña escala

5.1 Directorio y nombres de archivo

Se crea docs/adr/ en la raíz del repositorio y se colocan los archivos con número correlativo más un slug corto. Un slug es una cadena que resume el contenido usando solo minúsculas en inglés y guiones (algo como use-sqlite-for-local-storage). Es una convención para que, al usarse como parte del nombre de archivo o de una URL, se evite espacios, japonés o símbolos y quede en una forma fácil de procesar de manera mecánica.

docs/
  adr/
    0001-record-architecture-decisions.md
    0002-use-sqlite-for-local-storage.md
    0003-excel-report-via-com-automation.md
    0007-excel-report-via-openxml-library.md

En este ejemplo faltan 0004 a 0006 porque esos números se usaron en otras decisiones (por ejemplo, el método de autenticación o el diseño del registro de logs). 0007 es la decisión que reemplaza al método de 0003, pero no se comprimen los números ni se reutiliza 0003. La numeración correlativa simplemente aumenta en el orden en que se tomaron las decisiones, y es normal que haya huecos.

Es habitual que el primer ADR sea el que registra «la decisión de usar ADR» en sí misma. Así, quien releva el proyecto entiende las reglas de uso con solo mirar docs/adr/.

5.2 Cuándo escribirlo y quién lo revisa

• El momento de escribirlo es «justo después de decidir». Como cierre de la discusión de diseño, la conclusión de la reunión se convierte en ADR ese mismo día. Como se explica más adelante, escribirlo todo junto después es un patrón de fracaso.
• El ADR se incluye en la revisión de código. Basta con comprobar si la solicitud de extracción (pull request) de un cambio que afecta al método incluye la adición o actualización de un ADR. No hace falta una reunión de aprobación exclusiva para ADR; integrarlo en la revisión habitual es la solución realista para un equipo pequeño. Mantener el ADR bajo control de versiones también es algo que recomienda la guía de Microsoft.²
• Cuando se revierte una decisión, se escribe un ADR nuevo y se cambia el estado del ADR antiguo a Superseded, con referencia cruzada entre ambos. El cuerpo del texto no se modifica. No editar los registros ya aprobados y conservar el historial mediante una cadena de reemplazos: eso es tratar el ADR como «un registro de solo añadido».²

5.3 El ADR como entregable compartido con el cliente

En el desarrollo por encargo, se recomienda compartir el ADR con el cliente como parte de los entregables. Esto aporta tres beneficios.

1. Sirve como material para la aceptación del trabajo y la explicación. En lugar de explicar verbalmente «por qué esta estructura», basta con mostrar el ADR. En las decisiones en las que una restricción (presupuesto, plazo, entorno) fue determinante, el propio cliente es parte interesada, así que tener el registro evita desajustes de percepción más adelante.
2. Es un seguro frente a un cambio de proveedor. Desde la perspectiva del cliente, el coste y el riesgo del traspaso cambian mucho según exista o no un «historial de decisiones» que entregar al siguiente proveedor. Sobre cómo organizar esto antes de encargar el trabajo escribimos en la «guía de desarrollo por encargo de aplicaciones Windows», pero a la hora de decidir en el contrato qué documentación se recibirá tras la entrega, el ADR está entre las opciones con mejor relación coste-beneficio.
3. Encaja bien con los informes del cuasi-mandato. El contrato de cuasi-mandato exige informar sobre la ejecución del trabajo, y el ADR se puede usar tal cual como informe de la fase de diseño.

5.4 El tiempo real que requiere

Por experiencia propia, escribir un ADR siguiendo la plantilla lleva entre 15 y 30 minutos. En un proyecto pequeño, la frecuencia de decisiones es de unas pocas al mes, así que con una inversión de una o dos horas mensuales queda registrado todo el «porqué». Comparado con el tiempo que se pierde años después en investigar, reconsiderar y hacer el traspaso, es difícil encontrar un proyecto donde esto no compense.

6. Errores habituales

En particular, «escribirlo todo junto después» es una trampa habitual al introducir ADR en un sistema ya existente a mitad de camino. Lo realista no es intentar reconstruir todas las decisiones pasadas, sino escribir retroactivamente solo unas pocas de las decisiones principales que se conocen, y a partir de ahí acumular desde las decisiones de hoy en adelante. Incluso en un sistema ya existente (brownfield), si hay decisiones pasadas que se conocen bien, vale la pena registrarlas de forma retroactiva.²

7. Ejemplos reales de ADR

Mostramos dos ADR completos con temas habituales en aplicaciones de negocio para Windows de pequeña escala (el contenido es un ejemplo generalizado).

El primero es una decisión clásica de elección técnica: la base de datos.

# ADR-0002: Los datos de negocio se guardan en SQLite

## Estado

Aprobado (2026-07-17)

## Contexto

El sistema es una aplicación de escritorio de gestión de inventario de un único centro. Hay entre 2 y 3 usuarios,
pero en la práctica se instala en 1 PC del responsable principal de la oficina y se usa por turnos (un único uso
simultáneo). El cliente no cuenta con personal capaz de operar un servidor de base de datos, ni con presupuesto
para adquirir un equipo servidor. El volumen de datos se estima en unos pocos cientos de MB incluso tras 10 años
de operación. Se consideraron como opciones SQL Server Express, SQLite y un archivo de Access (.accdb). Se
descartó SQL Server Express porque el cliente no cuenta con la capacidad de construir el servidor ni de verificar
de forma continua su funcionamiento tras cada actualización de Windows. Se descartó Access por el riesgo de
corrupción en actualizaciones simultáneas y por su migrabilidad futura.

## Decisión

Se adopta SQLite para el almacenamiento de datos. El archivo de base de datos no se coloca en una carpeta compartida,
sino de forma local en el PC del responsable principal. La copia de seguridad se genera a diario mediante una
instantánea con VACUUM INTO y se guarda en el NAS (no se permite copiar el archivo en bruto mientras está en
funcionamiento, ya que las actualizaciones pendientes en el archivo WAL o las condiciones de carrera en la escritura producirían una copia de seguridad corrupta).

## Resultado

- Punto positivo: no hace falta construir ni mantener un servidor de base de datos. La copia de seguridad también se resuelve con una sola sentencia SQL
- Punto positivo: el runtime se puede distribuir junto con la aplicación, lo que simplifica la instalación
- Punto negativo: la escritura queda bloqueada a nivel de base de datos, por lo que no escala a varios centros ni a muchos usuarios
- Punto negativo: si en el futuro se migra a una base de datos en servidor, hará falta migrar los datos y modificar la capa de conexión
- En el momento en que se necesite uso simultáneo desde varios PC, esta decisión debe revisarse (en tal caso, pasaría a una base de datos en servidor o a un esquema vía API)

Solo vamos a aclarar los términos propios de SQLite que aparecen en este ejemplo. VACUUM INTO es una sentencia SQL que vuelca el contenido lógico de una base de datos en funcionamiento a otro archivo tal cual, y la propia documentación oficial de SQLite lo describe como «una alternativa a la API de copia de seguridad para crear una copia de una base de datos en funcionamiento».⁴ WAL (Write-Ahead Logging) es un método de journaling en el que las actualizaciones se escriben primero en un archivo -wal independiente antes de aplicarse al archivo principal. Con este método, si mientras el sistema está en funcionamiento se copia solo el archivo .db principal mediante una copia de archivo del sistema operativo, las actualizaciones aún no aplicadas que están en el archivo -wal quedan fuera, y el resultado es una copia de seguridad a medias. Que la «Decisión» de ADR-0002 llegue a especificar incluso el método de copia de seguridad se debe a que esta trampa es inseparable de la propia decisión.

El segundo ejemplo es un caso en el que se revierte una decisión ya tomada. Fíjese también en cómo se usa Superseded.

# ADR-0007: La salida a Excel de los informes se genera con una librería, no con integración COM

## Estado

Aprobado (2026-07-17) — reemplaza a ADR-0003 (adopción de automatización COM)

## Contexto

Existe el requisito de generar como archivo Excel el albarán de entrega y el resumen
mensual. Al principio se implementó con automatización COM de Excel, tal como indicaba
ADR-0003, pero en el proceso por lotes nocturno que se ejecuta sin supervisión se
repitió el problema de que el proceso de Excel quedaba residente y detenía el
procesamiento, y además la necesidad de licencia de Office en el PC de ejecución se
convertía en un problema cada vez que se renovaba el equipo. Se consideraron como
opciones continuar con la integración COM (añadiendo supervisión de procesos), cambiar
a una librería que genere directamente el formato Open XML, o convertir el informe a
PDF (un cambio de especificación). Convertirlo a PDF no era viable porque la contraparte comercial da por hecho que podrá seguir escribiendo sobre el Excel.

## Decisión

El informe pasa a generarse directamente en formato .xlsx mediante una librería.
No depende de Excel en sí. El formato se mantiene como una plantilla .xlsx incluida
en el repositorio, y la generación se realiza rellenando celdas.

## Resultado

- Punto positivo: el entorno de ejecución ya no necesita Excel, y la ejecución sin supervisión se vuelve estable
- Punto positivo: el problema de procesos residentes desaparece de forma estructural
- Punto negativo: al no poder usar todas las funciones de Excel, hay que simplificar parte del formato de los informes existentes
- Punto negativo: convertir los informes existentes en plantillas exige esfuerzo de modificación
- ADR-0003 pasa a Superseded, con una referencia a este ADR

Con solo leer estos dos ejemplos, se puede responder a las preguntas que siempre surgen en un traspaso, como «¿por qué este sistema no tiene una base de datos en servidor?» o «¿por qué el código del informe tiene rastros de haber abierto Excel?». Entre los dos suman apenas unos 1.500 caracteres y no llevan ni una hora escribirlos.

8. Resumen

• Lo que se pierde y complica el mantenimiento y el traspaso no es el qué, sino el porqué. Las decisiones no registradas se olvidan y provocan que se repitan los debates y se introduzcan cambios contrarios a la intención original.²
• El ADR es un formato de registro ligero: una decisión = un archivo, cinco elementos, un máximo de una o dos páginas. Se puede usar tal cual, con el formato original de Nygard, en desarrollos de pequeña escala.¹
• Solo se escriben las decisiones «difíciles de cambiar», «con varias opciones posibles» o «en las que una restricción fue determinante». Las convenciones y el formato se dejan a la automatización y no entran en el ADR.²
• Se guarda en docs/adr/ y se revisa junto con la solicitud de extracción (pull request). Las decisiones no se sobrescriben: se reemplazan mediante Superseded, manteniendo el historial inmutable.¹²
• En el desarrollo por encargo, el ADR se convierte en un entregable valioso también para el cliente, como material de explicación en la aceptación del trabajo y como documento de traspaso ante un cambio de proveedor.
• Entre 15 y 30 minutos por ADR. Empiece escribiendo uno con la próxima decisión de diseño que tome; si se trata de un sistema ya existente, comience escribiendo de forma retroactiva solo unas pocas de las decisiones principales que ya conoce.

Artículos relacionados

• Cómo estructurar los contratos de desarrollo por encargo y mantenimiento — Cómo distinguir entre cuasi-mandato y contrato de obra según el «Contrato Modelo» del IPA
• La forma correcta de trabajar bajo un contrato de cuasi-mandato para evitar la subcontratación encubierta
• Lo que conviene organizar antes de encargar el desarrollo externo de una aplicación Windows
• Fundamentos para elaborar un manual en Word — Ejemplos deficientes y cómo mejorarlos

Áreas de consultoría relacionadas

KomuraSoft LLC ofrece apoyo para introducir el ADR dentro de la revisión de diseño, inventariar y documentar las decisiones de diseño de sistemas ya existentes, y construir una estructura de mantenimiento pensada de cara a un traspaso o un cambio de proveedor.

• Consultoría técnica y revisión de diseño
• Desarrollo de aplicaciones Windows
• Modificación y mantenimiento de software Windows existente
• Contacto

Referencias

Artículos relacionados

Artículos recientes con las mismas etiquetas para profundizar en temas cercanos.

Temas relacionados

Estas páginas sitúan el tema en un contexto más amplio de servicios y decisiones.

Preguntas frecuentes

Preguntas habituales en las consultas sobre el tema del artículo.

¿Qué es un ADR (Architecture Decision Record)?

Es un documento que registra una decisión relacionada con la estructura del software en un único archivo, con una estructura fija y breve de «título/estado/contexto/decisión/resultado». Es un formato ligero propuesto por Michael Nygard en 2011: cada decisión se limita a una o dos páginas y, por regla general, se hace commit en Markdown dentro del mismo repositorio que el código. A diferencia de un documento de diseño exhaustivo, está especializado en conservar «por qué se eligió esa opción» y «qué opciones se descartaron».

¿Qué se debe escribir en un ADR y qué no hace falta escribir?

Debe escribirse lo que sea difícil de cambiar después (la elección de la base de datos o del método de comunicación, el formato de una integración externa, etc.), las decisiones tomadas entre varias opciones válidas, y las decisiones en las que una restricción —presupuesto, plazo, activos existentes— fue determinante. Por el contrario, no hace falta escribir lo que se puede unificar de forma mecánica con herramientas o convenciones, como las reglas de nomenclatura o la configuración de un formateador, ni lo que es fácil de cambiar y basta con leer el código para entenderlo. Cuando haya duda, el criterio es «¿la persona que sea yo mismo dentro de un año va a querer preguntar por qué?».

Si en algún momento quiero cambiar una decisión, ¿puedo reescribir el ADR antiguo?

No se reescribe: se añade un ADR nuevo que lo reemplaza. El ADR antiguo cambia su estado a Superseded (reemplazado), se le añade una referencia al ADR nuevo, y su cuerpo se deja tal cual. La guía de Microsoft también recomienda tratar el ADR como un registro de solo añadido y no editar después los registros ya aprobados. De esta forma, el propio historial de «cuándo y por qué cambió el rumbo» se convierte en material de traspaso.

Si ya existe un documento de diseño, ¿no sobra el ADR?

Tienen roles distintos. El documento de diseño muestra «qué estructura tiene el sistema ahora» (el qué), pero normalmente no conserva «por qué se eligió esa estructura y qué se descartó» (el porqué). Además, un documento de diseño exhaustivo tiende a dejar de actualizarse y, años después, suele haberse desviado del código. El ADR solo requiere añadir unos pocos cientos de caracteres cada vez que hay una decisión, así que es más difícil que deje de actualizarse, y aunque el documento de diseño quede desactualizado, «el motivo de la decisión» sobrevive por sí solo. En proyectos de pequeña escala, lo realista es aligerar el documento de diseño detallado y combinarlo con el ADR.

Perfil del autor

Página de presentación del autor del artículo.

Go Komura

Representante de KomuraSoft LLC

Especializado en desarrollo de software para Windows, consultoría técnica e investigación de fallos, sobre todo en proyectos con sistemas existentes y errores difíciles de reproducir.