En el ritmo acelerado de las células de desarrollo, es común tomar decisiones críticas en una reunión de pasillo, en una llamada rápida de Slack o en una sesión de refinamiento. El problema es que la memoria humana es volátil. Seis meses después, nadie recuerda por qué se eligió esa librería específica o por qué se decidió ignorar ese patrón de diseño.
Como ingenieros Senior, debemos entender que nuestra labor no es solo escribir código, sino gestionar el conocimiento técnico del equipo para evitar que se convierta en «materia oscura».
De la nota rápida al Architecture Decision Record (ADR)
Tomar notas en las reuniones importantes no es un acto administrativo; es el primer paso para crear un ADR. Un ADR es un documento corto que captura una decisión técnica relevante, el contexto en el que se tomó y las consecuencias de dicha elección.
¿Por qué deberías empezar a hacerlo hoy?
- Memoria Histórica: Evitas que el equipo caiga en discusiones cíclicas sobre temas que ya se resolvieron meses atrás.
- Onboarding Eficiente: Un nuevo integrante puede leer los ADRs y entender la evolución de la arquitectura sin tener que interrumpir a nadie.
- Responsabilidad Profesional: Documentar el «porqué» protege al equipo y al arquitecto. Si algo falla, el registro muestra que se tomó la mejor decisión con la información disponible en ese momento.
¿Qué debe incluir una buena nota técnica?
No necesitas transcribir toda la reunión. Enfócate en capturar estos cuatro puntos clave:
- Contexto: ¿Cuál era el problema que estábamos tratando de resolver?
- Alternativas: ¿Qué otras opciones consideramos y por qué las descartamos?
- Decisión: ¿Cuál fue el camino elegido de manera definitiva?
- Consecuencias: ¿Qué ganamos y qué sacrificamos con esta decisión? (Trade-offs)
El hábito del Ingeniero de Alto Impacto
En organizaciones de gran escala como Bancolombia, donde los equipos son dinámicos, la documentación de decisiones es lo que permite que el software sea mantenible a largo plazo. No confíes en tu memoria; un Senior confía en sus registros.
Empieza por llevar una libreta o una herramienta digital a cada reunión. Anota las decisiones y, al terminar, dedica 5 minutos a formalizar ese apunte en el repositorio del proyecto. Tu «yo» del futuro y tus compañeros te lo agradecerán.
Te comparto un template que puedes utilizar para documentar los ADR:
# ADR [Número]: [Título corto y descriptivo de la decisión]
* **Fecha:** [AAAA-MM-DD]
* **Estado:** [Propuesto / Aceptado / Superado / Rechazado]
* **Participantes:** [Nombre de las personas involucradas]
## 1. Contexto
¿Cuál es el problema técnico o de negocio que estamos tratando de resolver?
Describe las circunstancias actuales, las limitaciones técnicas y por qué es necesario tomar una decisión en este momento.
## 2. Alternativas
¿Qué otros caminos o herramientas consideramos antes de decidir?
* **Alternativa A:** [Breve descripción, pros y contras]
* **Alternativa B:** [Breve descripción, pros y contras]
Es importante registrar por qué se descartaron estas opciones para evitar discusiones cíclicas en el futuro.
## 3. Decisión
¿Cuál fue el camino elegido de manera definitiva?
Describe la solución técnica seleccionada y justifica por qué es la mejor opción dado el contexto y las alternativas evaluadas.
## 4. Consecuencias (Trade-offs)
¿Qué ganamos y qué sacrificamos con esta decisión?
Toda decisión técnica tiene un costo. Documenta los impactos positivos y negativos:
* **Impacto Positivo:** [Ej: Mejor rendimiento, menor deuda técnica]
* **Impacto Negativo / Riesgos:** [Ej: Mayor complejidad de implementación, curva de aprendizaje]
* **Efectos Secundarios:** [Ej: Necesidad de actualizar el pipeline de CI/CD]