ADRs per a projectes petits: com documentar decisions tècniques sense burocràcia

Fa uns mesos vaig obrir un projecte personal que portava un any sense tocar. Kotlin amb Spring Boot, una API per a gestió de feeds RSS. Em vaig trobar amb una decisió que no entenia: per què feia servir Redis com a memòria cau de feeds en comptes de la memòria cau en memòria de Spring. El codi funcionava, els tests passaven, però no tenia ni idea de per què havia triat Redis per a un projecte que corre en una sola instància.

Vaig trigar una hora a reconstruir el raonament. Vaig revisar commits, missatges de commit, fins i tot un fil vell de Slack amb mi mateix. Al final vaig trobar el motiu: necessitava persistir la memòria cau entre reinicis per no re-fetchejar tots els feeds en arrencar. Tenia sentit. Però una hora d’arqueologia per a una decisió que hauria ocupat 10 línies de documentació.

Des d’aleshores faig servir ADRs. No la versió enterprise de 3 pàgines amb comitè d’aprovació. Una versió lleugera que funciona per a projectes personals i equips petits. Escriure’l triga 5 minuts. No escriure’l costa hores de confusió futura.

Què és un ADR (sense complicar-ho)

Un Architecture Decision Record és exactament el que diu el nom: un registre d’una decisió d’arquitectura. Ni més ni menys.

No és un document de disseny. No és una spec. No és una justificació corporativa. És una nota breu que respon a quatre preguntes:

1. Quina decisió es va prendre.
2. En quin context es va prendre.
3. Quines alternatives es van considerar.
4. Quines conseqüències té.

Si les specs defineixen què es construirà, els ADRs expliquen per què es va decidir construir-ho d’una manera concreta i no d’una altra.

La relació amb SDD és complementària. La spec diu “el sistema de notificacions envia emails de forma asíncrona”. L’ADR explica “vam triar un sistema d’esdeveniments amb Spring Events en comptes d’una cua de missatges externa perquè el volum previst no justifica la complexitat operacional de mantenir un RabbitMQ”.

Plantilla ADR senzilla

Aquesta és la plantilla que faig servir. Intencionalment mínima:

# ADR-001: [Título de la decisión]

**Estado**: Aceptado | Superseded by ADR-XXX | Deprecated
**Fecha**: YYYY-MM-DD
**Autor**: [nombre]

## Contexto

[Qué problema o situación motivó esta decisión. 2-4 frases.]

## Decisión

[Qué se decidió hacer. Claro y concreto. 1-3 frases.]

## Alternativas consideradas

### [Alternativa A]
- Ventajas: ...
- Desventajas: ...

### [Alternativa B]
- Ventajas: ...
- Desventajas: ...

## Consecuencias

[Qué implica esta decisión. Positivo y negativo. Qué ganas, qué pierdes,
qué deuda técnica asumes.]

Són cinc seccions. Cap hauria de superar un paràgraf excepte les alternatives. Si necessites més d’una pàgina per explicar un ADR, probablement estàs documentant un disseny, no una decisió.

Exemple real: per què Kotlin en comptes de Java per a un microservei

Ompliré la plantilla amb un exemple real d’una decisió que vam prendre en un projecte:

# ADR-003: Usar Kotlin en vez de Java para el servicio de notificaciones

**Estado**: Aceptado
**Fecha**: 2026-03-15
**Autor**: Roger

## Contexto

Estamos creando un nuevo microservicio de notificaciones que se integrará con
el sistema de pedidos existente (Java/Spring Boot). El equipo tiene experiencia
en ambos lenguajes. El servicio será relativamente pequeño (~15 endpoints,
lógica de eventos y plantillas de email) y lo mantendrán 2-3 personas.

## Decisión

Escribir el servicio de notificaciones en Kotlin con Spring Boot 3.x.
El servicio de pedidos existente se mantiene en Java.

## Alternativas consideradas

### Java 21 con Spring Boot 3.x
- Ventajas: consistencia con el servicio de pedidos, menos curva de aprendizaje
  para el equipo, más candidatos si contratamos.
- Desventajas: más boilerplate para DTOs y data classes, null safety manual
  (Optional o anotaciones), corrutinas no nativas.

### Kotlin con Spring Boot 3.x
- Ventajas: data classes reducen boilerplate en DTOs y eventos, null safety
  nativo (importante porque manejamos datos de usuario que pueden venir
  incompletos), corrutinas para llamadas asíncronas al proveedor de email,
  extension functions para mappers limpios.
- Desventajas: un miembro del equipo tiene menos experiencia con Kotlin,
  alguna incompatibilidad menor con librerías Java puras.

### Kotlin con Ktor
- Ventajas: stack 100% Kotlin, más ligero que Spring.
- Desventajas: ecosistema más pequeño, menos tooling, el equipo no tiene
  experiencia con Ktor, integración con el resto de infra (Spring Cloud
  Config, Actuator) requeriría trabajo extra.

## Consecuencias

- El equipo necesita mantener dos lenguajes (Java en pedidos, Kotlin en
  notificaciones). Aceptamos esa complejidad porque el beneficio en
  productividad de Kotlin para este servicio específico lo compensa.
- El miembro del equipo con menos experiencia en Kotlin tendrá pair
  programming durante las primeras 2 semanas.
- Los módulos compartidos (eventos, DTOs comunes) se escriben en Kotlin
  pero son interoperables con Java.
- Si en el futuro migramos el servicio de pedidos a Kotlin, la experiencia
  ganada aquí será útil.

Això es va escriure en 10 minuts. Sis mesos després, quan algú nou pregunti “per què aquest servei està en Kotlin i l’altre en Java”, la resposta està documentada. No cal reconstruir el raonament des de zero.

Quan escriure un ADR (i quan no cal)

No tota decisió tècnica necessita un ADR. Si documentessis cada if arquitectònic, passaries més temps escrivint ADRs que codi. La clau és identificar les decisions que compleixen almenys una d’aquestes condicions:

Sí que necessita ADR

• És difícil de revertir. Triar la base de dades, el llenguatge, el framework, l’estructura de mòduls. Canviar-ho després costa setmanes o mesos.
• Va tenir alternatives raonables. Si hi havia diverses opcions vàlides i en vas triar una per motius específics, aquests motius haurien de quedar documentats.
• Algú et preguntarà per què. Si pots anticipar que un futur membre de l’equip (o el teu jo d’aquí a un any) mirarà aquell codi i pensarà “per què es va fer així”, això és senyal que necessita un ADR.
• Té implicacions a llarg termini. Decisions que afecten rendiment, escalabilitat, costos operacionals, seguretat o mantenibilitat futura.

No necessita ADR

• És una convenció estàndard. “Fem servir REST per a l’API” no necessita ADR si tot el teu stack és REST. És el default.
• És trivialment reversible. Triar entre dues llibreries de logging que fan el mateix i es canvien en 5 minuts no mereix un ADR.
• No va tenir alternatives. Si un requisit tècnic t’obliga a fer servir una tecnologia concreta, no hi ha decisió a documentar. Pots esmentar-ho a la spec.
• Ja està explicat a la spec. Si la spec diu explícitament “farem servir esdeveniments per a comunicació asíncrona” i explica per què, no necessites un ADR que repeteixi el mateix.

En cas de dubte, pregunta’t: si jo me n’anés del projecte demà i algú nou prengués el relleu, li resultaria confusa aquesta decisió. Si la resposta és sí, escriu l’ADR.

On guardar els ADRs

Al repositori. Punt. Igual que les skills, els ADRs viuen al costat del codi que descriuen.

projecte/
├── docs/
│   └── adr/
│       ├── 001-usar-postgresql-en-vez-de-mongodb.md
│       ├── 002-estructura-por-features-no-por-capas.md
│       ├── 003-kotlin-en-vez-de-java-servicio-notificaciones.md
│       ├── 004-redis-para-cache-de-feeds.md
│       └── template.md
├── src/
└── ...

La convenció de noms NNN-titulo-descriptivo.md és simple i funciona. El número dona ordre cronològic. El títol és descriptiu perquè puguis trobar l’ADR rellevant sense obrir cada fitxer.

Avantatges de tenir-los al repo:

• Es versionen amb git. Pots veure l’evolució de les decisions.
• Passen per PR. Un ADR nou es revisa com qualsevol altre canvi.
• Són cercables amb grep/search. No necessites una eina especial.
• Qualsevol persona que cloni el repo hi té accés immediat.
• Estan al costat del codi que afecten, no en un wiki que ningú visita.

Per a projectes amb múltiples repos, cada repo té els seus ADRs específics. Si hi ha decisions que afecten tota la plataforma, poden viure en un repo de documentació central, però això ja és per a equips més grans.

ADRs i agents d’IA: més útils del que sembla

Aquí és on els ADRs encaixen amb el flux de treball amb IA que vinc descrivint en articles anteriors.

Un agent d’IA que treballa amb el teu codi necessita context. Les skills li diuen com escriure codi. Les specs li diuen què construir. I els ADRs li diuen per què les coses són com són.

Això és particularment útil quan l’agent necessita prendre una decisió o quan un desenvolupador li demana una recomanació. Sense ADRs, l’agent proposa el que consideri millor segons el seu entrenament general. Amb ADRs, pot considerar el context específic del teu projecte.

Exemple de prompt que aprofita ADRs:

Contexto del proyecto:
- Skills: backend-conventions.md
- ADRs relevantes:
  - ADR-003: Usamos Kotlin en vez de Java para servicios nuevos
  - ADR-004: Redis como caché para datos que necesitan persistir entre reinicios
  - ADR-007: Spring Events para comunicación entre módulos del mismo servicio

Tarea: Necesito añadir un sistema de caché para las respuestas del LLM en el
servicio de resúmenes. Las respuestas no cambian frecuentemente y son costosas
de generar. Propón una implementación que sea consistente con las decisiones
arquitectónicas existentes.

Amb els ADRs com a context, l’agent proposarà Redis (consistent amb ADR-004) en comptes d’inventar la seva pròpia solució. Farà servir Kotlin (consistent amb ADR-003). I si la comunicació és interna al servei, farà servir Spring Events (consistent amb ADR-007).

Els ADRs converteixen l’agent d’un programador genèric a un programador que coneix el context i les decisions del teu projecte.

ADR per a decisions que ja vas prendre

Un error comú és pensar que els ADRs només serveixen per a decisions futures. En realitat, el major valor immediat és documentar les decisions que ja vas prendre i que avui no tenen explicació.

Si obres el teu projecte i hi ha cinc coses que “funcionen així però ningú sap ben bé per què”, aquests són els teus primers cinc ADRs. No cal que siguin perfectes. És millor tenir un ADR aproximat que no tenir res.

El meu procés per documentar decisions retroactives:

1. Identifica la decisió. Alguna cosa al codi que no és òbvia. “Per què fem servir Redis aquí”, “per què aquest mòdul està separat”, “per què hi ha un cron en comptes d’un trigger”.
2. Reconstrueix el context. Revisa commits, PRs, missatges de Slack, la teva memòria. No cal que sigui perfecte.
3. Escriu l’ADR amb el que sàpigues. Si no recordes les alternatives que vas considerar, escriu les que hauries considerat. Si no recordes exactament per què, escriu la teva millor hipòtesi i marca amb una nota tipus “[reconstruït, pot no ser exacte]”.
4. Marca l’estat. Si la decisió segueix vigent, “Aceptado”. Si ja no té sentit però es manté per inèrcia, “Deprecated” o “En revisió”.

# ADR-004: Redis como caché de feeds RSS

**Estado**: Aceptado
**Fecha**: 2025-04-XX (aproximada, reconstruido retrospectivamente)
**Autor**: Roger

## Contexto

[Reconstruido] El servicio de feeds RSS re-fetches todos los feeds al
reiniciarse. Con ~200 feeds y un rate limit de los proveedores, un reinicio
completo tardaba 15-20 minutos. Necesitaba una caché que persistiera entre
reinicios.

## Decisión

Usar Redis como caché de feeds parsados. TTL de 1 hora por feed.

## Alternativas consideradas

### Caché en memoria (Spring Cache + ConcurrentHashMap)
- Ventajas: cero infraestructura adicional.
- Desventajas: se pierde al reiniciar. Reinicio = re-fetch masivo.

### SQLite/H2 como caché en disco
- Ventajas: persiste sin servicio externo.
- Desventajas: más complejo de implementar, no pensado para TTL nativo.

### Redis
- Ventajas: TTL nativo, persiste entre reinicios, operaciones atómicas, bajo
  overhead.
- Desventajas: un servicio más que mantener (Redis).

## Consecuencias

- Redis añade un componente de infraestructura al deploy (docker-compose).
- El servicio arranca en segundos en vez de minutos.
- Si Redis no está disponible, el servicio funciona pero sin caché
  (degrada a re-fetch).

Cinc minuts d’escriptura que estalvien una hora d’arqueologia.

Flux complet: specs, ADRs i skills junts

L’ecosistema de documentació d’un projecte amb SDD es compon de tres peces que es complementen:

Cap substitueix els altres. Tots tres junts donen a un desenvolupador (o a un agent d’IA) tot el context que necessita per contribuir al projecte de forma alineada amb les decisions i convencions de l’equip.

Errors comuns amb ADRs

ADRs que són documents de disseny

Si el teu ADR té diagrames de seqüència, pseudocodi detallat i seccions de 500 paraules, no és un ADR. És un document de disseny disfressat. L’ADR només captura la decisió i el seu raonament. El disseny detallat va a la spec o a documentació tècnica apart.

ADRs que no esmenten alternatives

Si només escrius el que vas decidir però no quines alternatives hi havia, perds la part més valuosa. El context de “per què no X” sovint és més útil que “per què sí Y”. Quan algú nou proposa canviar a X, pot veure directament per què es va descartar.

ADRs que mai s’actualitzen

Si una decisió ja no aplica perquè el context ha canviat, l’ADR hauria de reflectir-ho. No l’esborris: marca l’estat com a “Superseded by ADR-XXX” i enllaça al nou. Així mantens l’historial de decisions.

No escriure ADRs perquè “és un projecte petit”

Els projectes petits són precisament on més necessites ADRs. En un equip de 20 persones amb processos formals, les decisions es discuteixen en reunions i queden en actes. En un projecte personal o de 2-3 persones, les decisions es prenen al cap d’algú i s’obliden en dos mesos.

Comença avui

Si portes llegint aquest article i estàs pensant “té sentit però no sé per on començar”, aquí va la versió mínima:

1. Crea una carpeta docs/adr/ al teu projecte.
2. Copia la plantilla que he mostrat més amunt a docs/adr/template.md.
3. Pensa en una decisió del teu projecte que no sigui òbvia. La primera que et vingui al cap.
4. Escriu l’ADR. No busquis la perfecció. 10 minuts com a màxim.
5. Fes commit.

Ja està. Ja tens el teu primer ADR. El següent l’escriuràs quan prenguis la pròxima decisió arquitectònica o quan algú et pregunti “per què es va fer així” i t’adonis que la resposta hauria d’estar escrita.

No és burocràcia. És memòria del projecte. I la memòria, al contrari que les opinions, no canvia amb el temps.