En qualsevol sistema que duri més d'uns mesos sorgeix la mateixa pregunta incòmoda: "per què vam fer això així?". La persona que va prendre la decisió ja no hi és, el context s'ha perdut i l'equip actual dubta entre respectar l'elecció o llençar-la per la borda sense entendre-la. La governança arquitectònica existeix per respondre aquesta pregunta i per assegurar coherència tècnica sense convertir-se en un fre burocràtic. Tradicionalment, governança evocava comitès pesats, documents de centenars de pàgines i un "arquitecte cap" que aprovava tot. Avui busquem el contrari: una governança lleugera, distribuïda i basada en decisions documentades de forma senzilla. L'eina estrella d'aquest enfocament són els Architecture Decision Records (ADR). En aquesta lliçó veurem què és la governança lleugera, com escriure ADR amb una plantilla, com funcionen els comitès d'arquitectura moderns i com definir estàndards que ajudin en comptes d'estorbar.

1. Què és la governança arquitectònica
2. Governança pesada vs lleugera
3. Architecture Decision Records (ADR)
4. Plantilla d'ADR
5. Exemple complet d'ADR
6. Comitès d'arquitectura moderns
7. Estàndards i guies (golden paths)
8. Errors Comuns i Consells
9. Exercicis
10. Conclusió

La governança arquitectònica és el conjunt de pràctiques que asseguren que les decisions tècniques d'una organització siguin coherents, estiguin alineades amb els objectius de negoci i es mantinguin en el temps. Cobreix tres preguntes:

• Qui decideix? Com es distribueix l'autoritat tècnica.
• Com es decideix? El procés per prendre i documentar decisions.
• Com s'assegura el compliment? Com es verifica que el que s'ha decidit es respecta.

L'objectiu no és controlar la gent, sinó reduir el cost de la coherència: que un equip no reinventi la roda, que les decisions importants no es prenguin a la lleugera i que el coneixement sobrevisqui a la rotació de persones. Una bona governança és invisible quan funciona i dolorosa només quan falta.

La governança lleugera no significa "cadascú fa el que vol". Significa moure la decisió al lloc on hi ha el coneixement (l'equip que construeix), però exigint que les decisions rellevants es documentin i es verifiquin. El comitè passa de porter a facilitador.

Un Architecture Decision Record (registre de decisió arquitectònica), idea popularitzada per Michael Nygard el 2011, és un document curt que captura una decisió arquitectònica significativa: el context en què es va prendre, la decisió en si i les seves conseqüències. Característiques clau:

• Un per decisió. No és un document mestre, sinó una col·lecció de fitxes petites.
• Immutable. Un ADR no s'edita un cop acceptat; si la decisió canvia, se n'escriu un de nou que substitueix l'anterior (estat "Reemplaçat per ADR-00X").
• Versionat amb el codi. Viu al repositori, normalment a docs/adr/, perquè evolucioni al costat del sistema i es revisi en els pull requests.
• Breu. Una o dues pàgines. Si necessites més, probablement siguin diverses decisions.

Què mereix un ADR? Decisions que són costoses de revertir o que afecten molts: triar un estil arquitectònic, una base de dades, un protocol de comunicació, una política d'autenticació, etc. No documentis amb ADR el nom d'una variable.

Una plantilla minimalista i molt utilitzada, en Markdown:

Repassem cada secció i per què importa:

• Estat: permet saber d'un cop d'ull si la decisió segueix vigent. El flux típic és Proposat → Acceptat; més endavant pot passar a Reemplaçat.
• Context: és la part més valuosa d'aquí a dos anys. Explica les forces que van portar a decidir. Sense context, una decisió correcta sembla arbitrària.
• Decisió: l'afirmació concreta. En veu activa ("Decidim fer servir PostgreSQL") perquè no hi hagi ambigüitat sobre què es va triar.
• Conseqüències: l'honestedat aquí és or. Tota decisió té un cost; anomenar-lo evita que l'equip futur se senti enganyat.
• Alternatives considerades: demostra que es va pensar. Evita que algú proposi d'aquí a un any una opció ja descartada per bones raons.

Observa com l'exemple aplica la plantilla amb dades reals: el context narra un problema concret (timeouts en campanya), la decisió és inequívoca (esdeveniments via RabbitMQ) i les conseqüències no amaguen el cost (consistència eventual, necessitat d'idempotència). Qualsevol que llegeixi això d'aquí a dos anys entendrà per què Facturació és asíncrona i no intentarà "arreglar-ho" tornant-la síncrona.

El comitè d'arquitectura no ha desaparegut, però ha canviat de paper. En el model modern sol organitzar-se com un ART (Architecture Review Team) o, més informalment, una guild d'arquitectura:

• Composició rotatòria: no només "arquitectes", sinó enginyers sènior de diversos equips. Evita la torre de vori i reparteix el coneixement.
• Funció assessora, no de porter: revisa ADR proposats, aporta perspectiva transversal i detecta encavalcaments o incoherències, però rarament bloqueja.
• Cadència lleugera: reunions curtes i freqüents, idealment sobre ADR ja escrits (es revisa un document, no s'improvisa en una pissarra).
• Decisions per consens informat: si no hi ha acord, l'equip que assumeix el cost decideix, deixant-ho registrat.

El flux del diagrama integra la governança en el procés de desenvolupament: l'ADR es proposa com un pull request, es discuteix com qualsevol canvi de codi i, en aprovar-se, queda versionat. La governança deixa de ser un esdeveniment a part i es torna part de la feina diària.

Perquè els equips tinguin autonomia sense caos, l'organització defineix estàndards i golden paths (camins daurats):

• Estàndard: una regla que s'ha de complir ("tota API REST exposa OpenAPI", "els logs surten en JSON"). Idealment, verificable de forma automàtica.
• Golden path (camí daurat): la forma recomanada i suportada de fer una cosa comuna (plantilla de microservei, pipeline de CI/CD llest). No és obligatori, però és el camí fàcil: qui se'n surt, assumeix el cost.
• Guia: recomanació sense obligatorietat ("preferim injecció per constructor").

La clau és distingir el que és obligatori i automatitzable del que és recomanat. Com més es pugui verificar amb eines (linters, fitness functions, plantilles), menys cal vigilar a mà. Un bon estàndard no es documenta en un PDF: es codifica en una comprovació que fa fallar el build si s'incompleix.

Aquest fragment converteix un estàndard de seguretat ("no executar com a root") en una comprovació que fa fallar el build si el Dockerfile no inclou una directiva USER. És governança executable: ningú no ha de recordar la regla ni revisar-la a mà, perquè el pipeline la imposa. Veurem aquesta filosofia portada a l'extrem en la propera lliçó sobre fitness functions.

• Documentació que ningú no llegeix ni manté. Un wiki gegant i obsolet és pitjor que res. Prefereix ADR curts versionats amb el codi.
• Editar ADR acceptats. Trenca la traçabilitat històrica. Si la decisió canvia, escriu un ADR nou que reemplaci l'anterior.
• Comitè que bloqueja tot. Si cada decisió necessita aprovació prèvia d'un òrgan central, el lliurament es paralitza. El comitè assessora; l'equip decideix i documenta.
• Documentar decisions trivials. Reserva els ADR per a decisions cares de revertir o que afecten molts. No documentis el format d'una data amb un ADR.
• Estàndards només sobre paper. Si un estàndard no es pot verificar automàticament, s'incomplirà en silenci. Codifica'l sempre que puguis.
• Consell: numera els ADR de forma seqüencial i mai no reutilitzis números. L'històric complet, inclosos els rebutjats i reemplaçats, és part del valor.

Exercici 1. Decideix quines d'aquestes decisions mereixen un ADR i quines no: (a) triar entre REST i gRPC per a la comunicació entre serveis; (b) el nom del paquet arrel; (c) fer servir autenticació amb JWT; (d) l'ordre dels imports.

Exercici 2. Escriu un ADR seguint la plantilla per a aquesta decisió: "l'equip farà servir PostgreSQL com a base de dades principal en comptes de MongoDB". Inventa un context raonable.

Exercici 3. La teva organització vol garantir que tots els serveis exposin un endpoint /health. Ho plantejaries com a guia, estàndard o golden path? Com ho verificaries?

Solució 1. Mereixen ADR: (a) i (c), perquè són decisions costoses de revertir i afecten tots els equips. No mereixen ADR: (b) i (d), que són convencions trivials; van en una guia d'estil o en el linter, no en un ADR.

Solució 2. (Exemple) Estat: Acceptat. Context: necessitem transaccions ACID i relacions fortes entre comandes, línies i clients; l'equip domina SQL i no preveiem dades sense esquema. Decisió: decidim fer servir PostgreSQL com a base de dades principal. Conseqüències: guanyem integritat referencial i transaccions; renunciem a la flexibilitat d'esquema de MongoDB i assumim que dades molt variables requeririen columnes JSONB. Alternatives: MongoDB (descartat: no necessitem esquema flexible i perdríem transaccions multidocument fàcils).

Solució 3. El millor és un estàndard ("tot servei exposa /health") reforçat amb un golden path (la plantilla de servei ja inclou l'endpoint, així complir-lo és gratis). La verificació s'automatitza: un test de contracte en CI que arrenca el servei i comprova que /health respon 200, fent fallar el build si no.

La governança arquitectònica moderna aposta per ser lleugera, distribuïda i executable: moure les decisions a l'equip que té el coneixement, documentar-les amb ADR breus i immutables versionats al costat del codi, i convertir el comitè en un assessor en comptes d'un porter. Hem vist com escriure ADR amb una plantilla i un exemple complet, com operen les guilds d'arquitectura i com els estàndards guanyen força quan es codifiquen en comprovacions automàtiques en comptes de quedar-se sobre paper. Aquesta darrera idea —verificar l'arquitectura automàticament— és el pont perfecte cap a la lliçó següent: Fitness Functions i Arquitectura Evolutiva, on aprendrem a escriure proves que comproven que l'arquitectura es manté sana a mesura que el sistema evoluciona.