Fer el projecte més automatitzable

• Decisions de disseny explícites
• Contractes i tipus
  • El codi com a context
• Tests i CI/CD
• Harness engineering
  • Guies i sensors
  • Quan s’activa
  • Com evolueix l’arnès
  • Contrast governat vs. no governat

Aquest capítol descriu la infraestructura que fa més segura la delegació: decisions explícites, contractes, tests i una verificació automàtica prou fiable per sostenir més autonomia.

Que la delegació autònoma sigui segura per defecte no és qüestió d’encertar el prompt, és qüestió de com està dissenyat el projecte. Tres palanques són especialment rendibles:

• Decisions de disseny explícites: patrons, convencions i fronteres documentades que l’agent pot seguir sense haver d’inferir-les.
• Contractes i tipus: interfícies, tipus i esquemes d’API que descriuen el resultat esperat al codi, no al cap del desenvolupador.
• Tests i CI/CD: una suite que verifica cada canvi sense intervenció manual.
• Arnès i verificació contínua: hooks, sensors i proves de calibratge que detecten regressions, deriva i buits de governança abans que arribin al repositori.

Totes quatre només serveixen de xarxa de seguretat real si s’executen automàticament a cada canvi.

Decisions de disseny explícites

Un projecte on les decisions estructurals estan documentades (patrons, convencions, fronteres entre mòduls) satisfà la primera condició del mode autònom sense haver de repetir-les a cada prompt. ADRs, fitxers d’instruccions de projecte i exemples canònics al codi serveixen el doble propòsit: orienten nous desenvolupadors i donen context a la IA per mantenir la coherència. Les decisions ja estan preses i són accessibles: ni el desenvolupador ni l’agent han d’inferir-les de nou.

El fitxer d’instruccions del projecte hauria d’evolucionar per acumulació de fracassos, no per especulació. Cada línia que hi afegeixes hauria de traçar-se fins a un error concret que ha passat: l’agent va comentar tests, va tocar fitxers fora d’abast, va aplicar un patró que el projecte havia descartat. Quan això passa, no n’hi ha prou de corregir el canvi, cal afegir la regla perquè no es repeteixi. Però el criteri és simètric: no cal documentar el que l’agent ja fa bé per defecte. Afegir regles per comportaments que ja són el default no protegeix res, només infla el fitxer i dilueix les regles que sí que importen. Un fitxer d’instruccions útil és curt i específic: cada línia resol un problema real d’aquest projecte, no un problema hipotètic o genèric.

Un ADR útil per a l’agent no és una descripció del que es va decidir, sinó del que es va descartar i per què. “Usem repositoris en lloc de serveis d’aplicació” diu poc; “usem repositoris en lloc de serveis d’aplicació perquè el domini té lògica de consulta complexa que no volem dispersar” dona a l’agent el criteri per aplicar el patró en casos nous sense desviar-se als defaults que coneix. La mateixa lògica s’aplica al fitxer d’instruccions del projecte: no és un llistat de convencions, sinó un llistat de decisions que l’agent hauria de respectar i que no s’infereixen llegint el codi: les desviacions del framework, els patrons descartats, les restriccions de domini que no apareixen als tipus.

Contractes i tipus

Definir contractes formals (interfícies, tipus, esquemes d’API, fronteres entre mòduls) fa que el resultat esperat estigui descrit amb precisió al codi, no al cap del desenvolupador. Un tipus és una especificació executable; un esquema d’API es pot validar automàticament. Quan l’agent ha de generar codi que encaixi amb aquests contractes, els buits d’especificació queden reduïts mecànicament: no és qüestió de redactar prompts millors, sinó d’haver escrit els contractes al codi.

En la pràctica, la diferència entre un contracte útil i un que l’agent ignorarà és la distància entre la intenció i el codi:

• Una interfície amb mètodes ben nomenats i tipus precisos és un contracte; un mòdul sense interfície pública definida no ho és: l’agent omplirà els buits com li sembli.
• Un esquema d’API declarat amb OpenAPI o GraphQL és verificable automàticament; una API descrita en un README no ho és.

El criteri pràctic: si la violació del contracte produeix un error de compilació o de validació sense que ningú hagi de llegir el codi, el contracte existeix realment.

El codi com a context

Quan el projecte té una estructura estable i un vocabulari limitat, el mateix codi ja fa de context i d’arnès per a l’agent. Les abstraccions bones no només executen bé: també li diuen al model quins conceptes existeixen, com es relacionen i quines decisions no hauria de reinventar.

• Abstraccions estables redueixen la dependència del prompt. Si el model troba límits clars entre mòduls, li cal menys instrucció extra per mantenir-se dins del patró.
• Els tests i els tipus no només detecten errors. També delimiten què vol dir una implementació acceptable, i això fa que la IA generi menys variants plausibles però incorrectes.
• Un codi ben estructurat és un context reutilitzable. Quan el vocabulari del projecte és consistent i acotat, canvia menys la manera com el model interpreta cada tasca.

Per això, millorar l’arquitectura no és només una decisió per a humans. També és la manera més fiable de fer que la IA rendeixi millor sense haver de compensar-la amb prompts cada vegada més llargs.

Tests i CI/CD

La verificació ha de ser simple i fiable. Això depèn de dues peces que es reforcen mútuament: una suite de tests sòlida i una CI/CD que l’executi automàticament a cada canvi.

Però aquestes inversions (documentació, contractes, tests) només es converteixen en una xarxa de seguretat real si s’executen automàticament a cada canvi. Un test que cal recordar de llançar manualment no protegeix res; un contracte que no es verifica a cada commit acaba desincronitzat. El mecanisme que tanca el cicle és la integració contínua (vegeu CI/CD): cada push dispara linters, type checkers, tests i escàners de seguretat, i cap canvi avança si alguna porta falla. Sense CI/CD, l’arnès existeix al repositori però no s’aplica; amb CI/CD, passa a ser la condició per defecte de tot el que es fusiona.

Com més d’aquesta estructura existeixi, més tasques passen de requerir mode Plan o Chat a ser segures en mode Autònom. Invertir en disseny clar, contractes explícits i tests no és només bona enginyeria, és el que converteix la IA d’una eina que cal supervisar constantment en un executor fiable.

Harness engineering

Decisions explícites, contractes i tests creen l’estructura. L’harness engineering és l’extensió natural d’aquesta idea: envoltar l’agent amb les verificacions que fan que l’estructura s’apliqui, i que evolucioni, automàticament.

Quan l’agent s’equivoca, la reacció instintiva és atribuir-ho al model: “aquesta IA no és prou bona per a això”. Però la majoria de fallades repetibles no són limitacions del model: són buits a la configuració. La idea d’envoltar l’agent amb un arnès automatitzat de verificació que atrapi aquests errors s’ha consolidat com a disciplina amb nom propi: harness engineering.

Linters estrictes, type checking, tests de contracte, escàners de seguretat, tot plegat forma un arnès que atrapa els tipus d’error que la revisió humana detecta però que no necessita jutjar. L’arnès no substitueix la revisió: l’allibera. Quan les portes automatitzades ja garanteixen que el codi compila, segueix els tipus, passa els tests i no conté vulnerabilitats conegudes, el revisor humà pot centrar tota l’atenció en el que les portes no poden avaluar: si la solució és la correcta, si l’abstracció aguantarà, si la decisió de disseny encaixa al sistema. Amb eines IA, la necessitat és més urgent: el volum de codi que un agent genera supera el que qualsevol revisor pot llegir línia a línia, de manera que l’arnès passa de ser un complement a la revisió a ser la porta principal de qualitat.

Guies i sensors

Aquest espai es pot ordenar en dues funcions complementàries:

• Guies de feedforward: anticipen el comportament abans que l’agent actuï.
• Sensors de feedback: observen el resultat i provoquen la correcció.

Les guies i sensors també es poden executar de dues maneres:

• Computacionals: deterministes, ràpids i barats; tests, linters, type checking i anàlisi estructural.
• Inferencials: LLMs o agents de revisió semàntica; útils per al judici, però massa cars i variables per convertir-los en el mecanisme principal de cada commit.

Quan s’activa

Un arnès pràctic no comença amb un agent, comença amb eines deterministes: linters, type checkers, tests automàtics i hooks de pre-commit. Són la base més fiable perquè no depenen del model: donada la mateixa entrada, produeixen sempre el mateix resultat. Les eines semàntiques (analitzadors d’AST, detectors de codi mort, validators de cobertura) afegeixen una capa que entén l’estructura del codi sense introduir probabilisme. Els agents entren quan cap de les capes anteriors pot cobrir el que cal verificar: consistència arquitectural, qualitat de documentació, convencions massa matisades per expressar-les com a regla determinista. El principi és el mateix que per a qualsevol delegació (vegeu Codi, eina o agent): prefereix determinista sobre probabilístic, i usa l’agent per al que l’script no pot fer.

Per timing, la regla és clara: pre-commit per bloquejar, CI per repetir i sensors continus per detectar deriva. El que és barat i local ha d’actuar abans; el que és més costós o més global ha de tornar a passar en pipeline; i el que pot degradar lentament (cobertura, dependències, codi mort, convencions que s’erosionen) necessita observació periòdica fora del camí d’un únic canvi.

Com evolueix l’arnès

L’arnès evolueix per dues forces complementàries: creix per cobrir forats nous i es conté perquè no s’infli fins a degradar-se. Cap de les dues sobra.

Creix per acumulació. Cada error que es repeteix és informació sobre on la configuració és incompleta. Quan l’agent comenta tests durant un refactoring, toca fitxers fora de l’abast definit o aplica un patró descartat, la resposta no és acceptar-ho sinó tancar el forat: una regla nova al fitxer d’instruccions, un hook que ho bloquegi, un validador que ho detecti.

Però esperar que l’agent falli és reactiu, i hi ha erosions que no donen símptomes fins que el dany ja és fet:

• una convenció al fitxer d’instruccions que els últims deu PRs han deixat d’aplicar,
• un exemple canònic que referencia funcions que ja no existeixen,
• una restricció de domini que un refactoring ha invalidat sense que ningú actualitzés les instruccions.

Programar un agent perquè escanegi aquests desajustos periòdicament (setmanalment, o en tancar l’sprint) converteix el manteniment en rutina en lloc de descoberta tardana. Alguns equips fan un pas més: deixen que l’agent analitzi els propis resultats i proposi millores (una regla, un hook, una guia que falta), amb el desenvolupador validant-les i automatitzant l’aprovació dels canvis de menor risc.

Però créixer no pot ser l’única direcció. Un arnès que només suma arriba a un punt on cada fracàs hi afegeix una línia i res no en treu mai cap. I aquí torna el mecanisme que ja governa el fitxer d’instruccions (vegeu Decisions de disseny explícites) i el context d’una sessió: el que sobra no queda inert, competeix per l’atenció del model i dilueix el que sí que importa. Un arnès massa carregat no només costa de mantenir: degrada l’agent que havia de protegir.

Per això l’acumulació necessita un contrapès, i el principi que el resol és senzill: l’arnès ha de contenir exactament el que l’evidència demana i res més. Ajuda separar dues coses que es confonen sota la mateixa paraula:

• El que l’arnès sap: regles i validacions que tanquen forats reals. Això sí que creix per acumulació.
• La maquinària de l’arnès: capes d’orquestració, estats, lògica de reintents. Això s’ha de mantenir simple.

El bucle que s’auto-millora és on el contrapès es fa imprescindible: un sistema que genera les seves pròpies regles, si ningú no el modera, fabrica el mateix excés que havia d’evitar. La validació humana no hi és només per filtrar errors, sinó per podar: consolidar regles que se solapen i esborrar les que ja no es tracen a cap fracàs concret. El test abans d’afegir res és el mateix que per al fitxer d’instruccions: si ho esborressis, canviaria res del que l’agent produeix? Si no, és soroll, encara que ho hagi proposat el mateix arnès.

L’arnès no és només una pràctica individual: la seva qualitat reflecteix la cultura d’enginyeria de l’equip. La recerca més rigorosa sobre el tema (el report DORA 2025) és consistent: la IA amplifica el que l’equip ja és. Equips amb CI/CD sòlid, cultura de revisió i bona cobertura de tests canalitzen la velocitat de la IA en guanys reals; equips sense aquestes bases només produeixen bugs més ràpid. L’arnès és la inversió organitzativa que determina de quin costat caus.

Contrast governat vs. no governat

Un exemple concret ajuda a veure per què tot això importa. Mateix endpoint, dues versions:

L’objectiu no és embellir el codi, sinó fer visible la diferència entre un canvi que sembla correcte i un canvi que està governat correctament.

Una manera de calibrar on és el teu projecte: imagina que l’agent fa un canvi incorrecte: viola un patró, trenca un contracte, introdueix una vulnerabilitat coneguda. Quantes d’aquestes coses el sistema les detectaria automàticament, sense que ningú hagués de llegir el codi? Cada resposta “caldria que algú ho veiés” és un forat a l’arnès, i un límit al que pots delegar amb seguretat. No cal omplir tots els forats abans de delegar, però sí tenir-los identificats. També val la pena preguntar quina cobertura té el mateix arnès: quines fallades detecta realment i quines encara depenen d’intuïció humana.