La primera vez que escribí un ADR fue porque me lo pedía el equipo de un proyecto grande. La razón por la que sigo escribiéndolos en proyectos de una sola persona es distinta: dejé de acordarme de por qué había tomado ciertas decisiones a los tres meses, y volver a discutirlas conmigo mismo cada vez era un desperdicio de tiempo que se podía evitar con un archivo de texto.

Qué es, sin rodeos

Un ADR (Architecture Decision Record) es un documento corto que registra una decisión técnica concreta: qué se decidió, qué alternativas se consideraron, por qué se descartaron, y qué consecuencias se aceptan a cambio. No es documentación de cómo funciona el sistema, eso ya lo cuenta el código. Es documentación de por qué el sistema es como es, que el código nunca cuenta por sí solo.

Por qué el código no basta

El código te dice qué hace el sistema. No te dice por qué no hace algo distinto. Si alguien —o un agente de código— ve una solución "obviamente mejor" a simple vista, sin un ADR no tiene forma de saber si esa alternativa ya se consideró y se descartó por un motivo válido, o si simplemente nadie pensó en ella todavía. Sin ese contexto, la decisión sin razón escrita se trata como un descuido, y se toca. La decisión con razón escrita se respeta, o al menos se cuestiona con conocimiento de causa.

El formato que uso, mínimo

No necesito plantillas complejas. Cuatro campos:

  • Contexto: qué problema había que resolver y qué restricciones existían en ese momento.
  • Decisión: qué se eligió, en una o dos frases, sin ambigüedad.
  • Alternativas descartadas: qué otras opciones se consideraron y por qué no se eligieron.
  • Consecuencias: qué se gana y qué se sacrifica con esta decisión, incluidas las desventajas que se aceptan a propósito.

Un archivo de texto por decisión, con fecha, es suficiente. No hace falta una herramienta dedicada ni un proceso de aprobación para un proyecto pequeño.

Cuándo escribo uno y cuándo no

No escribo un ADR para cada línea de código. Lo escribo cuando la decisión tiene alternativas razonables que alguien podría proponer de nuevo más adelante, cuando revertirla sería costoso, o cuando el motivo no es obvio con solo mirar el resultado final. Elegir una librería sobre otra, una arquitectura sobre otra, o descartar deliberadamente una funcionalidad que parece obvia añadir: esos son los casos que merecen quedar por escrito.

Cómo esto ayuda específicamente con agentes de código

Un agente que trabaja sobre el proyecto no tiene memoria de las conversaciones que tuviste contigo mismo hace dos meses. Si un ADR explica por qué se descartó cierta librería, y ese archivo está accesible en el repo, el agente puede leerlo antes de sugerir volver a esa opción. Sin ese registro, cada sesión nueva corre el riesgo de reabrir un debate que ya estaba cerrado, porque no hay forma de que el agente sepa que ya se cerró.

El coste de no hacerlo

La alternativa a escribir ADRs no es "ahorrar tiempo documentando". Es pagar ese mismo tiempo más tarde, cada vez que alguien —humano o agente— propone reconsiderar algo que ya se decidió, y hay que reconstruir de memoria el razonamiento original. Esa reconstrucción es más cara que haberlo escrito una vez cuando la decisión estaba fresca.

La recomendación

No necesitas un proceso pesado para empezar a usar ADRs. Necesitas escribir, la próxima vez que tomes una decisión técnica con alternativas razonables, cuatro frases: qué elegiste, qué descartaste, por qué, y qué consecuencias aceptas. Ese archivo te ahorra la próxima discusión contigo mismo, o con un agente que no tiene forma de saber que esa discusión ya pasó.

Relacionado: Cómo estructuro un proyecto para que un agente no se pierda