§ Publicación
La arquitectura es una conversación, no un diagramita.
Por qué los mejores diseños de sistemas nacen del desacuerdo productivo, y cómo documentar las decisiones (no solo el resultado) cambia a los equipos.
Los diagramas mienten. No por malicia, sino por omisión: muestran el qué y ocultan el por qué. Y el por qué es justo lo que un equipo necesita heredar cuando quien diseñó ya no está.
Decisions over artifacts
Un ADR —Architecture Decision Record— no es burocracia. Es la huella de una conversación: qué opciones se consideraron, qué restricciones pesaban, qué supuesto marcó la diferencia.
Cuando un sistema se siente opaco, el problema casi nunca es técnico. Es que las decisiones quedaron atrapadas en la cabeza de alguien.
Cómo escribir ADRs que se lean
- Contexto primero. Sin él, la decisión parece arbitraria.
- Opciones con argumentos, no con preferencias.
- La decisión y su costo. Qué ganamos y a cambio de qué.
El hábito vale más que el formato. Un ADR breve que existe supera a uno perfecto que no.
Jason