El Registre de Decisions d'Arquitectura: Per Què el Teu Equip en Necessita Un
Tots els equips d'enginyeria han tingut aquesta conversa. Un desenvolupador obre un mòdul, mira una implementació que sembla innecessàriament complexa i pregunta: "Per què es va construir així?" El silenci s'apodera de la sala. La persona que va prendre la decisió va marxar fa vuit mesos. Ningú pot explicar el raonament real.
L'equip fa una de dues coses. O ho deixa tal com està per por ("probablement hi havia una raó"). O ho refactoritza, reintroduint sense saber-ho exactament el problema que la implementació original estava dissenyada per evitar.
Els Architecture Decision Records solucionen això. Són una de les pràctiques més simples i amb major ROI que un equip d'enginyeria pot adoptar, i la majoria dels equips no les fan servir.
Què és Realment un ADR
Un ADR és un document curt — normalment menys d'una pàgina — que captura una única decisió arquitectònica. No un document de disseny. No un RFC. Sols un registre del que es va decidir, per què es va decidir i quines són les conseqüències esperades.
El format és deliberadament mínim. L'estructura més emprada té cinc seccions:
- Títol. Una frase nominal curta.
- Estat. Proposat, Acceptat, Obsolet o Substituït.
- Context. Quina és la situació? Quines forces estan en joc?
- Decisió. Què vam decidir? Expresa-ho clarament.
- Conseqüències. Què se'n deriva d'aquesta decisió? Tant positives com negatives.
Per Què la Secció de Context ho és Tot
La decisió en si mateixa sol ser òbvia mirant el codi. El que no pots veure és el perquè. I és allà on resideix tot el valor.
Un bon context captura el panorama de la decisió en aquell moment: les alternatives que existien, les restriccions sota les quals operava l'equip, els trade-offs que van valorar.
Exemples de Bons Temes per a ADRs
El llindar que faig servir: si la decisió és difícil de revertir, afecta múltiples parts del sistema, o serà qüestionada per futurs membres de l'equip, escriu un ADR.
Exemples:
- Tria d'una base de dades. "ADR-003: Usar PostgreSQL per a dades transaccionals i Redis per a emmagatzematge de sessions."
- Enfocament d'autenticació. "ADR-007: Implementar autenticació stateless basada en JWT amb tokens d'actualització."
- Selecció de servei de tercers. "ADR-015: Usar Stripe per al processament de pagaments."
On Viuen els ADRs
Això és no negociable: els ADRs viuen al repositori de codi. No a Confluence. No a Google Docs. Al repositori, en un directori com /docs/adr/, versionat juntament amb el codi que descriuen.
El Cost de No Tenir ADRs
Coneixement tribal. Les decisions arquitectòniques viuen als caps de qui les va prendre. Quan aquestes persones marxen, el coneixement marxa amb elles.
Debats refets. Sense un registre del perquè, els equips revisen les mateixes discussions cada pocs mesos.
Fricció en l'onboarding. Un nou membre de l'equip ha de fer enginyeria inversa de tota la lògica arquitectònica.
Començar Sense Burocràcia
La pròxima vegada que el teu equip prengui una decisió arquitectònica significativa, fes que la persona que la va impulsar dediqui 20 minuts a escriure-la en format de cinc seccions. Posa-la en un PR. Revisa-la. Fusiona-la. Aquest és el teu primer ADR.
A Conectia, hem vist que els ADRs fan una diferència particularment gran en equips distribuïts. Quan els nostres enginyers sènior s'uneixen a l'equip d'un client, els ADRs existents els permeten entendre la lògica arquitectònica en dies en lloc de setmanes.
Construint un equip que pren sòlides decisions arquitectòniques i les documenta? Parla amb un CTO — els nostres enginyers sènior de LATAM aporten la disciplina de la presa de decisions estructurada a la teva base de codi des del primer dia.
