Sistema de decisión que pone fin al caos del proyecto: Registro de decisiones arquitectónicas (ADR) (Sistema DE Decision Que Pone Fin Al Caos Del Proyecto Registro DE Decisiones Arquitectonicas Adr)

Sistema de decisión que acaba con el caos del proyecto: Registro de decisiones arquitectónicas (ADR)

El mayor problema en los proyectos de software modernos no suele ser la calidad del código. El verdadero peligro proviene de un lugar mucho más insidioso: Decisiones olvidadas.

La gran mayoría de los equipos corporativos todavía gestionan las decisiones arquitectónicas que determinan el destino del proyecto en el nivel "Hablamos de ello en la última reunión". Sin embargo, a medida que el proyecto crece, el equipo cambia y pasa el tiempo, esas reuniones se desvanecen.

Estas molestas preguntas persisten:

• "¿Por qué hicimos de este sistema un microservicio? ¿Quién decidió?"
• "¿Por qué elegimos esta base de datos? ¿Buscamos alternativas?"
• "¿Previmos este problema que estamos viviendo ahora?"

Si no tienes una respuesta clara a estas preguntas o un documento que mostrar; Significa que su proyecto está cayendo en un caos técnico.

En este punto entra en juego el sistema ADR (Architecture Decision Record), que evita que el proyecto dependa de las personas.

¿Qué es la ADR? (No es un documento, memoria arquitectónica)

ADR es un sistema donde se registran de manera breve, clara y permanente las decisiones críticas tomadas en proyectos de software. Pero no confunda esto con documentación técnica aburrida.

Cada ADR es un registro en vivo que responde a 4 preguntas básicas:

1. ¿Qué decisión tomamos?
2. ¿Por qué lo compramos? (¿Cuál fue el contexto?)
3. ¿Cuáles eran las alternativas? (¿Qué eliminamos?)
4. ¿Cuáles son las compensaciones? (¿Cuánto nos cuesta o nos arriesga esta decisión?)

ADR es la "memoria" de su proyecto. El código puede cambiar, la tecnología puede cambiar, incluso el CTO puede cambiar; pero la lógica de las decisiones permanece en el proyecto gracias a ADR.

Diferencia crítica entre tarea y ADR

Muchos equipos cometen el error de pensar que los tickets o tareas de Jira son “decisiones”. Sin embargo, existe una gran diferencia entre ellos.* Tarea: "Haz esto", dice. Está orientado a la acción.

• ADR (Decisión): "¿Por qué hacemos esto?" dice. Está orientado a la estrategia.

Expliquemos con un ejemplo sencillo:

• Tarea: "Mejorar los puntos finales de la cesta". (Esta tarea finaliza y se archiva).
• ADR: "¿La estructura del carrito debería ser un servicio separado o debería permanecer dentro de la aplicación principal?" (Esta decisión afecta la arquitectura del proyecto durante años).

La tarea termina, ADR vive.

¿Cómo es un ADR?

Escribir ADR no es un trabajo que lleve días. Más bien, requiere claridad. A continuación se muestra una plantilla de ADR sencilla y eficaz:

ADR-007: Uso de caché de Redis

Estado: Aceptado

Contexto: Los tiempos de respuesta de la API aumentaron y la carga en la base de datos comenzó a aumentar. Las operaciones de lectura superan con creces a las de escritura.

Decisión: La caché de Redis se utilizará en puntos finales de lectura frecuente.

Alternativas: Se consideró la optimización del índice de la base de datos o el uso de CDN, pero se eliminó debido a la necesidad de datos instantáneos.

Consecuencias:

• (+) El tiempo de respuesta (Latencia) disminuirá.
• (+) La carga de la base de datos disminuirá.
• (-) Se agregará complejidad de borrado (invalidación) de caché.

Como se puede ver; Revela claramente no sólo la decisión, sino también sus motivos y consecuencias.

¿Por qué la ADR no es sólo un tema "técnico"?

Como gerente o propietario de un proyecto, solicitar ADR protege su proyecto. El sistema ADR proporciona:

• Velocidad: Las mismas discusiones sobre arquitectura no se repiten en cada sprint. La decisión está tomada, el viaje continúa.
• Facilidad de incorporación: Un nuevo desarrollador entrante podría preguntar: "¿Por qué?" En lugar de preguntar "", comprende toda la historia del proyecto leyendo los registros ADR.* Gestión técnica de la deuda: Se avanza aceptando riesgos (compensación), no de forma inconsciente.

¿Cómo aplico ADR en mis servicios?

En mi trabajo de gestión de proyectos y consultoría técnica, la redacción de ADR no es una "tarea" sino una disciplina de entrega.

Cuando me involucro en un proyecto, suelo implementar lo siguiente en los primeros 7 días:

1. Establecimiento de la Estructura del Registro ADR: Determinamos dónde se guardarán las decisiones (Jira, Git, Notion, etc.).
2. Registro de decisiones críticas: Tomamos una radiografía de la arquitectura actual y aclaramos las decisiones críticas tomadas retrospectivamente.
3. Dar forma a la hoja de ruta: Priorizamos la hoja de ruta de entrega en función de estas decisiones arquitectónicas, no solo de las características.

Esto garantiza una total transparencia entre la dirección y el equipo técnico. Se evita la "desviación del alcance" (expansión del alcance) y el proyecto se confía al propio sistema, no a la memoria de los individuos.

Resultado

El código cambia. Las reuniones pasan volando. Pero las decisiones forman la base de su proyecto.

Si siente que las decisiones están flotando en el aire en su proyecto y los mismos temas se discuten una y otra vez, necesita una "memoria de decisiones".

La carpeta "Technology Stack and Architecture" es el lugar más natural para que vivan estas decisiones.

---

Configuremos este sistema en 5 pasos usando la estructura de Confluence:

Paso 1: Crear la "Biblioteca de decisiones"

Abramos una nueva página de inicio en la carpeta "Arquitectura y pila de tecnología" en la captura de pantalla.

• Nombre de la página: Registro de decisiones de arquitectura (ADR)
• Propósito: Esta página no es una decisión independiente; Esta es la tabla principal donde se enumeran todas las decisiones (Índice). Así, cuando un nuevo miembro del equipo hace clic aquí, ve el historial completo del proyecto en una lista.#### Paso 2: preparar una plantilla global A nadie le gusta crear una página desde cero cada vez. En Confluence, debes crear una "Plantilla Global" o una plantilla solo para este Espacio. El contenido de la plantilla debe ser como hablamos antes:
• Título: ADR-XXX: [Título corto]
• Estado: (Detallaremos esto en el Paso 3)
• Contexto: ¿Qué pasa?
• Decisión: ¿Qué estamos haciendo?
• Consecuencias: Costos y ganancias.

Paso 3: Utilice la macro visual "Estado"

Una de las mayores fortalezas de Confluence es la función Macro de estado. Agregue esta macro a la parte superior de su plantilla. Los colores permiten que el cerebro perciba la situación en cuestión de segundos. Los códigos de colores estándar pueden ser:

• 🟢 ACEPTADO (Verde): La decisión ha sido tomada y se está implementando.
• 🟡 PROPUESTO (Amarillo): Abierto a discusión, aún no aprobado.
• 🔴 RECHAZADO (Rojo): Fue sugerido pero no aceptado (ocultarlo también es una lección).
• ⚪ DESPRECADO (Gris): Solía ​​ser válido pero ahora ha sido reemplazado por una nueva decisión (por ejemplo, ADR-009).

Paso 4: Editar árbol de páginas (jerarquía)

Coloque cada nueva página ADR que cree (por ejemplo, ADR-001: Redis Cache) como una página secundaria de la página Registro de decisiones de arquitectura que abrimos en el primer paso. La vista será así:``` 📂 Teknoloji Yığını ve Mimarisi └── 📂 Architecture Decision Log (ADR) ├── 📄 ADR-001: Redis Cache Kullanımı ├── 📄 ADR-002: Auth Provider Seçimi └── 📄 ADR-003: ...

Esta es la parte "mágica". 🪄 En lugar de hacer listas manualmente una por una, usemos la automatización de Confluence.
Agregue la macro "Propiedades de página" a cada página de ADR (plantilla) y coloque información resumida como estado, fecha de decisión y responsables de la toma de decisiones.
Vaya a la página principal (Registro de decisiones de arquitectura) y agregue la macro "Informe de propiedades de página".
Esta macro extrae esa información resumida de las subpáginas y crea una tabla automática y siempre actualizada en la página principal.