De RFC a ADR: Alcanzando la Decisión y Manteniendo el Razonamiento

La decisión que nadie pudo reconstruir

El nuevo líder técnico hace una pregunta razonable: ¿por qué cada servicio se comunica con el sistema de facturación a través de esa cola? Hay un ADR — ADR-014, cuatro oraciones, escrito hace once meses. Contexto: "necesitábamos una integración de facturación confiable." Decisión: "usar la cola." Consecuencias: "algo de latencia añadida." Técnicamente es un registro. No responde nada.

Estuviste allí, así que sabes lo que ADR-014 no dice: la discusión de tres semanas a través de dos canales de Slack y un hilo de PR acalorado; la opción de API sincrónica que perdió debido a un límite de tasa que desde entonces se ha elevado; la objeción del ingeniero de personal que fue respondida con un punto de referencia que nadie puede encontrar ahora. El debate ocurrió. El registro fue escrito después, de memoria, por una persona, un viernes.

Este es el modo de fallo documentado, casi universal, de una práctica genuinamente buena. La guía prescriptiva de AWS y los documentos Well-Architected de Microsoft recomiendan ambos los ADR — y ambos señalan el dolor: mantenerlos actualizados lleva tiempo, y gestionarlos se vuelve complejo a medida que los equipos y las opciones se multiplican. La causa raíz es estructural: el debate y el registro viven en lugares diferentes, por lo que el registro siempre es una transcripción con pérdida. La solución es hacer que sean el mismo lugar. Tampoco es una práctica específica de ingeniería, ni siquiera específica de ADR. Google requiere un documento de diseño — problema, enfoque propuesto, alternativas consideradas, compensaciones — escrito y revisado antes de que comience un trabajo técnico significativo, una práctica establecida en el propio Software Engineering at Google de la empresa. Es la misma disciplina que un ADR, aplicada un paso antes: el ADR registra la elección a la que un documento de diseño llegó tras argumentar. Ambos fallan de la misma manera por la misma razón, y ambos se solucionan con el mismo movimiento: mantener el argumento donde vive el registro, en lugar de transcribir uno en el otro después. Lee cada paso a continuación como si cubriera ambos artefactos.

Por qué se pudren los ADRs

Una frase del propio material de la comunidad ADR lleva todo el diagnóstico: un RFC suele tratar sobre alcanzar un acuerdo; un ADR registra el acuerdo una vez alcanzado. Dos artefactos, dos momentos — y todo lo que hay entre ellos se filtra. Las alternativas que eran "obviamente" incorrectas no se registran (hasta que dejan de ser obvias). La objeción que dio forma al diseño final sobrevive solo como un comentario en PR en un hilo cerrado. La sección de contexto se escribe al final, de la peor manera, por quien perdió el juego de no ser. Reuniones que deberían haber producido decisiones producen resúmenes en su lugar, y el razonamiento que hace que una decisión sea duradera — la cosa de la que depende toda la cadena de calidad de decisiones — es exactamente lo que la transcripción deja caer.

Paso 1–3: La propuesta, el contexto, las opciones

1. 1Declara la propuesta como la afirmación raíz — la decisión propuesta, no una pregunta: "Enrutaremos todas las escrituras de facturación a través de una cola duradera." Esta oración es el título del futuro ADR. Punto de control: la raíz existe, una oración, escrita por el proponente.
2. 2Contexto como argumentos pro separados. Cada fuerza que hace necesaria la decisión — el requisito de fiabilidad, el límite de tarifa del sistema de facturación, el mandato de auditoría — es su propio argumento bajo la raíz. Un párrafo monolítico de "Contexto" no puede ser impugnado; tres afirmaciones de contexto separadas pueden ser cuestionadas, confirmadas o derribadas individualmente. Punto de control: ≥2 argumentos de contexto, cada uno una fuerza.
3. 3Cada opción tiene su propio nodo. La cola, la API síncrona, el trabajo por lotes — argumentos hermanos, cada uno con sus propios pros y contras. El pro/con es relativo al padre, por lo que las desventajas de una opción dependen de esa opción, no de la decisión. Incluye las opciones que esperas rechazar: el hermano rechazado es lo que responde al "¿por qué no simplemente…?" del próximo año. Punto de control: existe cada opción sobre la que un lector podría preguntar.

Paso 4–6: La ronda RFC que deja un registro

Ahora la ronda de revisión — normalmente la parte que se dispersa en chats, comentarios y pasillos. Aquí se presenta como tres tipos de intercambio estructurado, cada uno un diálogo de cuatro turnos entre un revisor y el autor de la opción:

Paso 7: Decidiendo — y lo que la calificación no es

Los tomadores de decisiones califican las opciones: cada una etiquetada con una calificación. La distribución es evidencia genuina — donde se encontraba la sala, en el registro, antes de la llamada. Pero la calificación no es la decisión. Un humano nombrado aún decide, y si la llamada va en contra de la distribución, el nodo de decisión es donde eso se explica. (Quién debería ser ese humano nombrado, y cómo asignar el rol antes del debate en lugar de después, es su propia disciplina — consulta el tutorial sobre derechos de decisión.)

Paso 8–9: El ADR que no tuviste que escribir

Aquí está la recompensa. El registro no es un documento que escribes después — es el nodo de la opción elegida más todo lo que ya está adjunto a él: los argumentos de contexto (Context), los hermanos rechazados (Options Considered), las cadenas completadas (la discusión, con autores), las calificaciones (dónde estaba la sala), y el argumento de decisión con su justificación (Decision). Nada se transcribe, por lo que nada se pierde en la transcripción.

1. 1Registra las consecuencias que estás aceptando. Los inconvenientes conocidos —la latencia adicional, la carga operativa de la cola— se consideran como hijos de la opción elegida, reconocidos por el decisor. Escribirlos es lo que convierte esto en una decisión en lugar de una preferencia. Punto de control: ≥1 consecuencia aceptada en el registro.
2. 2Exporta si tu organización requiere ADRs rastreados por el repositorio. Muchas lo hacen, correctamente: el ADR en markdown junto al código permanece como el artefacto de cumplimiento. Escribe el resumen de cuatro secciones del árbol (cinco minutos, no un viernes), enlaza de vuelta a la discusión para el debate completo. Punto de control: el ADR del repositorio cita el árbol; el árbol contiene el razonamiento.

Disentir y comprometerse, en el registro

El patrón que Amazon hizo famoso — discrepar y comprometerse — tiene un problema de legibilidad: ¿cómo puede alguien saber más tarde que la discrepancia fue real, escuchada y respondida, en lugar de ser ignorada? La mecánica de la cadena lo responde. Una cadena de Revisión que completó sus cuatro turnos y finalizó sin acuerdo es precisamente el recibo: se presentó la objeción, se respondió, se insistió y se respondió nuevamente, en el registro, antes de que el disidente se comprometiera. El disidente está documentado como que fue escuchado — lo que hace que comprometerse después sea razonable en lugar de meramente obediente.

Paso 10: Sustitución sin eliminar

Las decisiones envejecen. Cuando se eleva el límite de tasa que eliminó la opción sincrónica, el movimiento correcto es una nueva decisión que hace referencia a la que reemplaza — un nuevo argumento vinculado al nodo de ADR-014, indicando qué cambió. La antigua decisión permanece legible; su razonamiento es exactamente la razón por la cual la nueva decisión sabe qué está anulando.

Una brecha honesta a gestionar explícitamente: no hay un campo de estado ADR incorporado. Propuesto / aceptado / sustituido no es un estado de primera clase en un argumento; la sustitución se modela mediante enlaces, y la convención es tuya para mantener. Establece esto en el acuerdo de trabajo de tu equipo en lugar de asumir que el producto lo impone.

Limitaciones honestas

• ✗Esto no reemplaza los ADR en tu repositorio si tu organización los requiere versionados junto al código. Exporta y confirma el resumen; utiliza el árbol para la parte en la que markdown es deficiente: el debate.
• ✗No hay campo de estado ADR. Propuesto/aceptado/sustituido es una convención de enlace que mantienes, no algo que el producto impone.
• ✗Una cadena son cuatro vueltas. Una profunda discrepancia arquitectónica necesitará una llamada; la cadena es el registro de lo que ya se intentó antes.
• ✗Las calificaciones son un único valor etiquetado, no una puntuación ponderada de múltiples criterios.
• ✗No hace que nadie escriba un buen contexto. La estructura reduce el costo de un buen registro; no proporciona el juicio.

Lecciones prácticas

• ✓Un RFC, una discusión. Resiste al mega-árbol que cubre toda la arquitectura del trimestre: los enlaces de supersesión conectan decisiones mejor que la anidación.
• ✓Semilla de lo que existe. Un transcrito cargado de decisiones o tu antigua carpeta ADR, extraída, le da al debate un buen comienzo — etiquetado como importado, para que los argumentos en vivo permanezcan distinguibles.
• ✓Ponga los nombres de los revisores en sus cadenas y déjelos allí. La atribución es la responsabilidad; las objeciones arquitectónicas anónimas se convierten en folclore con el tiempo.
• ✓La sección de consecuencias es del decisor, de nadie más. Los inconvenientes aceptados escritos por la persona que los aceptó tienen un peso diferente al de las advertencias de un revisor.

ADR-014, la versión que responde

Volviendo a la pregunta del nuevo líder técnico. En la versión reconstruida, ADR-014 es un nodo: la decisión de la cola con su justificación, tres fuerzas contextuales (una ahora obsoleta — visiblemente), un hermano de API sincrónica rechazado cuyo nombre fatal menciona el antiguo límite de tasa, cuatro cadenas de revisión completadas, incluida la del ingeniero de personal, y el punto de referencia adjunto como evidencia. El líder técnico lee durante diez minutos, ve que el límite de tasa ha cambiado y abre una propuesta que sustituye a la antigua nodo. Nadie excava en Slack. Esa es toda la promesa: las cadenas alcanzan el acuerdo, el árbol lo registra — y el registro responde preguntas que no sabías que se harían.