One of the questions I've heard most often in architecture reviews isn't "does this work?", it's "why is it built this way?". And the most common answer, honestly, is an uncomfortable silence followed by "I think it was a decision made two years ago, I'm not sure if it's still valid".

Code tells you what the system does. It almost never tells you why it was decided to build it that way instead of five other equally reasonable ways. That second part —the context, the discarded alternatives, the trade-off that was knowingly accepted— is the first thing to get lost, because it lived in someone's head or in a Slack channel that no one can search anymore.

What an ADR Is

An Architecture Decision Record is a short document, versioned alongside the code, that records an architecture decision at the moment it's made. It's not exhaustive documentation of the system — it's a specific note about a specific decision, written while the context is still fresh.

Here's the template I use, deliberately minimal:

# ADR 007: Usar PostgreSQL en vez de un motor NoSQL para el catálogo de productos

## Estado

Aceptado

## Contexto

Necesitamos persistir el catálogo con relaciones fuertes entre producto, categoría e inventario.
El equipo evaluó DynamoDB (ya usado en otros servicios) y PostgreSQL administrado.

## Decisión

Usamos PostgreSQL. Las consultas del catálogo requieren joins frecuentes y transacciones
multi-tabla que un modelo de acceso por clave no resuelve bien sin duplicar lógica de aplicación.

## Consecuencias

Ganamos integridad referencial y consultas ad-hoc simples. Perdemos la escalabilidad horizontal
automática de DynamoDB — aceptable porque el volumen proyectado no lo requiere en los próximos 3
años. Revisar si el volumen cambia significativamente.

Four sections. Context, decision, consequences, and a status that can be updated ("Proposed", "Accepted", "Superseded by ADR-014"). No twenty-field templates that nobody's going to fill out completely after the third time.

It Lives in the Repository, Not in a Wiki

An ADR in docs/adr/ within the same repository as the code it documents has three advantages that no external wiki gives you for free: it gets reviewed in the same pull request as the change that implements the decision, it stays versioned along with the code it applies to (if you go back three years to an old commit, the ADR from that time is still there), and it shows up in the code searches of anyone working on that part of the system — no one needs to remember that a wiki exists and know to search for it there.

When to Write One (and When Not To)

Not every decision deserves an ADR. If you write one for everything, nobody's going to read them and the ritual loses its meaning. The criterion I use: is this decision expensive to reverse, does it affect more than one team, or could a reasonable person have chosen the opposite alternative? If the answer is yes to any of the three, it's worth the ten minutes it takes to write it. Choosing a variable name doesn't need an ADR. Choosing between a monolith and microservices, between SQL and NoSQL, or adopting a pattern like CQRS, does.

The Real Audience

An ADR isn't written for today's team — it's written for the person who's going to inherit the system in two years, who's going to wonder "why is this built this way?", and instead of reconstructing the decision from scratch or assuming it was a mistake, will be able to read exactly what was considered and why it was discarded. Often that person is you yourself, at a point when you've already forgotten the context you have fresh today. Writing the ADR is, ultimately, a favor you do for your own future memory.