5. ADR: registrar decisiones de arquitectura

Descripción

Si algún documento técnico está hecho a la medida de alguien que todavía no confía en su inglés, es este. Un ADR es corto por diseño, sigue una plantilla fija de cinco campos y usa un vocabulario tan acotado que cabe en una tarjeta. No hay párrafos largos que sostener, no hay que improvisar estructura, no hay que sonar elegante. Hay que llenar cinco casillas con frases cortas y honestas. Un desarrollador de nivel B1 puede escribir un ADR impecable en su primer intento, porque lo que se evalúa no es la fluidez sino el criterio: por qué se tomó esta decisión y qué cuesta.

En esta lección vas a ver qué es un Architecture Decision Record, por qué se escribe corto y por qué —una vez aceptado— no se toca. Vas a aprender la plantilla estándar (title, status, context, decision, consequences) y, más importante para esta guía, el inglés preciso que va en cada campo: el tiempo verbal correcto, la fórmula con la que se abre un contexto, el We will que hace que una decisión suene decidida, y los cuatro estados que marcan el ciclo de vida de una decisión —proposed, accepted, deprecated y superseded by—. Vas a practicar lo más difícil de todo, que no es gramática: escribir las consecuencias negativas sin suavizarlas. Y vas a cerrar escribiendo un ADR real sobre una decisión que ya tomaste en un proyecto tuyo.

Conexión con el módulo: En la lección anterior aprendiste a explicar una arquitectura por escrito —narrar un flujo entre componentes, presentar una alternativa descartada con justicia, escribir para dos audiencias a la vez—. Ese es el músculo largo. El ADR es su contraparte breve: en lugar de explicar cómo funciona todo el sistema, congela una decisión y su costo. Los dos se complementan. En un design doc completo explicas la arquitectura; cuando esa discusión concluye en una elección concreta y con consecuencias, esa elección merece su propio ADR para que dentro de dos años alguien sepa por qué. En la lección siguiente pasarás del documento de decisión al documento de entrada al proyecto —el README—, que es lo primero que un lector externo abre. Aquí todavía estamos escribiendo para el equipo y para el futuro; ahí empezaremos a escribir para quien llega de fuera.

Qué es un ADR (y qué no es)

Un Architecture Decision Record es un documento corto que registra una sola decisión de arquitectura: qué se decidió, en qué contexto, y qué consecuencias trae. Nada más. Su nombre lo dice completo: architecture (una decisión que afecta la forma del sistema, no una línea de código), decision (una elección entre alternativas reales) y record (un registro, algo que queda escrito y fechado).

La analogía que mejor lo captura es la de una entrada de bitácora o la de un asiento contable. Cuando un contador registra un movimiento, no borra el anterior ni lo reescribe: agrega una línea nueva, con fecha, que deja constancia. La bitácora de un barco funciona igual: cada entrada queda, aunque después el rumbo cambie. Un ADR es exactamente eso para las decisiones técnicas. No es documentación viva que se actualiza cada semana —para eso está el README de la lección siguiente—. Es un registro histórico: la foto de por qué el equipo eligió A en lugar de B en el momento en que lo eligió, con la información que tenía entonces.

Y esto responde de una vez la pregunta más común: ¿por qué escribir la decisión si ya la tomamos y ya está en el código? Porque el código te dice qué se hizo, nunca por qué. Seis meses después, alguien —quizá tú mismo— va a mirar esa cola de mensajes, ese caché, esa base de datos elegida, y va a pensar "esto está mal, hay que cambiarlo". Sin el ADR, no tiene forma de saber si fue una decisión pensada con razones que siguen vigentes, o un accidente que nadie revisó. Con el ADR, lee en dos minutos el contexto y las alternativas, y decide con información en vez de adivinar. El ADR existe para tu yo futuro y para la persona que llega cuando tú ya no estás en el proyecto.

Lo que un ADR no es:

• No es un tutorial ni una guía de uso. No explica cómo usar la tecnología que elegiste. Explica por qué la elegiste.
• No es un design doc. El design doc describe todo un sistema o feature; el ADR aísla una decisión puntual dentro de él.
• No es un documento vivo. No se edita después de aceptado (ya veremos por qué).
• No es largo. Un ADR de una página es normal. Uno de tres páginas probablemente esté mezclando varias decisiones que deberían ir separadas.

Por qué corto, y por qué inmutable

Estas dos propiedades son las que hacen del ADR un formato tan amigable, y las dos tienen una razón detrás.

Corto, porque una decisión bien pensada se explica en pocas frases. La plantilla te obliga a la economía: no hay espacio para divagar. Si no puedes decir el contexto en un párrafo y la decisión en dos frases, probablemente todavía no entiendes bien el problema —o estás metiendo dos decisiones en un solo documento—. La brevedad no es un límite de espacio, es una prueba de claridad. Para ti, que escribes en un segundo idioma, es una ventaja enorme: menos texto es menos superficie de error. Cinco frases correctas son más fáciles de lograr que cinco párrafos.

Inmutable, porque un registro que se reescribe deja de ser un registro. Aquí está el punto que más cuesta al principio: una vez que un ADR está en estado accepted, no se edita para cambiar la decisión. Si mañana el equipo decide lo contrario, no vuelves atrás a modificar el ADR viejo. Escribes un ADR nuevo que documenta la nueva decisión, y marcas el viejo como superseded by (reemplazado por) el nuevo. El viejo queda como estaba, para siempre.

¿Por qué tanta rigidez? Vuelve a la analogía del asiento contable, o piénsalo en términos que ya conoces: un ADR aceptado es como un commit en la historia de git. No reescribes commits viejos para arreglar el presente; haces un commit nuevo encima. La historia completa —incluidos los errores— es justamente lo que tiene valor. Si editaras los ADR viejos para que "siempre hubieran dicho lo correcto", perderías la única cosa que un ADR aporta: el rastro honesto de cómo evolucionó el pensamiento del equipo. La persona que llega dentro de dos años no quiere una verdad limpia y retocada; quiere saber qué se probó, qué se descartó y qué se cambió de opinión, para no repetir un experimento que ya falló.

La única edición permitida sobre un ADR aceptado es cambiar su estado (por ejemplo, de accepted a deprecated o a superseded by ADR-0012). El cuerpo —contexto, decisión, consecuencias— se queda intacto.

Qué esperar: la primera vez que quieras "corregir" un ADR viejo vas a sentir que estás dejando un error a la vista. Ese instinto de limpiar es natural, y aquí está equivocado. Escribir el ADR nuevo que reemplaza al viejo no es más trabajo que editar el viejo, y deja algo que el equipo agradece: la cadena completa de por qué A, luego por qué B en lugar de A.

La plantilla: cinco campos y el inglés de cada uno

La plantilla clásica —la de Michael Nygard, la más usada— tiene cinco campos. Nada de misterio. Lo que sí importa para esta guía es el inglés concreto que va en cada uno, porque cada campo tiene su tiempo verbal y su registro. Aquí está el mapa:

Vamos campo por campo.

Title — el titular

El título es una frase nominal (no una oración con verbo conjugado) que nombra la decisión, normalmente con un número de secuencia. Es el titular que alguien lee en un índice para saber si este ADR le interesa.

ADR-0007: Store session state in Redis instead of in-process memory
ADR-0012: Adopt JWT for stateless authentication
ADR-0003: Use PostgreSQL as the primary datastore

Fíjate en el patrón en inglés: verbo en infinitivo sin to al inicio (Store, Adopt, Use), luego el objeto, y cuando ayuda, el contraste con instead of. Corto, concreto, buscable. Evita títulos vagos como Database decision o Auth stuff: no le dicen nada a quien busca meses después.

Status — el estado, con su vocabulario exacto

El estado es una sola palabra que marca dónde está la decisión en su ciclo de vida. Son cuatro, y su inglés es fijo —no los traduzcas ni los inventes, son términos técnicos que todo el mundo reconoce—:

La diferencia entre deprecated y superseded by es sutil y vale la pena tenerla clara, porque es exactamente el tipo de matiz que te preguntan en una entrevista de arquitectura:

• Deprecated: la decisión ya no vale, pero no hay una decisión nueva que ocupe su lugar. Ejemplo: decidiste soportar Internet Explorer 11 y hoy simplemente ya no importa; nadie decidió "en cambio soportamos X".
• Superseded by ADR-0015: existe una decisión nueva, concreta, que reemplaza a esta. Apuntas al número para que el lector siga la cadena. Ejemplo: el ADR-0007 dijo "sesiones en Redis" y el ADR-0015 dijo "en cambio, tokens JWT sin estado". El 0007 no se borra; se marca Superseded by ADR-0015.

En inglés lo escribes literalmente así en el campo:

Status: Superseded by ADR-0015

Y en el ADR nuevo, como cortesía al lector, cierras el círculo con una línea que apunta hacia atrás:

This decision supersedes ADR-0007 (session state in Redis).

El verbo aquí es supersede (reemplazar, dejar sin efecto). ADR-0015 supersedes ADR-0007 = el 0015 deja sin efecto al 0007. Es una de esas palabras que casi solo verás en este contexto; vale la pena memorizarla.

Context — presente simple, hechos y fuerzas

El contexto describe la situación que obliga a decidir: las restricciones, las necesidades, las fuerzas en tensión. Es la parte que tu yo futuro más va a agradecer, porque es donde entiende qué sabías tú en ese momento.

Regla de inglés clave: el contexto va en presente simple, porque describe hechos y fuerzas que son ciertos ahora. No narras una historia en pasado; expones un estado de cosas. Y es descriptivo, neutral, sin todavía tomar partido:

Context:
Our web app keeps session state in each server's memory. We are
about to run multiple instances behind a load balancer. With
in-memory sessions, a user's requests must always hit the same
instance, which forces sticky sessions and breaks when an instance
restarts. We need a session store that all instances can share and
that survives a restart. Expected load is under 5,000 concurrent
sessions. The team already runs Redis for caching.

Observa el vocabulario de fuerzas: we need, forces, breaks when, must always. Son las presiones que justifican decidir algo. Nota también que el contexto todavía no dice la solución: describe el problema y las restricciones (carga esperada, que ya usan Redis) para que la decisión, cuando llegue, se lea como consecuencia lógica y no como capricho.

Decision — We will, y punto

Aquí está la frase más importante de todo el formato, y es una de las más fáciles de decir bien en inglés. La decisión se escribe en voz activa, con el equipo como sujeto, y en futuro de compromiso: We will....

Decision:
We will store session state in Redis, shared across all app
instances. Sessions will expire after 30 minutes of inactivity.
We will use the Redis instance we already operate for caching,
in a separate logical database.

We will store..., We will use.... No We think we should maybe store..., no It was decided that sessions would be stored.... Recuerda la regla de la lección 3 sobre voz activa y sujeto explícito: aquí es donde más rinde. El ADR registra un compromiso; el inglés tiene que sonar comprometido. We will es exactamente ese registro: firme sin ser arrogante. Una decisión escrita en pasiva vaga (it was decided) esconde quién decide y suena a que nadie se hace responsable.

Compara el registro:

Si la decisión todavía está en debate, no fuerces el We will: ese ADR aún está en estado Proposed, y ahí sí es legítimo escribir We propose to.... El We will firme es para cuando el estado pasa a Accepted.

Consequences: el campo que separa a un profesional

Los tres primeros campos casi se llenan solos. El cuarto, consequences, es donde se ve el criterio —y donde la mayoría flaquea, no por el inglés, sino por la tentación de quedar bien.

Las consecuencias son lo que cambia en el mundo por haber tomado esta decisión: lo bueno y lo malo. Y la regla de oro, la que hace creíble a todo el ADR, es esta: las consecuencias negativas se escriben con la misma franqueza que las positivas. Un ADR que solo lista beneficios no es un registro, es un folleto de ventas, y nadie confía en él.

Esto es contraintuitivo y hay que decirlo claro: escribir el costo de tu propia decisión no te hace ver débil; te hace ver senior. Quien entiende de verdad una tecnología sabe exactamente qué sacrifica al elegirla. Ocultar el costo no lo elimina —solo garantiza que estalle más tarde, cuando ya nadie recuerde que era un riesgo conocido—. La persona que dentro de un año choque con esa limitación va a agradecer enormemente encontrarla escrita, en vez de descubrir que a nadie se le ocurrió mencionarla.

El error de inglés (y de actitud) más común aquí es suavizar. El español a veces envuelve el problema en algodón, y traducido literal queda en un inglés lleno de might, slightly, a bit, could potentially que le quita el filo a la advertencia. Compara:

Fíjate en el patrón de la columna correcta: nombra el costo concreto, cuantifica cuando puedes (~1ms, under 5,000), y usa presente/futuro directo (adds, must, now need) en lugar de condicionales apilados. No estás siendo negativo; estás siendo exacto. Un buen bloque de consecuencias mezcla las dos caras sin esconder ninguna:

Consequences:
Positive:
- All app instances share session state. We can scale horizontally
  without sticky sessions.
- Sessions survive an app restart. Users stay logged in during deploys.
- We reuse infrastructure the team already runs.

Negative:
- Redis becomes a hard dependency. If Redis is down, no one can log in.
  We must treat it as a critical service, not a best-effort cache.
- Every authenticated request makes a network call to Redis, adding
  ~1ms of latency per request.
- Developers must run Redis locally to start the app. We will document
  this in the README and provide a docker-compose file.

Neutral:
- Session data is now visible in Redis. We must not store secrets in it.

Ese último punto, bajo Neutral, muestra algo útil: no todo es bueno o malo, a veces es solo una consecuencia que el lector debe conocer. Y observa que la consecuencia negativa a menudo genera trabajo futuro —documentar en el README, dar un docker-compose—; nombrarlo aquí es lo que convierte el ADR en algo accionable y no en una queja.

Qué esperar: la primera vez que escribas las consecuencias negativas de tu propia decisión vas a sentir que estás dándole municiones a quien quiera criticarla. Es al revés. Un ADR que reconoce sus costos por adelantado desarma la crítica: ya no hay un "no pensaste en X", porque X está escrito, cuantificado y con un plan. La honestidad temprana es la mejor defensa que existe.

Un ADR completo, de principio a fin

Aquí está todo junto —la decisión de Redis que fuimos armando— como se vería en un archivo real dentro del repositorio, normalmente en una carpeta docs/adr/ con nombres como 0007-session-state-in-redis.md:

# ADR-0007: Store session state in Redis instead of in-process memory

Status: Accepted
Date: 2026-03-14
Deciders: Backend team

## Context
Our web app keeps session state in each server's memory. We are
about to run multiple instances behind a load balancer. With
in-memory sessions, a user's requests must always hit the same
instance, which forces sticky sessions and breaks when an instance
restarts. We need a session store that all instances can share and
that survives a restart. Expected load is under 5,000 concurrent
sessions. The team already runs Redis for caching.

## Decision
We will store session state in Redis, shared across all app
instances. Sessions will expire after 30 minutes of inactivity.
We will reuse the Redis instance we already operate, in a separate
logical database.

## Consequences
Positive:
- All instances share session state. We can scale horizontally
  without sticky sessions.
- Sessions survive an app restart. Users stay logged in during deploys.
- We reuse existing infrastructure.

Negative:
- Redis becomes a hard dependency for login. If Redis is down,
  no one can log in. We must treat it as a critical service.
- Every authenticated request adds a ~1ms Redis call.
- Developers must run Redis locally. We will add a docker-compose file.

Neutral:
- Session data lives in Redis. We must not store secrets there.

Léelo entero y nota lo que no tiene: no tiene jerga innecesaria, no tiene frases de treinta palabras, no tiene vocabulario avanzado. Tiene presente simple en el contexto, We will en la decisión, y consecuencias honestas con números. Es un documento que un desarrollador B1 escribe bien, y que un ingeniero senior aprueba sin cambios. Ese es el punto de toda la lección: aquí compites por criterio, no por acento.

Errores frecuentes (y su arreglo)

Ejercicios

Ejercicio 1 — Elige el estado correcto

Lee cada escenario y escribe la línea Status: que le corresponde. Recuerda la diferencia entre Deprecated (nada la reemplaza) y Superseded by ADR-NNNN (una decisión nueva y concreta la reemplaza).

1. El equipo decidió en 2023 dar soporte a Internet Explorer 11. Hoy nadie lo usa y nadie tomó una decisión explícita para reemplazar ese soporte; simplemente dejó de tener sentido.
2. El ADR-0007 decía "guardar las sesiones en Redis". El equipo acaba de aprobar el ADR-0015, que dice "en cambio, usar tokens JWT sin estado".
3. El ADR-0003 decidió usar PostgreSQL como base de datos principal. El equipo todavía usa PostgreSQL sin cambios ni planes de reemplazarlo.

Ejercicio 2 — Quítale el algodón a la consecuencia

Estas tres frases están suavizadas igual que las de la tabla de la lección. Reescríbelas en inglés directo: nombra el costo, cuantifica si puedes, usa presente/futuro sin condicionales apilados.

1. This could potentially make onboarding a bit slower for new developers.
2. There might be some additional cost involved in running this.
3. It may be somewhat harder to debug issues in production.

Ejercicio 3 — Escribe el campo Decision

Lee el contexto y escribe la frase de Decision en inglés, en voz activa y con We will.

Context: Our mobile app currently bundles all images at build time, which makes the app 340MB. App store reviews mention the download size as a reason for uninstalling. We need to reduce the app size without rewriting the image-loading code.

Ejercicio 4 — Tu primer ADR sobre una decisión que ya tomaste

No inventes una decisión hipotética. Ese es el error que mata la práctica. Elige una decisión de arquitectura que ya tomaste en un proyecto real —tuyo, del trabajo, de un curso, de un side project—. No tiene que ser grande. Sirve perfectamente: por qué usaste SQLite en vez de PostgreSQL, por qué elegiste Tailwind en vez de CSS a mano, por qué guardaste la config en variables de entorno en vez de un archivo, por qué separaste el frontend del backend. Cualquier bifurcación donde hubo al menos dos caminos y elegiste uno.

Ahora escríbela como ADR, en inglés, siguiendo estos pasos:

1. Title. Frase nominal con la elección y, si aplica, el instead of. Ejemplo: ADR-0001: Use SQLite instead of PostgreSQL for local development.
2. Status. Como ya la tomaste y sigue vigente, es Accepted.
3. Context. En presente simple, describe qué te presionaba a decidir. ¿Cuántos usuarios esperabas? ¿Qué restricciones tenías —tiempo, presupuesto, equipo, infraestructura—? Esta es la parte donde más vas a practicar el we need / it must / the constraint is.
4. Decision. Una o dos frases con We will (o I will, si es un proyecto solo tuyo).
5. Consequences. Aquí está el trabajo de verdad. Escribe al menos un beneficio y al menos un costo real. Fuérzate a nombrar el costo con la misma claridad que el beneficio. Si no se te ocurre ningún costo, no has pensado bien la decisión: toda elección de arquitectura sacrifica algo.

Criterio de que salió bien: dáselo a leer a alguien que no conoce tu proyecto —un compañero de la comunidad, incluso un modelo de IA—. Si con solo ese texto entiende qué problema resolvías, qué decidiste y qué te costó, el ADR funciona. Si te tiene que preguntar "¿pero por qué no usaste lo otro?", tu contexto o tus consecuencias todavía tienen un hueco.

# ADR-0001: Use SQLite instead of PostgreSQL for local development

Status: Accepted

## Context
This is a side project with a single developer and no deployment
yet. We need a database to prototype the data model quickly. We
don't have a server to host PostgreSQL, and installing it locally
adds setup steps for every new contributor. Expected data volume
during development is under 10,000 rows.

## Decision
We will use SQLite for local development and testing. We will
revisit this decision before deploying to production with real
users.

## Consequences
Positive:
- Zero setup: SQLite ships with Python, no server to install or run.
- The whole database is a single file, easy to reset or share.

Negative:
- SQLite does not enforce some constraints PostgreSQL does (e.g.,
  strict typing), so bugs that only show up under PostgreSQL's
  rules may go unnoticed until deployment.
- We must rewrite and test all queries against PostgreSQL before
  going to production; some SQL syntax differs between the two.

Qué esperar: el ejercicio se siente sorprendentemente rápido —quince, veinte minutos— y esa es justamente la lección. Documentar una decisión no es una tarea pesada de fin de proyecto; es un hábito barato que te deja un rastro valiosísimo. Después de escribir tres o cuatro, la plantilla se te vuelve automática y empiezas a pensar en context / decision / consequences incluso antes de sentarte a escribir. Eso, además, es exactamente la estructura mental que te van a pedir en una entrevista de diseño.

Checklist antes de dar por cerrado un ADR

• Una decisión. ¿El ADR trata una sola decisión, no dos disfrazadas de una?
• Title buscable. ¿El título nombra la elección concreta, no un tema vago?
• Status correcto. ¿La palabra de estado es una de las cuatro (proposed, accepted, deprecated, superseded by)?
• Context en presente. ¿Describe las fuerzas actuales sin adelantar la solución?
• Decision decidida. ¿Está en We will, voz activa, sin condicionales tibios?
• Consequences honestas. ¿Hay al menos un costo real, cuantificado y sin suavizar?
• Inmutabilidad respetada. Si esto reemplaza una decisión vieja, ¿escribiste un ADR nuevo y marcaste el viejo superseded by, en vez de editarlo?

Resumen y siguiente paso

Antes de avanzar, deberías poder:

• Explicar en una frase qué es un ADR y por qué se escribe corto e inmutable.
• Llenar los cinco campos de la plantilla (title, status, context, decision, consequences) con el tiempo verbal correcto de cada uno.
• Usar los cuatro estados (proposed, accepted, deprecated, superseded by ADR-NNNN) sin confundir deprecated con superseded by.
• Escribir una decisión en voz activa con We will..., sin pasiva vaga ni condicionales tibios.
• Nombrar al menos un costo real y cuantificado en las consecuencias, sin suavizarlo con might, could potentially o a bit.

Vuelve a la idea con la que abrimos. Si el inglés te da síndrome del impostor, el ADR es el mejor lugar para empezar a producir evidencia de que puedes escribir documentación técnica seria en inglés. No pide fluidez. Pide cinco campos, presente simple para el contexto, We will para la decisión, y el coraje —más que la gramática— de nombrar el costo de lo que elegiste. Todo eso está a tu alcance hoy, con el inglés que ya tienes.

Y hay un beneficio que va más allá del idioma: un repositorio con una carpeta docs/adr/ bien llevada es una de las señales de seniority más creíbles que puedes mostrar sin que nadie te dé permiso. Le dice a quien revisa tu portafolio que no solo escribes código, sino que piensas en decisiones, en costos y en el equipo que viene después. Es criterio hecho texto.

En la próxima lección cambiamos de audiencia. El ADR lo escribes para el equipo y para el futuro; el README lo escribes para el desconocido que abre tu repositorio por primera vez y decide, en treinta segundos, si tu proyecto merece su atención. Mismo principio de lenguaje llano, lector completamente distinto.

Recursos

• Documenting Architecture Decisions — el artículo original de Michael Nygard (2011) que definió la plantilla de cinco campos que usa esta lección.
• adr.github.io — el hub de la organización ADR en GitHub: vocabulario común, plantillas y herramientas para gestionar decisiones de arquitectura.
• architecture-decision-record (Joel Parker Henderson) — repositorio con múltiples plantillas de ADR (Nygard, MADR y otras) y ejemplos reales de decisiones documentadas.
• Architectural decision record process — AWS Prescriptive Guidance — cómo AWS describe el ciclo de vida completo de un ADR, desde Proposed hasta Superseded.
• Maintain an architecture decision record (ADR) — Microsoft Azure Well-Architected Framework — guía de Microsoft sobre por qué el ADR es un registro append-only y qué elementos debe tener cada entrada.