Skip to main content

Contexto​

Con la org y el repo de docs ya en su sitio (ADRs 0001 y 0002), aparecen las primeras decisiones realmente arquitectónicas: hosting, autenticación, formato de versionado, branching strategy. Sin un mecanismo formal, esas decisiones quedarían capturadas como mensajes de Slack, comentarios en PRs o memoria individual de quien las tomó. Eso es frágil: cuando una persona se va, cuando un agente IA toma el relevo de un módulo, o simplemente cuando pasan seis meses, el porqué se pierde.

El formato Architecture Decision Record (Michael Nygard, 2011) ya resolvió este problema en muchos equipos. La pregunta no es si adoptarlo, sino con qué nivel de ceremonia.

Decisión​

Toda decisión arquitectónica u organizacional significativa se documenta como un Architecture Decision Record (ADR) dentro de internal-docs/docs/adrs/, numerado secuencialmente, inmutable una vez aceptado, y discutido previamente en GitHub Discussions cuando aplica.

Consecuencias​

  • Memoria institucional: las decisiones (y sus motivos) sobreviven a cambios de personas, agentes IA o herramientas.
  • Trazabilidad de cambios: si una decisión se revierte, queda explícito mediante un nuevo ADR que supersede al anterior.
  • Onboarding más simple: nuevos contribuidores leen los ADRs y entienden el porqué del estado actual sin preguntar.
  • Disciplina al proponer cambios grandes: forzar la escritura de un ADR obliga a evaluar alternativas y consecuencias antes de implementar.
  • Costo de proceso: cada decisión "grande" añade overhead (escribir, revisar, mergear). Se mitiga acotando el ámbito a decisiones que cruzan repos, módulos o personas.
  • Riesgo de obsolescencia: si nadie revisa los ADRs viejos, pueden quedar contradicciones; se mitiga con la regla de inmutabilidad + supersede.

Alternativas evaluadas​

  • Documentación libre en READMEs o wikis: más rápido de escribir pero sin estructura ni inmutabilidad; las decisiones se diluyen y nadie sabe cuál es la versión vigente.
  • Issues etiquetados como decision: aprovecha la UI de GitHub pero los issues se cierran y desaparecen del flujo principal; tampoco hay numeración estable ni contenido renderizable.
  • Slack/Notion para decisiones: efímero o desconectado del código; las decisiones se pierden o quedan inaccesibles para agentes que solo leen el repo.
  • Formato MADR vs Nygard plain: optamos por una variante simple (Contexto / Decisión / Consecuencias / Alternativas / Referencias) que prioriza brevedad sobre exhaustividad; podemos enriquecer el template más adelante si hace falta.

Referencias​