El registre de decisions d'arquitectura: per què el teu equip en necessita un
Tots els equips d'enginyeria han viscut aquesta conversa. Un desenvolupador obre un mòdul, es queda mirant una implementació que sembla innecessàriament complexa i pregunta: «Per què es va fer així?». Es fa el silenci. La persona que va prendre la decisió va marxar fa vuit mesos. Algú recorda vagament un fil de Slack. Un altre, una sessió de pissarra que ningú no va fotografiar. Ningú no sap explicar el raonament real.
I aleshores l'equip fa una de dues coses. O ho deixa estar per por («alguna raó hi devia haver») i crea un deute tècnic permanent que ningú no gosarà tocar. O ho refactoritza i, sense saber-ho, reintrodueix exactament el problema que la implementació original volia evitar. He vist passar totes dues coses tantes vegades que ja n'he perdut el compte.
Els Architecture Decision Records resolen això. Són una de les pràctiques més senzilles i amb més retorn que un equip d'enginyeria pot adoptar, i la majoria d'equips no la fan servir.
Un ADR és un registre, no una especificació
Un ADR és un document curt —normalment de menys d'una pàgina— que recull una única decisió arquitectònica. No és un document de disseny. No és un RFC. No és una especificació. Només un registre de què es va decidir, per què es va decidir i quines conseqüències se n'esperaven.
El format és deliberadament mínim. L'estructura més estesa, basada en la proposta original de Michael Nygard, té cinc seccions:
- Títol. Un sintagma nominal curt. «Fer servir PostgreSQL per a les dades transaccionals.» «Adoptar event sourcing per al processament de comandes.» «Implementar autenticació basada en JWT.»
- Estat. Proposat, acceptat, obsolet o substituït. Si està substituït, enllaça l'ADR nou.
- Context. Quina és la situació? Quines forces hi entren en joc? Quines restriccions hi ha? Aquí és on captures l'estat del món en el moment de la decisió.
- Decisió. Què hem decidit? Digues-ho clar i sense embuts.
- Conseqüències. Què se'n deriva, d'aquesta decisió? Les bones i les dolentes. Què esdevé més fàcil? Què es complica? Quines restriccions noves crea?
I prou. Cap plantilla de vint pàgines. Cap circuit d'aprovacions. Cap comitè. Un desenvolupador l'escriu, l'equip el revisa i el document viu al repositori, al costat del codi que descriu.
Per què la secció de context ho és tot
La decisió en si normalment és evident mirant el codi. Veus que el sistema fa servir RabbitMQ. Veus que l'autenticació passa per tokens JWT. Veus que la capa de dades segueix un patró d'event sourcing.
El que no pots veure és el perquè. I és al perquè on hi ha tot el valor.
Una bona secció de context retrata el paisatge de la decisió en aquell moment: les alternatives que hi havia, les restriccions amb què treballava l'equip, els compromisos que es van sospesar. Podria sonar així:
«Necessitem una cua de missatges per processar esdeveniments de comandes de manera asíncrona. El volum actual és de 500 missatges per segon, amb una previsió de 5.000 per segon d'aquí a dotze mesos. L'equip té experiència amb RabbitMQ però no amb Kafka. Som quatre i no ens podem permetre la càrrega operativa de gestionar un clúster de Kafka. El nostre proveïdor de núvol ofereix RabbitMQ gestionat, però no Kafka gestionat.»
Sis mesos més tard, quan un enginyer nou pregunti «per què no vam triar Kafka?», la resposta serà allà mateix. Sense arqueologia. Sense escriure per Slack a algú que potser ho recorda o potser no. I, sobretot, quan l'equip sí que creixi fins al punt que Kafka tingui sentit, podrà crear un ADR nou que substitueixi aquest, entenent perfectament què ha canviat.
No totes les decisions mereixen un ADR
No cal un ADR per a cada decisió. Triar entre dues biblioteques de formatació de dates no en justifica cap. El llindar que faig servir: si la decisió és difícil de revertir, afecta diverses parts del sistema o serà qüestionada per futurs membres de l'equip, escriu un ADR.
Exemples de decisions que sempre n'haurien de tenir un:
Triar una base de dades. «ADR-003: fer servir PostgreSQL per a dades transaccionals i Redis per a les sessions.» El context recull per què no MongoDB (la flexibilitat d'esquema no compensava els compromisos de consistència en aquest domini), per què no una única base de dades per a tot (les dades de sessió tenen patrons d'accés fonamentalment diferents) i quines implicacions operatives té.
L'enfocament d'autenticació. «ADR-007: implementar autenticació stateless basada en JWT amb refresh tokens.» El context explica per què no autenticació amb sessions (el sistema ha de suportar diversos tipus de client, mòbil inclòs), el compromís de no poder revocar tokens a l'instant i l'estratègia de mitigació (caducitat curta més rotació de refresh).
El patró de comunicació entre serveis. «ADR-012: REST síncron entre serveis per a les lectures, esdeveniments asíncrons per a les escriptures.» El context recull per què no una arquitectura totalment orientada a esdeveniments (l'equip encara no en té l'experiència i el sistema no és prou complex per justificar-ne la càrrega operativa) i quan toca revisar la decisió.
La tria de serveis de tercers. «ADR-015: fer servir Stripe per al processament de pagaments en lloc de construir una integració a mida amb l'API del banc.» El context documenta la comparativa de costos, el compromís del vendor lock-in i les capacitats concretes que van decantar la decisió.
Els ADR viuen al repositori, no al wiki
Això és innegociable: els ADR viuen al repositori de codi. Ni a Confluence, ni a Google Docs, ni a Notion. Al repositori, en un directori com /docs/adr/ o /adr/, versionats al costat del codi que descriuen.
Les raons són pràctiques: són fàcils de trobar (són allà mateix quan un desenvolupador treballa al codi), estan versionats (Git et regala l'historial i el blame), viatgen amb el codi (fes un fork del repositori i les decisions hi van incloses) i es revisen com el codi (els ADR passen per pull request, cosa que hi afegeix encara més context).
Numera'ls seqüencialment: 0001-use-postgresql-for-transactional-data.md, 0002-adopt-jwt-authentication.md. La numeració crea una línia de temps que explica com ha evolucionat l'arquitectura.
El cost de no tenir ADR
L'absència d'ADR crea tres problemes concrets i cars:
Coneixement tribal. Les decisions arquitectòniques viuen al cap de qui les va prendre. Quan aquestes persones marxen —i marxaran—, el coneixement marxa amb elles. L'equip que queda hereta una arquitectura que no acaba d'entendre, i la tracta com a sagrada (no toca allò que no entén) o com a prescindible (refactoritza sense conèixer les restriccions).
Debats que es repeteixen. Sense un registre de per què es va prendre una decisió, els equips tornen a les mateixes discussions cada pocs mesos. «Hauríem de passar a Kafka?» es debat tres cops l'any perquè ningú no recorda que l'equip ja ho va avaluar i ho va descartar per raons concretes i documentades. Cada debat crema hores d'enginyeria sènior i genera frustració.
Fricció en la incorporació. Algú que s'incorpora a un equip sense ADR ha de reconstruir tota la lògica arquitectònica a partir del codi, de missatges dispersos de Slack i del que l'equip sigui capaç de recordar en explicacions improvisades. He vist períodes d'incorporació allargar-se de setmanes a mesos només per la falta de context arquitectònic.
Com començar sense burocràcia
L'error més gran que cometen els equips amb els ADR és tractar-los com un exercici burocràtic. Creen plantilles elaborades, comitès de revisió i circuits d'aprovació. I llavors ningú no els escriu, perquè l'esforç no compensa.
Comença pel mínim:
- La pròxima vegada que el teu equip prengui una decisió arquitectònica significativa, demana a qui l'ha impulsada que dediqui vint minuts a escriure-la en el format de cinc seccions.
- Posa-la en un PR. Revisa-la com si fos codi. Fusiona-la. Ja tens el primer ADR.
- Repeteix-ho amb les quatre decisions significatives següents.
Al cinquè ADR, l'equip començarà a citar els anteriors a les discussions. «Això és el mateix compromís que vam recollir a l'ADR-003.» Aquest és el moment en què la pràctica s'aguanta sola: quan l'equip en veu el valor en el seu propi flux de treball, no perquè ho digui un document de procés.
A Conectia hem vist que els ADR marquen una diferència especialment gran en equips distribuïts. Quan els nostres enginyers sènior s'incorporen a l'equip d'un client, els ADR existents els permeten entendre la lògica arquitectònica en qüestió de dies, no de setmanes. I quan n'aporten de nous, sumen a la memòria institucional d'una manera que sobreviu a qualsevol persona concreta. És una d'aquestes pràctiques petites que, amb el temps, es converteixen en un avantatge competitiu seriós per a l'organització d'enginyeria.
El millor moment per començar a escriure ADR era quan vau prendre la primera decisió arquitectònica. El segon millor moment és ara.
Estàs construint un equip que prengui decisions arquitectòniques sòlides i les documenti? Parla amb un CTO: els nostres enginyers sènior de LATAM porten la disciplina de la decisió estructurada a la teva base de codi des del primer dia.
