Parecen no haberme escuchado cuando se los dije

Los acuerdos verbales se los lleva el viento apenas algo sale mal, y el desarrollador que no dejó nada por escrito termina cargando la culpa. Qué es un ADR, para qué sirve, cómo se estructura y cómo se nombra.

Empezás el día, entrás a esa daily bendita, y arranca el diálogo de siempre.

—¿Por qué se hizo de este modo?

(En tu intento frustrado número diez, le contestás lo mismo al TL.)

—Fue una decisión que acordamos entre nosotros dos y los arquitectos.

(El TL finge demencia.)

—Como sea, hay que hacerlo de esta otra forma.

(Te quedás callado, mirando, respirando para no explotar.)

—Ya está hecho, pero bueno, ya fue. Lo hago de nuevo.

El feature estaba a punto de salir cuando cayó la bomba de tiempo: un refactor no planificado que corrió la entrega.

Esto no le pasó a una sola persona en un solo lugar. Es una escena compuesta — un poco de lo que viví, un poco de lo que me contaron colegas de otros equipos. Los detalles cambian; lo que se repite es el patrón.

#El desarrollador cargó con todo

El único que tenía tracking de lo conversado era el desarrollador. El TL se desentendió y no reconoció nada. Los arquitectos, que habían dado el visto bueno de palabra, empujaban como si nunca hubieran dicho una palabra al respecto.

El impacto lo sufrió el desarrollador. La culpa, también: el equipo lo señaló "por hacer las cosas mal".

#El veto verbal

El problema no fue lo que se dijo, sino que se quedó solo en eso: dicho, nada más — nunca escrito. Las palabras se las lleva el viento, y a quien acuerda de palabra le conviene exactamente eso: que no quede nada anotado. Porque cuando algo sale mal, esa misma persona se pone a moldear la realidad y cuenta una versión que le resulta favorable.

Nadie aprobó nada. Nadie vio nada. Nadie propuso nada. El desarrollador no siguió lo pactado — sí lo siguió, pero eso también se niega.

En otras palabras: sin un registro que lo contradiga, la última versión de la historia es la que queda — y esa versión la escribe quien decidió de palabra, no quien ejecutó la decisión.

#Por qué a nadie de arriba le conviene que quede escrito

Un día, agotado, ese desarrollador propuso escribir un documento. Ni el TL ni los arquitectos lo impulsaron — al contrario, lo frenaron.

No hace falta pensar que lo hacen con mala intención. Es más simple que eso: el sistema no premia a quien deja constancia, premia a quien mantiene la ambigüedad. Un TL o un arquitecto que decide de palabra conserva el margen para decir "yo nunca dije eso" si algo sale mal después. Su criterio queda protegido — nunca tiene que defenderlo por escrito ni hacerse cargo cuando falla. Mientras tanto, quien queda expuesto es quien ejecutó la decisión sin nada firmado.

Ese incentivo protege el ascenso de quien decide de palabra, y perjudica el de quien la ejecuta y después carga con la culpa. No es una conspiración — es lo que pasa cuando el costo de una mala decisión lo paga otra persona.

#Para esto existen los ADR

Un ADR (Architecture Decision Record) es exactamente lo que ese desarrollador necesitaba: un documento corto que registra una decisión de arquitectura, quién la tomó, por qué, y qué alternativas se descartaron.

No reemplaza la conversación — la conversación sigue pasando en la daily, en el call, en el pasillo. Lo que hace el ADR es que, después de esa conversación, quede algo que nadie pueda reescribir con el diario del lunes.

El formato que uso está inspirado en el que popularizó Michael Nygard — le agregué el plazo de aprobación porque, en la práctica, es lo que más me salvó.

#Cómo se estructura

# 0007. Usar concurrencia optimista para actualizar inventario

## Estado
Propuesto — plazo de aprobación: 2026-08-09 EOD. Sin respuesta a esa fecha = aprobado.

## Quiénes decidieron
- Jane Doe (Tech Lead)
- Juan Pérez, Ana Torres (Arquitectura)
- Vos (autor/a de este ADR)

## Contexto
Qué disparó esta decisión, qué restricciones había, por qué había que resolverlo ahora.

## Opciones evaluadas
| Opción | Pros | Contras |
|---|---|---|
| A. Lock pesimista | Simple, sin conflictos | Bloquea, no escala |
| B. Concurrencia optimista | Escala, no bloquea | Hay que manejar conflictos |

## Decisión
Cuál se eligió y por qué, en un párrafo.

## Consecuencias
Qué se vuelve más fácil, qué se vuelve más difícil, qué deuda queda.

Cinco piezas hacen el trabajo: quién decidió, qué contexto había, qué opciones se compararon, qué se eligió y en qué estado está la aprobación. El resto es forma.

#Cómo se nombran y dónde viven

Un ADR no es un documento suelto en un Google Doc que nadie vuelve a abrir — vive en el repo, versionado como el resto del código.

• Carpeta: docs/adr/ (o docs/decisions/, cualquiera de las dos convenciones sirve mientras el equipo la respete).
• Nombre de archivo: número secuencial de cuatro dígitos + título corto en kebab-case. Ejemplo: 0007-usar-concurrencia-optimista-inventario.md.
• Los números nunca se reutilizan ni se reordenan, aunque un ADR se rechace.
• Un ADR aceptado es inmutable. Si la decisión cambia más adelante, no se edita el archivo viejo — se escribe un ADR nuevo que lo reemplaza, y el viejo pasa a estado "Reemplazado por ADR-00XX".

Esa numeración secuencial es lo que convierte a la carpeta en una línea de tiempo: cualquiera puede leer, en orden, cómo evolucionó la arquitectura y por qué.

#Poné un plazo, y mandalo por mail

Esto lo aprendí a los golpes: un ADR sin plazo de aprobación se queda flotando para siempre en un canal de Slack que nadie vuelve a leer.

Lo que a mí me funcionó: mandar el ADR por mail (no por chat) a todos los que tienen que aprobarlo, con una fecha límite explícita — 48 horas es razonable. Si no hay objeción para esa fecha, se avanza con lo propuesto.

El silencio también es comunicación. Y a diferencia del "sí" verbal en una call, un mail con fecha y destinatarios no se puede negar después.

#Impulsalo igual, aunque no te lo pidan

Escribir esto lleva una mañana, a veces más. Y es realista esperar que ni el TL ni los arquitectos lo empujen — no porque estén en contra del ADR en sí, sino porque, como vimos, el incentivo de dejar todo en gris sigue siendo suyo. Eso no cambia solo porque el ADR sea una buena práctica: una práctica profesional no se adopta porque sea correcta, se adopta cuando alguien la sostiene en contra de ese incentivo.

Ese alguien podés ser vos. No como gesto heroico, sino porque es la forma más barata de resolver el problema de fondo: dejar de depender de la memoria ajena para que tu trabajo se sostenga. Si encontrás a alguien más en el equipo empujando lo mismo, sumate — un ADR protege a todos los que participaron de la decisión, no solo a quien lo escribió.

Tres meses después, cuando haya que reconstruir por qué se decidió algo, ese documento va a tener la respuesta. No hace falta levantar la voz para defenderte: el documento ya la tiene.

#adr #architecture #decision-making #documentation