Copyrights. David Asensio Cañas ,
2026. Todos los derechos reservados.
En cualquier proyecto de desarrollo de software, la arquitectura no se diseña de una sola vez: se construye a base de decisiones. Algunas son técnicas, como elegir un patrón de segregación de responsabilidades por consultas de comandos (CQRS) o definir cómo se organizan las ramas del repositorio de código; otras son de proceso, como establecer la forma de revisar cambios o las herramientas que se adoptan en el equipo. Con el tiempo, esas decisiones se olvidan, se repiten discusiones ya cerradas o se cambian sin saber por qué se habían tomado en primer lugar.
Un registro de decisiones arquitectónicas (ADR, por sus siglas en inglés, y que en español puede traducirse como registro de decisiones de arquitectura) resuelve buena parte de ese problema. Se trata de un documento breve y acumulativo que captura el contexto, las alternativas evaluadas y las consecuencias de cada decisión significativa. En consultoría de software se ha convertido en una herramienta de primera línea porque permite preservar el conocimiento del equipo, reducir el tiempo dedicado a debates recurrentes y dar continuidad a los proyectos cuando cambian las personas que los sostienen.
Un registro de decisiones arquitectónicas es un documento de extensión corta que describe una decisión técnica relevante, el contexto en el que se tomó, las alternativas que se evaluaron y las consecuencias que implica. No es un manual de diseño ni una guía de estilo: es un historial. Cada entrada funciona como una fotografía del razonamiento del equipo en un momento concreto, y el conjunto de entradas permite reconstruir por qué el sistema tiene la forma que tiene hoy.
En consultoría, esta trazabilidad tiene un valor incalculable porque los equipos cambian con frecuencia y los proyectos se traspasan entre personas. Cuando un consultor nuevo se incorpora a un proyecto y pregunta por una decisión que ya está tomada, el registro le ofrece la respuesta sin necesidad de interrumpir a nadie. Además, el cliente obtiene un artefacto de documentación que justifica técnicamente lo que se ha construido y que puede auditarse o revisarse en el futuro sin depender de la memoria de quien estuvo presente en la conversación original.
El propósito central del registro no es burocratizar el trabajo del equipo, sino dejar constancia de las decisiones que afectan de forma significativa al sistema. Es decir, no cualquier decisión merece una entrada. Solo se documentan aquellas que impactan en la estructura del sistema, en los atributos de calidad clave (rendimiento, seguridad, disponibilidad, mantenibilidad) o que resultan difíciles o costosas de revertir. Un cambio de nombre de una variable no necesita un registro; un cambio en el modelo de persistencia, sí.
Cada entrada captura el contexto, la justificación y las implicaciones de la decisión, de modo que el lector pueda evaluar si la decisión sigue vigente o si las circunstancias han cambiado. Esto no solo facilita la incorporación de nuevos miembros, sino que además reduce la probabilidad de que el equipo revise dos veces la misma alternativa. La decisión, una vez documentada, deja de ser un tema abierto y se convierte en una referencia consultable que cualquier miembro puede citar cuando surja la duda.
En los equipos que no llevan ningún tipo de registro suelen aparecer tres patrones de comportamiento que frenan el proyecto y generan frustración. El primero es la parálisis: no se decide nada por miedo a equivocarse. El segundo es tomar una decisión sin justificación, de forma que las personas que no participaron en la conversación no entienden el motivo y vuelven a abrir el debate. El tercero es no dejar constancia de la decisión en ningún repositorio, de manera que el equipo olvida que se tomó o ni siquiera sabe que existe.
Estos patrones se pueden agrupar de la siguiente manera:
Escribir un registro de decisiones arquitectónicas rompe los tres patrones. Obliga a decidir, obliga a justificar y obliga a documentar en un lugar accesible. El resultado es un proyecto con menos reuniones repetidas, con menos reprocesos y con un historial que sirve como punto de partida para equipos futuros, en lugar de una serie de decisiones que se diluyen en la memoria colectiva.
Los beneficios de adoptar registros de decisiones arquitectónicas no son abstractos. Se traducen en menos tiempo invertido en debates ya resueltos, menos riesgo de tomar decisiones contradictorias con las anteriores y una incorporación más rápida de nuevo personal. Un proyecto que lleva meses en marcha y que ha tomado cuarenta decisiones significativas acumula, sin registro, cuarenta oportunidades de que alguien las cuestione sin motivo documentado.
Además, el registro ayuda a los equipos a mantener coherencia entre fases. Cuando un proyecto se entrega y pasa a mantenimiento, o cuando se inicia una siguiente iteración con otro equipo, las decisiones anteriores no se renegocian desde cero. Esto es especialmente crítico en entornos de consultoría, donde la rotación de perfiles es alta y cada nuevo miembro necesita un contexto fiable en poco tiempo para no ralentizar la entrega del proyecto.
Un registro compartido alinea a los miembros actuales del equipo, porque cada integrante conoce las decisiones y el razonamiento detrás de ellas. También alinea a los miembros futuros, que se incorporan con un contexto que de otro modo tardarían semanas en reconstruir. La alineación no se consigue con documentos extensos, sino con entradas cortas y asertivas que cualquiera pueda leer en pocos minutos y entender sin consultar fuentes adicionales.
En paralelo, el conjunto de registros establece una dirección estratégica para el proyecto o producto. Permite ver patrones, identificar principios recurrentes y detectar cuándo una decisión nueva se aparta de la línea técnica que el equipo había fijado. Esa coherencia es lo que diferencia una arquitectura pensada de una suma accidental de parches tomados bajo presión.
La reducción de tiempo es probablemente el beneficio más visible. Cada vez que una decisión está documentada, el equipo evita una reunión, una discusión en el chat o un intercambio de mensajes interminable. Además, durante las revisiones de código y las sesiones de planificación, el registro se convierte en la referencia que zanja discusiones sin necesidad de recurrir al criterio de la persona con más antigüedad del equipo.
También mejora la calidad de la documentación del proyecto. Muchas veces la documentación técnica se limita a describir lo que hay, sin explicar por qué. El registro cubre precisamente ese vacío: no repite lo que hace el sistema, sino por qué se eligió una opción y no otra. Para futuros equipos, ese matiz es la diferencia entre entender el sistema y limitarse a copiarlo sin comprender sus motivos.
La consistencia es lo que hace útil una colección de registros. Si cada documento sigue una estructura distinta, quien lo consulta tiene que reorientarse en cada lectura. Por eso conviene definir una plantilla única y adoptarla sin excepciones. No es necesario que la plantilla sea larga; con cuatro o cinco secciones bien elegidas se cubre lo esencial y se mantiene el documento ligero durante toda la vida del proyecto.
Esa plantilla debe ser lo bastante flexible como para recoger tanto decisiones técnicas puntuales como decisiones de proceso, pero lo bastante rígida como para que cualquier lector encuentre la información siempre en el mismo orden. En la práctica, las plantillas de registro más eficaces son las que se pueden rellenar en quince minutos y leer en cinco, porque eso reduce la fricción y aumenta la probabilidad de que el equipo las mantenga en el tiempo.
Cada entrada debería incluir, como mínimo, los siguientes elementos:
El nivel de confianza es un elemento que muchos equipos omiten y que sin embargo resulta muy útil. Una decisión arquitectónicamente significativa puede tomarse con un nivel de confianza relativamente bajo, porque el equipo no tiene datos suficientes o porque el contexto aún no está claro. Documentar ese nivel de confianza avisa a los futuros lectores de que la decisión podría necesitar revisión cuando aparezcan más datos, sin descalificarla por sistema ni generar sensación de inseguridad en el cliente.
Cada entrada debe tener un estado explícito: propuesto, aceptado o reemplazado. Cuando se encadenan muchas decisiones, tener estados claros es lo que permite saber qué está vigente y qué ha quedado obsoleto. Sin esta información, el registro se convierte en un montón de documentos acumulados en lugar de un historial navegable que cualquiera pueda consultar con rapidez.
Cuando una decisión se cambia, no se reescribe la entrada original. Se crea una nueva entrada que sustituye a la anterior y se vinculan ambas. Este enfoque conserva la historia del razonamiento y deja claro cuándo y por qué cambió la dirección técnica. Además, si una decisión es tan amplia que abarca varias fases (por ejemplo, una solución a corto plazo, otra a medio plazo y otra a largo plazo), conviene dividirla en varios registros independientes, uno por fase, para que cada uno pueda evaluarse por separado.
El registro debe iniciarse al comienzo de la carga de trabajo y mantenerse durante toda su vida útil. En proyectos sobre sistemas ya existentes, conviene crear un registro aunque sea de forma retroactiva, basándose en las decisiones pasadas que se conozcan: es mejor un historial parcial que ningún historial. Lo importante es que el registro refleje lo que el equipo sabe y que sirva como punto de partida para lo que venga después, sin convertirse en una tarea que nunca arranca.
El registro es un documento de solo añadido. No se editan las entradas ya aceptadas para corregirlas sin más: si una decisión cambia, se añade una nueva entrada que la sustituya y se enlazan ambas. Esta regla parece estricta, pero es la que garantiza que el registro conserve su valor histórico y que cualquier lector pueda reconstruir la evolución del pensamiento técnico del equipo a lo largo de los meses.
Al inicio de una consultoría o de un proyecto, lo habitual es que las decisiones se tomen con rapidez y mucha incertidumbre. Ese es precisamente el momento en el que aparece el mayor número de decisiones significativas y en el que más fácil resulta olvidarlas. Empezar el registro en esa fase, aunque sea con entradas escasas, es más útil que empezarlo semanas después, cuando parte del contexto ya se ha perdido y nadie recuerda exactamente por qué se eligió una alternativa concreta.
El mantenimiento tiene que integrarse en la rutina del equipo, no tratarse como una tarea aparte. Algunos equipos reservan un hueco en la reunión de planificación para revisar qué decisiones nuevas hay que documentar. Otros lo vinculan a los hitos de entrega o a las revisiones de sprint. Lo importante es que el registro no se convierta en un documento que solo se escribe cuando alguien se acuerda, porque en ese caso acabará abandonado en una carpeta que nadie consulta.
El registro debe almacenarse junto a la documentación de la carga de trabajo y ser accesible para todo el equipo y para el cliente. Una decisión que se tomó pero nunca se registró es una decisión que probablemente se olvidará, lo que conduce a debates repetidos o a cambios posteriores que desconocen la intención original. Cuanto más cerca esté el registro del resto de la documentación, más probable es que se consulte y que se mantenga actualizado.
En consultoría, esta práctica se relaciona directamente con la excelencia operativa. Un arquitecto puede ayudar al equipo a establecer un repositorio único de documentos y recursos, y a colocar allí todos los artefactos relevantes: diagramas, guías, actas y, por supuesto, el registro de decisiones. Esa fuente única de verdad sirve para la referencia diaria, para las auditorías y para la respuesta ante incidentes, y evita que cada miembro del equipo guarde su propia versión del contexto en un lugar distinto.
La mayoría de los problemas que aparecen al adoptar registros de decisiones no vienen de la herramienta, sino de cómo se usa. Hay equipos que escriben entradas demasiado largas, otros que las convierten en guías de diseño y otros que ocultan las consecuencias negativas de una decisión para que parezca mejor de lo que es. En todos los casos el resultado es el mismo: el registro pierde credibilidad y se deja de consultar, con lo que se pierde también el beneficio que se buscaba.
Mantener el registro útil es más sencillo de lo que parece si se respetan unas pocas reglas. No hace falta un proceso pesado ni herramientas sofisticadas: basta con una plantilla, un repositorio accesible y el compromiso de documentar lo significativo cuando ocurre, no semanas después cuando el detalle ya se ha difuminado.
Conviene evitar tres cosas. La primera es ocultar las consecuencias de la decisión, ya sea de forma intencionada o accidental. La segunda es publicar registros sin justificación, porque pierden su valor en cuanto cambian las circunstancias y nadie puede evaluar si la decisión sigue siendo válida. La tercera es convertir las guías de diseño en registros de decisiones, algo que confunde al lector y diluye el propósito del documento.
Si hay más justificación o ideación de diseño disponible, lo adecuado es aportar un enlace a un documento complementario, pero sin que la decisión dependa de ese material para entenderse. La entrada principal debe ser clara y autosuficiente: alguien que la lea sin acceso a los anexos tiene que poder comprender qué se decidió y por qué, sin necesidad de abrir cinco archivos adicionales.
Los registros más útiles son los que se mantienen concisos, asertivos, relevantes y fácticos. Un tono neutro, sin adornos, funciona mejor que un texto cargado de matices. Esto no significa que el registro sea frío, sino que el lector pueda extraer la información esencial con una sola lectura y sin ambigüedades, algo especialmente valioso en contextos de auditoría o de traspaso de proyectos.
También conviene mantener la coherencia en la anatomía de cada entrada. Una plantilla repetida permite que un lector navegue por decenas de registros con la misma facilidad con la que navega por uno solo. Y siempre hay que incluir el contexto y la justificación: un registro sin justificación pierde su valor con el tiempo, porque las partes interesadas no pueden evaluar si la decisión sigue vigente cuando cambian las circunstancias del proyecto o del negocio.
Un registro de decisiones arquitectónicas es, en esencia, un cuaderno de bitácora del proyecto. En lugar de olvidar por qué se eligió una herramienta, un modelo de datos o una forma de trabajar, el equipo deja constancia escrita del motivo. Esto ayuda a que cualquier persona que llegue después entienda el proyecto con rapidez, sin tener que preguntar lo mismo varias veces ni provocar reuniones para temas que ya se habían resuelto en el pasado.
Para quien no tiene perfil técnico, el valor está en la transparencia y en la continuidad. El cliente obtiene un documento que justifica las decisiones técnicas y que puede revisarse o auditarse cuando lo necesite. Y la organización reduce la dependencia de las personas concretas que estuvieron en el proyecto, porque el conocimiento queda documentado en un lugar accesible al que cualquiera puede recurrir sin depender de la memoria de un único integrante.
Desde el punto de vista técnico, el registro de decisiones arquitectónicas es un artefacto de gobierno del diseño. Permite trazar la relación entre requisitos, restricciones y soluciones, y facilita que las decisiones futuras se tomen con conocimiento de las anteriores. Los arquitectos que lo integran en su práctica diaria ganan una base sólida para evaluar cambios, justificar desviaciones y guiar a los equipos en la evolución de la carga de trabajo a lo largo de todo su ciclo de vida.
La recomendación operativa es clara: definir una plantilla con estado, contexto, alternativas, decisión, compensaciones y nivel de confianza; almacenar el registro junto a la documentación de la carga de trabajo; tratarlo como un documento de solo añadido; y revisar periódicamente qué decisiones nuevas conviene documentar. Con esas cuatro bases, el registro deja de ser un requisito formal y se convierte en una herramienta que ahorra tiempo, evita renegociaciones y preserva el criterio técnico del equipo frente a cualquier cambio de personal o de alcance.
Optimización personalizada para tus sistemas digitales. Experiencia y dedicación en cada proyecto, mejoramos tus procesos tecnológicos.
