ADRs para equipos que necesitan una arquitectura clara
Como CTO fraccional, uso Architecture Decision Records para que startups y scale-ups documenten las decisiones que realmente sostienen su arquitectura SaaS e integraciones IA. Un ADR registra que se decidió, por qué y con que consecuencias.
La mayoría de equipos no los escribe. Y luego pasan seis meses teniendo la misma discusión cada vez que alguien nuevo pregunta "¿por que usamos está base de datos?" o "¿por que no usamos GraphQL?"
Por qué los equipos no los escriben
Porqué nadie les enseñó a hacerlo, porqué parece burocracia, porqué "no hay tiempo" y porqué el conocimiento sobre esas decisiones está en la cabeza de dos o tres personas que llevan más tiempo en el equipo. Hasta que esas personas se van.
La estructura mínima que funciona
Un ADR no necesita más de media página. La estructura que uso:
Estado: Aceptado
Fecha: 2026-03-15
Contexto: El core legacy no puede modificarse. Necesitamos integrar el módulo de ML sin acoplamiento directo.
Decisión: El core produce eventos de negocio. El módulo de ML los consume de forma asíncrona.
Alternativas consideradas: API síncrona (descartada por riesgo de latencia), modificación del core (descartada por proceso de cambio de 3 meses).
Consecuencias: El ML puede actualizarse independientemente. La latencia de respuesta del core no se ve afectada. El equipo de ML necesita entender el esquema de eventos.
Cuándo escribir un ADR
No para cada decisión. Para las que son difíciles de revertir, que afectan a varios equipos o que serán cuestionadas cuando las cosas vayan mal. Una regla práctica: si la decisión merece más de 10 minutos de discusión en una reunión, merece un ADR.
Dónde guardarlos
En el repositorio de código, junto al código que afectan. No en Confluence, no en Notion, no en Google Drive. En el repo, dónde los desarrolladores trabajan. Un directorio docs/adr/ con un archivo Markdown por decisión. La búsqueda de Git hace el resto.
Implementar ADRs es uno de los primeros pasos del Sprint de Arquitectura.
Agenda una sesión →