Pregunta y contexto
Esta pregunta evalúa si puedes transformar una compensación técnica importante en una memoria de equipo que sea fácil de buscar, revisar y hacer evolucionar. Cubre cuándo se justifica un ADR, cómo registrar las opciones descartadas, cómo el registro respalda la revisión de código y la resolución de problemas, y cómo manejar una decisión que es reemplazada por una nueva.
Aplica para roles de backend, plataforma, SRE, staff engineer y puestos multifuncionales. Asume que el equipo cuenta con un repositorio y un proceso de revisión, pero no con una convención compartida de registros de decisiones; la elección puede involucrar confiabilidad, seguridad, interfaces, dependencias o una compensación de costos irreversible.
Qué evalúa el entrevistador
Primero, ¿puedes identificar una decisión arquitectónicamente significativa en lugar de documentar cada detalle de implementación? Segundo, ¿puedes explicar la elección con un contexto neutral, restricciones, opciones y consecuencias? Tercero, ¿puedes situar el ADR en un ciclo de vida con estados propuesto, revisado, aceptado y reemplazado? Cuarto, ¿puedes hacer que el registro sea útil en la revisión de código, la incorporación de nuevos miembros y la respuesta a incidentes?
Preguntas aclaratorias para hacer
- ¿La decisión afecta la estructura del sistema, atributos clave de calidad, una interfaz pública o solo la implementación local?
- ¿Qué restricciones duras aplican: latencia, disponibilidad, cumplimiento normativo, habilidades, ventana de migración o costo?
- ¿La opción ya está desplegada o el ADR sigue en estado Proposed? ¿Quién puede aceptarlo o rechazarlo?
- ¿Los ADR residirán en el repositorio, en un sistema de documentación o en ambos? ¿Cómo encontrarán las actualizaciones los equipos afectados?
- ¿Qué señales detonarían una reevaluación: tráfico, tasa de fallas, costo o cambios regulatorios?
Estructura para una respuesta de 30 segundos
“Primero verifico si la elección cambia la estructura del sistema, los atributos clave de calidad o una interfaz difícil de revertir. Si es así, creo un ADR conciso. Este registra el contexto, las restricciones, las opciones consideradas, las alternativas descartadas, la decisión, las compensaciones, los riesgos y el estado; luego, los equipos afectados lo revisan mientras está en estado Proposed. Tras su aceptación, lo trato como un historial inmutable; cuando los requisitos cambian, creo un ADR sustituto, vinculo el registro anterior y actualizo el índice. Mantengo el registro en un repositorio versionado y accesible, y lo referencio en revisiones de diseño, revisiones de código, incorporación de personal y resolución de problemas.”
Respuesta paso a paso
Paso 1: Establecer el umbral de registro
Crea un ADR cuando una elección afecte la estructura del sistema, atributos clave de calidad, interfaces públicas, dependencias importantes o un costo difícil de revertir. La nomenclatura, el detalle de una refactorización puntual o una elección ya regida por un estándar claro generalmente no necesitan su propio registro. El umbral preserva las decisiones que cambiarán el razonamiento futuro sin generar ruido documental.
Paso 2: Describir el problema de forma neutral
Expón el problema, el impacto en el usuario o en el negocio, los requisitos funcionales y no funcionales, el plazo y las restricciones no negociables. No introduzcas de forma encubierta una opción preferida en el contexto ni sustituyas los hechos con “el equipo X insistió”. Un nuevo colaborador debería entender por qué se requiere una decisión ahora.
Paso 3: Comparar opciones y compensaciones
Enumera las opciones realmente consideradas, incluidas las opciones descartadas y los motivos por los que se rechazaron. Compara latencia, disponibilidad, radio de impacto, seguridad, costo de migración, carga operativa y capacidad del equipo; cuando los valores sean inciertos, declara las suposiciones y el nivel de confianza. Mantén el ADR enfocado en la decisión y vincula por separado los picos exploratorios o diseños detallados.
Paso 4: Declarar la decisión y las consecuencias
Escribe una decisión que se sostenga por sí misma, como “Usaremos una cola regional y aceptaremos la aprobación manual para la conmutación por error entre regiones”. Luego registra los beneficios esperados, costos, riesgos, controles requeridos y componentes afectados. “Elegir la opción A” no es suficiente porque los revisores futuros no podrán ver la razón ni el precio pagado.
Paso 5: Establecer estado, propiedad y revisión
Utiliza estados como Proposed, Accepted, Rejected, Deprecated y Superseded. Asigna un responsable e invita a los equipos afectados a leer y comentar mientras esté en Proposed; al aceptarse, añade fecha, partes interesadas y versión. La revisión verifica que los hechos, las restricciones, las opciones y las consecuencias sean claros, no que todos vayan a estar de acuerdo para siempre.
Paso 6: Integrar el ADR en el flujo de trabajo de ingeniería
Versiona los ADR junto con el repositorio o el sistema de documentación y mantén un índice con capacidad de búsqueda. Cuando una revisión de diseño o de código detecte un cambio que entre en conflicto con una decisión aceptada, vincula el ADR y exige un registro de cambio explícito. La incorporación de nuevos miembros, las transferencias de proyectos y la respuesta a incidentes también deben usar el ADR para responder al “por qué de esta manera”, reduciendo debates repetitivos.
Paso 7: Agregar un nuevo registro cuando la decisión cambie
Mantén inmutable un ADR aceptado o rechazado. Si nueva evidencia, escala, costos o regulaciones cambian la conclusión, escribe un nuevo ADR describiendo el nuevo contexto, la limitación anterior y la nueva compensación. Una vez aceptado, marca el registro antiguo como Superseded y vincula ambos registros. Esto preserva el historial mientras facilita encontrar la decisión actual.
Ejemplo de una respuesta sólida
“Primero compruebo si esto afecta la estructura del sistema, los atributos clave de calidad, una interfaz o un costo irreversible; si es solo una implementación local, no añadiría un ADR. Una vez que cumple con el umbral, redacto un registro Proposed con el contexto del problema, los requisitos del usuario y no funcionales, las restricciones, las opciones, las alternativas descartadas, la decisión, las compensaciones, los riesgos y la confianza.
Invito a los equipos afectados a leer antes de una discusión de revisión, y registro el estado, el responsable, la fecha y las partes interesadas. Tras la aceptación, mantengo el ADR en un repositorio versionado y con capacidad de búsqueda, y lo referencio en revisiones de diseño, revisiones de código, incorporación de miembros y resolución de problemas. Se mantiene conciso y basado en hechos en lugar de reemplazar un documento de diseño completo.
Si los requisitos o la evidencia cambian, no edito el registro aceptado. Creo un nuevo ADR explicando por qué la decisión anterior ya no encaja, las nuevas opciones y sus consecuencias. Tras la aceptación, marco el registro antiguo como Superseded y vinculo los dos, de modo que el equipo vea la elección actual sin perder el historial del razonamiento.”
Errores comunes
- Escribir una guía de diseño completa → la decisión es difícil de encontrar → mantén el contexto, las opciones, la decisión y las consecuencias; vincula los detalles.
- Registrar solo al ganador → el debate se repite más adelante → incluye las opciones descartadas y las restricciones del momento.
- Reemplazar restricciones con preferencias → el registro no se puede revisar → utiliza hechos y suposiciones neutrales y observables.
- Editar un registro aceptado directamente → el historial desaparece → añade un nuevo registro y marca el anterior como Superseded.
- Omitir el estado y el responsable → nadie sabe si aplica → rastrea el ciclo de vida, el responsable y la fecha de aceptación.
- Nunca citar el ADR → la documentación no tiene valor operativo → conéctalo con la revisión de diseño, la revisión de código, la incorporación de personal y la respuesta a incidentes.
Preguntas de seguimiento y respuestas
Pregunta de seguimiento 1: ¿Puede un equipo aceptar un ADR si hay personas en desacuerdo?
Sí. Registra las objeciones no resueltas, los riesgos y quién puede aceptar la decisión. La revisión hace visibles la elección y su costo; no genera un consenso permanente de manera forzada. Si falta evidencia, mantén el ADR en estado Proposed y programa una tarea de validación.
Pregunta de seguimiento 2: ¿Cuándo se debe crear un ADR retroactivamente?
Créalo retroactivamente cuando una estructura existente, interfaz o compensación de calidad sea importante pero nadie pueda explicarla. Utiliza commits, datos de incidentes y entrevistas con los mantenedores, y etiqueta el resultado como un registro retrospectivo para que la inferencia no se presente como un hecho de la época.
Pregunta de seguimiento 3: ¿Repositorio o wiki?
Prefiere el repositorio versionado cerca del código afectado para que el registro se revise junto con la implementación. Si las partes interesadas del negocio o de seguridad necesitan un acceso más amplio, replica un índice o resumen manteniendo una única fuente autorizada para evitar divergencias.
Pregunta de seguimiento 4: ¿Cómo demostrar el valor de los ADR?
Monitorea el tiempo que les toma a los nuevos miembros entender las decisiones clave, la repetición de debates, las violaciones de decisiones aceptadas detectadas en revisiones y la rapidez con la que quienes responden incidentes encuentran el contexto. Las métricas revelan brechas; la cantidad de documentos no es el objetivo.