English

La sección de alternativas del ADR es oro

La parte más valiosa de un documento de decisión son las opciones que no elegiste. Tu asistente de IA hereda tu código, pero no tu razonamiento: solo ve lo que construiste, así que vuelve a proponer con gusto exactamente lo que descartaste hace seis meses. Una sección en tus Architecture Decision Records lo arregla.

Por qué los agentes siguen sugiriendo lo que rechazaste

Un ADR, en el formato original de Michael Nygard de 2011, tiene cinco partes: Title, Context, Decision, Status, Consequences. Fíjate en lo que falta: los perdedores. El documento registra qué elegiste y por qué es bueno, pero no qué evaluaste ni por qué perdió. Un colega humano puede preguntarte en el pasillo; un agente de código que lee tu repositorio no puede. Para el agente, "usamos Postgres" es un hecho, no un veredicto. Sin el veredicto, "¿consideraste MongoDB para esto?" es una sugerencia perfectamente razonable — por cuarta vez.

La guía prescriptiva de AWS sobre ADRs lo dice claro: lo más poderoso de la estructura es que captura la razón de la decisión, y eso es lo que evita que quienes no estuvieron en la sala la reabran después. Los agentes son el colaborador definitivo que "no estuvo en la sala".

El mecanismo: Alternatives Considered

Agrega una sección de Alternatives Considered a cada ADR. Para cada opción rechazada, escribe tres cosas:

La plantilla MADR (Markdown Any Decision Records) incluye esto como secciones de primera clase — Considered Options y Pros and Cons of the Options — así que si empiezas desde cero, úsala en lugar de inventar la tuya. Un ejemplo concreto:

## Considered Options

* PostgreSQL
* MongoDB
* DynamoDB

## Pros and Cons of the Options

### MongoDB — rejected
* Good: flexible schema for the ingest prototypes
* Bad: our reporting queries are relational joins; we'd rebuild them in app code
* Why it lost: 80% of query load is multi-table aggregation — wrong shape for a document store

Esa última línea es la barrera de contención. Cuando tu agente la lee, "migrar a Mongo" deja de ser un refactor plausible y se convierte en un callejón sin salida documentado.

Trucos avanzados

• Alimenta los ADRs al contexto del agente de forma deliberada. Incluye la carpeta docs/adr/ en el archivo de instrucciones de tu agente (CLAUDE.md, AGENTS.md, reglas de Cursor) con una línea: "Lee los ADRs relevantes antes de proponer cambios de arquitectura; no vuelvas a proponer alternativas rechazadas."
• Los ADRs rechazados también cuentan. En el proceso de AWS, el equipo puede rechazar un ADR completo — y el responsable registra la razón precisamente "para evitar futuras discusiones sobre el mismo tema". Conserva los ADRs rechazados en el repositorio; son barreras de contención, no basura.
• Reemplaza, no edites. Los ADRs aceptados son inmutables. Cuando el mundo cambia (Mongo lanza la funcionalidad que lo descartó), escribe un nuevo ADR que reemplace al anterior. Tu agente ve entonces la línea de tiempo, no una historia reescrita en silencio.
• Escribe el factor decisivo como una condición verificable. "Rechazado: agrega una segunda base de datos que operar" envejece mejor que "rechazado: demasiado complejo" — el agente (y tu yo futuro) puede comprobar si la condición sigue vigente.

Recursos

• Documenting Architecture Decisions — Michael Nygard (2011)
• MADR — la plantilla Markdown Any Decision Records
• Why write ADRs — blog de ingeniería de GitHub
• Proceso de ADR — AWS Prescriptive Guidance
• Architecture decision record — colección de plantillas de Joel Parker Henderson