English

Los ADR son combustible para agentes de IA

Tu asistente de IA sigue sugiriendo el ORM que ya probaste y descartaste. Propone la capa de caché que rechazaste en marzo. No es que sea tonto — está leyendo tu base de código, y la base de código solo muestra qué construiste, nunca por qué. Las opciones rechazadas, las concesiones, las restricciones — nada de eso vive en el código. Los Architecture Decision Records lo devuelven.

El porqué que falta

El código es un registro de conclusiones. Cuando un asistente de IA revisa tu repositorio, ve que usas Postgres, que no hay cola de mensajes, que la autenticación la maneja un middleware hecho en casa. Lo que no puede ver es que evaluaste tres colas y las rechazaste todas porque tu equipo de operaciones son dos personas, o que la biblioteca de autenticación "obvia" se probó y se eliminó después de un problema de licencia.

Las personas del equipo llevan esta historia en la cabeza. La IA no tiene cabezas a quién preguntar. Así que hace lo estadísticamente razonable: vuelve a sugerir la opción popular — exactamente la que ya rechazaste. Cada vez que la corriges en el chat, esa corrección se evapora cuando termina la sesión. Necesitas el porqué escrito en algún lugar que el asistente realmente vaya a leer.

Anatomía de un registro de decisión

Un ADR es un archivo markdown corto — un archivo por decisión, numerado, que vive en docs/decisions/ dentro del propio repositorio. El formato clásico tiene cuatro partes:

1. Contexto — la situación que forzó una decisión. Tamaño del equipo, tráfico, plazos, restricciones existentes.
2. Decisión — lo que elegiste, dicho con claridad. "Usaremos Postgres con replicación lógica."
3. Alternativas rechazadas — y por qué — la sección que más importa para la IA. "MongoDB: rechazada, nuestras consultas son relacionales. Kafka: rechazada, la carga operativa es demasiado alta para un equipo de operaciones de dos personas."
4. Consecuencias — qué facilita esta decisión, qué dificulta, y qué tendría que cambiar para que la reconsideres.

Eso es todo. Sin ceremonia de plantilla, sin flujo de aprobación. Se toma una decisión, se escribe un archivo, y ambos entran en el mismo commit cuando es posible.

Qué cambia para tu IA

Una vez que los ADR existen en el repositorio, se vuelven contexto como cualquier otro archivo. Apunta a tu asistente hacia docs/decisions/ — a través de tu archivo de instrucciones del proyecto, o simplemente diciéndole que lea el directorio antes de proponer cambios de arquitectura. El cambio de comportamiento es inmediato y específico: en lugar de "deberías considerar MongoDB para esto", obtienes "el ADR-0003 rechazó los almacenes de documentos porque tus consultas son relacionales — nos quedamos con Postgres, pero así es como manejar el nuevo requisito dentro de él".

El asistente deja de volver a litigar preguntas ya resueltas y empieza a construir sobre ellas. Las alternativas rechazadas siguen rechazadas. Y cuando una decisión realmente merece reconsiderarse, la sección de consecuencias del ADR le dice al asistente — y a ti — exactamente qué condiciones cambiadas lo justificarían.

Trucos avanzados

• Escribe el primer ADR hoy, para la decisión más grande que esté en juego ahora mismo. No rellenes el historial — captura la decisión viva mientras las alternativas y el razonamiento están frescos. Rellena las antiguas solo cuando surjan.
• Mantén cada ADR en una página. Un ADR largo no lo leerán las personas y desperdicia ventana de contexto para la IA. Si no cabe en una página, estás documentando dos decisiones.
• Enlaza el directorio de ADR desde tu README (y desde tu archivo de instrucciones de IA). La descubribilidad es todo el juego — un ADR que ninguna herramienta encuentra es como si no existiera.

Recursos

• adr.github.io — descripción general y herramientas de ADR
• Plantillas y ejemplos de architecture decision records