El 2011, Michael Nygard va escriure que «una de les coses més difícils de seguir durant la vida d'un projecte és la motivació darrere de certes decisions». Quasi quinze anys després, la frase descriu un problema nou: l'agent de programació que entra al teu repositori hi arriba sense aquesta motivació i no té a qui preguntar-la.
Aquesta peça defensa una tesi senzilla: quan un agent entra en un repositori, el primer que cal escriure no és un prompt millor. Són les decisions que no es poden revertir sense cost, amb el seu context i les alternatives descartades, al repositori i allà on l'agent les llegeixi.
El que el codi no diu
El codi diu què fa el sistema. No diu per què té aquesta forma: per què hi ha una cua on semblaria que n'hi hauria prou amb una crida directa, per què aquell servei és l'únic que escriu a la base de dades o per què es va descartar l'opció que avui sembla òbvia. Aquest perquè sol viure al cap de dues o tres persones.
Un desenvolupador nou el recupera preguntant. Benjamin Cane, que escriu sobre arquitectura i agents de programació, ho planteja sense embuts el maig de 2026: a diferència dels enginyers, els agents no reben context de les converses de passadís, d'acompanyar altres persones ni del coneixement tribal. Només saben el que es captura.
El dilema de Nygard, a velocitat d'agent
Nygard descrivia què li passa a qui hereta un projecte sense conèixer-ne les decisions: o les accepta a cegues, o les canvia a cegues. La seva conclusió és que convé evitar les dues coses. Un agent és exactament en aquesta posició, amb una diferència: actua de pressa. Si accepta a cegues, repeteix un patró la raó del qual ja no existeix. Si canvia a cegues, desfà una decisió que algú va prendre per un motiu.
La guia d'arquitectura de Microsoft Azure ho diu d'una altra manera: una decisió que es pren però mai es registra probablement s'oblidarà, cosa que porta a debats repetits o a canvis posteriors que contradiuen sense saber-ho la intenció original.
Un prompt millor no substitueix el perquè. Si la raó d'una decisió només és al cap de l'equip, l'agent haurà d'endevinar-la.
Què mereix un registre, i com és
No tot mereix un registre. Microsoft recomana incloure només les decisions que afecten l'estructura del sistema, els seus atributs de qualitat clau o que són difícils de revertir, amb les alternatives que es van descartar. Nygard proposa un format curt, d'una o dues pàgines, numerat de forma correlativa i amb cinc parts:
| Part del registre | Què respon | Per què la necessita l'agent |
|---|---|---|
| Títol | De quina decisió es tracta, en una frase nominal | Per trobar-la abans de tocar aquella part del codi |
| Estat | Proposta, acceptada, obsoleta o substituïda | Per no seguir una decisió que ja es va canviar |
| Context | Quines forces i restriccions hi havia | Per saber si encara existeixen |
| Decisió | Què es va decidir i quines alternatives es van descartar | Per no proposar de nou el que ja es va descartar |
| Conseqüències | Què es guanya i què s'accepta perdre | Per saber què es trenca si es canvia |
Estructura de Michael Nygard (2011); la columna de l'agent és elaboració pròpia d'onext
Un exemple il·lustratiu, inventat i sense relació amb cap client:
- Títol: les comandes s'escriuen només des del servei de comandes.
- Estat: acceptada.
- Context: diversos serveis escrivien a la mateixa taula i les dades arribaven inconsistents.
- Decisió: un sol servei escriu; la resta publica esdeveniments. Es va descartar una base de dades per servei pel cost d'operar-ne tantes.
- Conseqüències: un canvi a comandes obliga a coordinar-se amb el servei de comandes. S'accepta aquesta fricció.
Amb això al davant, un agent a qui es demana «escriu la comanda des del servei de facturació» hauria de poder detectar que xoca amb la decisió i aturar-se a consultar. Sense això, no té manera de saber-ho.
Una altra regla de la guia de Microsoft ajuda l'agent: els registres acceptats no s'editen. Si una decisió canvia, se n'escriu un de nou que substitueix l'anterior i s'enllacen, de manera que queda la història de per què va canviar el rumb.
On posar-les perquè l'agent les llegeixi
Cane recomana guardar-les a Git, al costat del codi, perquè així tenen versions, revisió i validació automàtica. Si l'arquitectura abasta diversos serveis i repositoris, proposa un repositori central d'arquitectura que s'afegeix com a directori addicional en executar l'agent. I si ja viuen en una wiki, un servidor MCP (Model Context Protocol) pot servir-les a l'agent, a costa de més infraestructura.
Convé no confondre què fa cada capa. Les instruccions compartides orienten l'agent en el dia a dia, com vam veure a instruccions compartides i curades. El que s'ha de complir s'imposa amb controls, no amb un fitxer, com vam explicar a Claude Code per a equips: context no és control. El registre de decisions és la tercera capa: no ordena res, explica per què les coses són així.
Fins on portar-ho: regles que la màquina comprova
Hi ha qui va més lluny. El març de 2026, un equip d'autors va publicar a InfoQ «Architectural Governance at AI Speed». Proposen convertir cada decisió en una directiva breu que persona i agent puguin interioritzar, i que l'agent comprovi contra el codi. Descriuen el registre de decisions com una «unitat atòmica d'intenció» i assenyalen que, si cada registre s'ha d'aprovar abans d'implementar-se, les persones acaben sent el coll d'ampolla.
Risc Convertir decisions en regles que es comproven soles és una tendència, no una garantia. Les decisions noves i les excepcions continuen necessitant una persona que decideixi i signi, com vam explicar a specs i agents: on es signa.
Per on començar si el codi ja té anys
Microsoft aconsella començar el registre també en projectes que ja existeixen i, si hi ha dades, generar-lo retroactivament a partir de les decisions conegudes. No cal documentar el sistema sencer: es comença per la part que l'agent tocarà, com vam explicar a especificar el codi legacy abans dels agents.
- Llista les decisions d'aquella part del codi que serien cares de revertir.
- Pregunta a qui les va prendre, mentre continuï a l'equip, el context i les alternatives que es van descartar.
- Escriu cadascuna en una o dues pàgines, amb les cinc parts, i guarda-la al repositori.
- Fes que l'agent les llegeixi abans de tocar aquella part del codi, i que una persona revisi qualsevol canvi que les contradigui.
- Quan una decisió canviï, escriu-ne una altra que la substitueixi i enllaça-les.
Això s'aguanta en la resta del mètode. El llindar de què s'especifica i què no, segons el Spec-Driven Development (SDD, desenvolupament guiat per especificacions), el tractem a les plantilles d'SDD ja són gratis, i la xarxa de proves que detecta els errors, a abans de l'agent, la xarxa.
On encaixa onext
A AI-Accelerated Development construïm amb el teu equip el context en què treballa la IA i el procés amb què treballeu. Tots dos es queden a casa teva. Una persona decideix on hi ha risc. El primer pas és un diagnòstic gratuït, i si al diagnòstic no veiem diferència, no hi ha Quick-start.
Preguntes freqüents
Què és un registre de decisió d'arquitectura (ADR)?
És un document curt que anota una decisió d'arquitectura: què es va decidir, en quin context i amb quines conseqüències. Michael Nygard el va proposar el 2011 amb cinc parts: títol, estat, context, decisió i conseqüències.
Per què un agent necessita les decisions per escrit?
Perquè no té a qui preguntar. Benjamin Cane ho resumeix així: a diferència d'un enginyer, un agent no rep context de les converses de passadís, d'acompanyar altres persones ni del coneixement que només és al cap de l'equip. Només coneix el que es captura.
Quines decisions mereixen un registre?
Les que afecten l'estructura del sistema, els seus atributs de qualitat clau o que són difícils de revertir. Microsoft aconsella incloure només aquestes.
Es pot editar un registre ja aprovat?
No convé. La guia de Microsoft el tracta com un registre de només afegir: si una decisió canvia, s'escriu un registre nou que substitueix l'anterior i s'enllacen, de manera que es conserva per què va canviar el rumb.
On es guarden perquè l'agent les llegeixi?
Cane recomana guardar-les a Git al costat del codi, perquè així tenen versions i revisió. Si l'arquitectura abasta diversos repositoris, un repositori central d'arquitectura; si viuen en una wiki, un servidor MCP (Model Context Protocol), a costa de més infraestructura.
Poden les màquines fer complir les decisions sense una persona?
És una tendència: InfoQ proposa convertir cada decisió en una directiva breu que l'agent comprova contra el codi. Les decisions noves, i les excepcions, continuen necessitant una persona que decideixi.
Fonts
- Michael Nygard, «Documenting Architecture Decisions», Cognitect, 15 de novembre de 2011.
- Microsoft Learn, «Maintain an architecture decision record (ADR)», Azure Well-Architected Framework, 10 d'abril de 2026.
- Benjamin Cane, «Your coding agent is missing one thing: architectural context», 28 de maig de 2026.
- Kyle Howard, Christian Johansen, Dana Katzenelson, Brian Rhoten i Warren Gray, «Architectural Governance at AI Speed», InfoQ, 26 de març de 2026.
- Les cites de fonts en anglès estan traduïdes per onext. L'exemple de registre, la columna sobre l'agent i la lectura són elaboració pròpia d'onext; l'exemple és il·lustratiu, inventat i no correspon a cap client.
Bernat López és fundador i CEO d'onext, boutique d'IA. Acompanya equips de desenvolupament i de producte a treballar amb IA amb mètode —especificació abans de programar, una persona que decideix on hi ha risc i Spec-Driven Development— i aplica a la seva pròpia empresa el que proposa: onext funciona amb el seu propi sistema agèntic.
LinkedIn →