ADR: documenta el porqué de tus decisiones técnicas

El problema que nadie quiere admitir: sabemos qué se decidió, pero no por qué

Cualquier founder tech que haya incorporado a un nuevo ingeniero sabe la escena: el desarrollador pregunta por qué se usó tal base de datos, por qué se descartó GraphQL o por qué el sistema de autenticación funciona de esa manera particular. Y la respuesta honesta, la mayoría de las veces, es un incómodo silencio o un «así estaba cuando llegué».

El debate que surgió en Hacker News en torno a esta pregunta —¿cómo capturas el POR QUÉ detrás de las decisiones de ingeniería, no solo el qué?— toca uno de los puntos ciegos más costosos en equipos de software: la pérdida del contexto de decisión. Y en startups de crecimiento acelerado, donde el equipo rota, donde se prioriza la velocidad y donde la documentación siempre puede esperar, este problema se vuelve crítico.

Por qué la documentación tradicional falla a los equipos de ingeniería

Los métodos clásicos de documentación tienen fallas estructurales que los founders deben conocer:

👥 ¿Quieres ir más allá de la noticia?

En nuestra comunidad discutimos las tendencias, compartimos oportunidades y nos ayudamos entre emprendedores. Sin humo, solo acción.

👥 Unirme a la comunidad

Los comentarios en el código explican el cómo, no el porqué. Dicen «esto hace X», pero no «descartamos Y porque en ese momento teníamos Z restricción».
Las descripciones de pull requests (PR) suelen ser insuficientes: «fix bug», «add feature», «refactor». El razonamiento se queda en la conversación de Slack que nadie volverá a leer.
Los wikis y Confluence pages mueren de desactualización. Nadie tiene incentivo para mantenerlos al día cuando el sprint apremia.
La memoria del equipo es frágil. Cuando la persona que tomó la decisión rota, el conocimiento se va con ella.

El resultado es lo que en ingeniería se llama deuda de conocimiento: un pasivo invisible que ralentiza el onboarding, genera debates repetidos y produce errores evitables cuando alguien reimplementa lo que ya se descartó.

Architecture Decision Records (ADR): el estándar que todo equipo debería adoptar

Los Architecture Decision Records (ADR) son documentos cortos y estructurados que capturan una decisión arquitectónica importante junto con su contexto, alternativas consideradas y consecuencias. No son wikis enormes ni documentos de diseño exhaustivos: son registros concisos que responden exactamente a la pregunta que nos ocupa.

Un ADR bien escrito contiene, como mínimo, las siguientes secciones:

Título y estado (Propuesto / Aceptado / Deprecado / Reemplazado)
Contexto: ¿cuál era la situación que motivó la decisión?
Decisión: ¿qué se resolvió hacer?
Alternativas consideradas: ¿qué otras opciones se evaluaron y por qué se descartaron?
Consecuencias: ¿qué trade-offs se aceptaron? ¿Qué se gana y qué se sacrifica?

El proyecto de referencia adr.github.io mantiene templates abiertos y herramientas de línea de comandos para gestionar ADRs directamente desde el repositorio, lo cual los convierte en ciudadanos de primera clase del código.

El formato Y-Statement: una alternativa ágil

Para equipos que buscan algo más liviano, el formato Y-Statement es una opción poderosa:

«Porque [contexto], decidimos [decisión] para lograr [resultado deseado], aceptando [consecuencias o trade-offs].»

Simple, reproducible y suficientemente rico para preservar el razonamiento sin convertirse en burocracia.

Docs-as-code: llevar la documentación al flujo de trabajo del equipo

Uno de los problemas estructurales de la documentación es que vive fuera del flujo de trabajo del ingeniero. La solución más efectiva es el enfoque docs-as-code: tratar la documentación con las mismas herramientas, flujos y disciplina que el código fuente.

Esto implica:

Almacenar los ADRs en el mismo repositorio Git que el código (carpeta /docs/decisions/).
Revisar los ADRs en el mismo pull request que implementa el cambio arquitectónico.
Automatizar validaciones (enlaces rotos, formato, campos obligatorios) en el pipeline CI/CD.
Versionar los ADRs: cuando una decisión cambia, no se borra el ADR anterior, se marca como Reemplazado por ADR-XXX y se crea uno nuevo.

Según las mejores prácticas documentadas por Xenoss y AltexSoft, este enfoque reduce drásticamente la desactualización porque la documentación y el código evolucionan en el mismo commit.

IA y automatización: el salto que los equipos modernos están dando

El avance más interesante de los últimos meses es la integración de inteligencia artificial para automatizar la generación de ADRs. Ya no es ciencia ficción: equipos reales están usando estas soluciones hoy.

Claude AI para escanear y documentar decisiones existentes

Un caso documentado por Adolfi.dev muestra cómo usar Claude AI (Anthropic) para escanear un codebase existente, identificar decisiones arquitectónicas no documentadas y generar ADRs automáticamente. El flujo es simple:

El agente analiza el código y detecta patrones de decisión (elección de frameworks, estructuras de datos, patrones de autenticación).
Genera un borrador de ADR con contexto inferido del código y del historial de commits.
Un ingeniero humano revisa, enriquece y aprueba el documento.

La instrucción es tan simple como: «Siempre que realices un cambio arquitectónico significativo, crea un ADR en /docs/decisions/». Esto convierte al agente en un co-autor de la documentación viva del proyecto.

El enfoque humano-liderado, IA-potenciado de Salesforce

Salesforce publicó su metodología en 2025: los ingenieros definen los criterios de evaluación (seguridad, escalabilidad, costo, mantenibilidad) y la IA investiga alternativas, evalúa trade-offs y redacta el ADR. El humano toma la decisión final y añade el contexto cualitativo que la IA no puede inferir.

El resultado es una evaluación más objetiva (sin los sesgos de preferencia del ingeniero de turno) y un registro más completo de las alternativas descartadas.

Claude ADR System para proyectos con IA como co-desarrollador

Un sistema documentado en GitHub Gists describe una arquitectura donde Claude actúa como co-desarrollador en proyectos de software, con instrucciones explícitas de generar ADRs para cada cambio significativo. Esto es especialmente valioso en startups donde el founder técnico trabaja solo o con un equipo pequeño: la IA no solo escribe código, también documenta el razonamiento.

El impacto real en onboarding: de semanas a días

Para un founder, el valor de esta práctica se mide en tiempo de rampa de nuevos ingenieros. Un estudio de InfoQ con datos de equipos de más de 50 personas muestra que los equipos con ADRs activos reducen el tiempo de onboarding técnico en hasta un 40%, porque los nuevos miembros pueden responder sus propias preguntas de contexto sin depender de los veteranos.

Más allá del onboarding, los beneficios son concretos:

Menos debates repetidos: cuando alguien propone «¿por qué no usamos MongoDB?», la respuesta está en el ADR-003.
Mejor toma de decisiones futuras: al revisar decisiones pasadas con sus consecuencias reales, el equipo aprende de su propia historia.
Reducción de deuda técnica invisible: se puede identificar cuándo una decisión tomada bajo restricciones pasadas ya no aplica.
Cumplimiento y auditoría: en sectores regulados (fintech, healthtech), el registro de decisiones arquitectónicas puede ser un requisito legal.

Problemas comunes y cómo superarlos

La adopción de ADRs falla por razones predecibles. Aquí los más frecuentes en startups y sus soluciones:

Problema	Solución
«No tenemos tiempo»	Usar templates cortos + IA para el borrador inicial. El ingeniero solo valida.
«Nadie los lee»	Integrarlos en el PR review: no se aprueba un cambio arquitectónico sin su ADR.
«Se desactualizan»	Docs-as-code en el mismo repo. Los ADRs no se editan: se deprecan y se crean nuevos.
«El equipo no tiene disciplina»	Automatizar la verificación en CI/CD: si falta el ADR, el pipeline falla.

Guía de implementación rápida para founders tech

Si quieres empezar esta semana, aquí el camino más corto:

Crea la carpeta /docs/decisions/ en tu repositorio principal.
Adopta un template base de adr.github.io. No lo personalices en exceso al inicio.
Define el umbral de decisión: ¿qué tipo de decisión merece un ADR? Regla práctica: si la discusión en Slack duró más de 30 minutos, merece un ADR.
Integra la revisión en el PR: añade un campo en tu template de PR: «¿Esta decisión requiere un ADR? Si es sí, ¿está adjunto?»
Piloto con IA: usa Claude o ChatGPT con el contexto del cambio para generar el primer borrador. Toma 5 minutos, no 50.
Haz retroalimentación del pasado: dedica una sesión de 2 horas con el equipo a documentar las 5 decisiones arquitectónicas más importantes ya tomadas. Es deuda de conocimiento que vale la pena saldar.

Conclusión

La pregunta de Hacker News es deceptivamente simple, pero toca un problema de fondo en todos los equipos de ingeniería que escalan: el conocimiento de por qué se tomaron las decisiones es tan valioso como el código mismo. Y a diferencia del código, ese conocimiento no está versionado, no está testeado y no tiene CI/CD que lo proteja.

Los Architecture Decision Records, combinados con el enfoque docs-as-code y la automatización con IA, ofrecen hoy una solución madura y accesible para cualquier startup. No se trata de documentar todo: se trata de documentar lo que importa, en el momento en que importa, de la forma más eficiente posible.

El costo de no hacerlo es silencioso pero acumulativo: cada nuevo ingeniero que tarda semanas en entender el sistema, cada debate repetido sobre decisiones ya tomadas, cada error cometido por desconocer un trade-off aceptado hace seis meses. Ese es el precio real de la deuda de conocimiento.

Descubre cómo otros founders implementan prácticas de documentación técnica y automatización en sus equipos. Únete gratis a la comunidad de Ecosistema Startup.

Unirme gratis